Support Home > SDK Integration > Phonegap Plugin

Phonegap Plugin

DOCUMENT SUPERSEDED: The information that is contained within this document has been superseded. Refer to the current SDK integration support document for the latest integration instructions and procedures.


The Kochava SDK allows advertisers to integrate a single SDK to leverage the hundreds of ad networks and publisher partners via Kochava. This limits the number of 3rd party SDKs required to run a successful user acquisition strategy and greatly reduces complexity during update cycles. Find documentation for other SDKs, plugins, and Server-to-Server Integrations here.


Integrating the Plugin

  1. Download the Kochava PhoneGap SDK and unzip.
  2. Create a PhoneGap project using the Cordova command line tool.
  3. Add the iOS and/or Android platforms to your project.
  4. Navigate to the top folder of your project with a command prompt or terminal, and enter the following (where sdk_path is the location where you unzipped the Kochava PhoneGap SDK plugin):
  5.  

    NOTE: Android Developers – Our plugin includes a dependency on the Google Play Services plugin and will automatically install it with our plugin. Confirm that the exists <top_level_app_folder>/platforms/android folder/com.google.playservices.

     

  6. In pluginscom.kochava.sdkwww edit the kochava.js file set the variables in the initKochava method (shown below) with values which apply to your application.
    • kochava_ios_app_id must be set to the iOS app guid for your application from your dashboard.
    • kochava_android_app_id must be set to the Android app guid for your application from your dashboard.
    • currency (optional – default = ‘usd’).
    • debug (optional – default = false) causes communication between the SDK and Kochava servers to be logged for debugging.  It should be set to false for release builds.
    • request_attribution (optional) must be set to true for the SDK retrieve attribution data from Kochava servers.  See the section on Attribution Data Request for more information.
    • identity_link (optional) provides the opportunity to “link different identities” together.  See the section on IdentityLink for more information.
    • app_limit_tracking (optional – default = false).  See the section on Limit Ad Tracking for more information.

     

  7. Run “cordova build” to build your iOS and/or Android project.

Attribution Data Request

If you indicated in your initializer that you would like to receive attribution data (request_attribution =true, above), you will receive a JSON string via a callback.

  1. Implement the following code in your application’s index.js file’s onDeviceReady method:

 

Sample Payload:

 

At any time, you may also retrieve attribution data via a callback by passing a callback function to the RetrieveAttribution method.


Toggling Debug Logging

Console logging will be OFF by default, unless enabled via either the initial command or the enableConsoleLogging method, which takes only a bool as an argument. If you had enabled console logging when you initialized the library, you can also disable it via this method by passing “FALSE” to it.


IdentityLink

NOTE: Values must be strings.

 

IdentityLink events provide the opportunity to “link different identities” together. For example, you may have assigned each user of your app an internal userid which you want to connect to a user’s service identifier. Using the IdentityLink method, you can send both your internal id and their service identifier connecting them in the Kochava database.

Kochava reports can be output to show additional identity information for devices in the Kochava database so that you can supplement your reports with internal identifiers that are useful to you and your application.

Although you can call the IdentityLink method any time, it is best called just once per data pair being connected, and it is your responsibility to know you have or have not made that connection.


Toggling Limit-Ad-Tracking

Ad tracking will be ON by default, unless disabled via either the initial command or the LimitAdTracking method, which takes only a bool as an argument.


Calling Event Methods

NOTE: After initialization, Kochava can be used to track information.

 

Sending Kochava post-install events is not a requirement. To track installation information, you must ONLY include the Kochava Phonegap plugin. While this is true, many advertisers want to understand and correlate the relationship between conversion and attribution source information with post-install behaviors. This can only be done by tracking post-install events.

Once the Constructor is called, the Kochava event tracking method can be called from anywhere within the application. Events will be coupled with the information sent by the Constructor to report events, based on user device and application information.

Events are not sent immediately to Kochava servers but queued, should the device not have connectivity.

 

NOTE: Event names may not be prepended with an underscore, as that convention is reserved for Kochava system events. (i.e. _INSTALL)

 

No event pre-registration is required. To instrument an event, simply send an event name via the eventTitle parameter. Optionally, you can also send an eventValue.

Uses of the the optional eventValue parameter could be any of the following:

  • Gather in-app purchase information that can be used for LTV calculation.
  • A JSON formatted string, in which you want to track several data points.
  • Another piece of information, paired with the eventTitle.

 

If the string passed in eventValue is all numeric (and may include a decimal point), Kochava will automatically sum all the amounts for the same eventTitle. For example, if you sent the purchase amount of in-app purchases in eventValue and named eventTitle “IAP – Purchase Price”, Kochava would add up all the purchase amounts and sum them as a total for “IAP – Purchase Price”.

Regardless of what is passed in eventValue, Kochava’s user dashboard will let you access all the data passed in eventValue for any eventTitle, and present a count of all times trackEvent passed any given eventTitle.

 

NOTE: If you pass a string of JSON represented data, only the root level (no nested chunks) is stored. Also there exists a limit of 75 total characters passed in eventValue.

 

You can call the tracking method from anywhere in your application. It is called by accessing it through the application’s delegate.

 

NOTE: Import your app delegate’s header file at the top of the file from which you call this method.

NOTE: In the example below, “Detail View” and “product list” are just examples for a particular scenario. Say an app has a large amount of items listed in a UITableView (like the Settings app on the iPhone). The user taps on one of the items in the list to go to a more detailed view. So you want to log that the user went to the more detailed view of the product list (which was the item on the table they tapped on). You might send this pair of events to indicate the user went to a “Detail View” of the “product list”.


Sending App Store Receipts

NOTE: This feature is only supported within iOS, and is in beta testing. Please contact Kochava before implementing this feature

 

Similar to the trackEvent method, a name/value pair representing a purchase event with a Base64 encoded string containing an App Store receipt may be sent to Kochava servers.

 

The App Store receipt should be obtained through your app, Base64 encoded and then sent using the EventWithReceipt method.


Sending Spatial Events

 

Spatial events let you send a title and an x, y, and z coordinate to our server for visualizing your data.

At any time the SpatialEvent may be called.


Deep Linking

After receiving the URI from your application via openURL:(NSURL *)url sourceApplication: in your application delegate, just pass the URL and sourceApplication parameters to the sendDeepLink method. For more information about Deep Linking for iOS, click here.

 

NOTE: Starting with iOS 9, you can take advantage of Apple’s Universal Links. For more information about implementing Universal Links, click here.

 

If you are not using Universal Links, you will need to register the URL scheme, refer to https://developer.apple.com/library/ios/documentation/iPhone/Conceptual/iPhoneOSProgrammingGuide/Inter-AppCommunication/Inter-AppCommunication.html


Kochava Device ID Retrieval

If you would like to retrieve the Kochava Device ID from the SDK for your own use, you can retrieve it by passing a callback function to the GetKochavaDeviceId method.


iBeacons (iOS Only)

NOTE: iBeacon Detection is not included with the standard Kochava SDK , a Phonegap SDK capable of iBeacon detection is available upon request. For further information on iBeacon Detection, contact a Kochava account manager.


Upload to App Store

NOTE: Around April 26, 2014, Apple modified their automatic code validation surrounding the gathering of the Advertising Identifier (IDFA). The following error indicates a problem with this validation process:

 

“Improper advertising identifier [IDFA] usage. Your app contains the Advertising Identifier [IDFA] API but your app is not respecting the Limit Ad Tracking setting in iOS.”

There have been no instances of the Kochava SDK triggering this error. Kochava’s SDK’s IDFA usage complies with Apple’s guidelines, and Kochava adheres to a user’s Limit Ad Tracking setting. Also, Kochava periodically submits apps with our library integrated to ensure that our SDK passes Apple validation.

If this error message appears when you try to submit an app to the app store, alert your Account Manager that you received it, and provide the following information:

  • Version of Kochava’s SDK that you are using.
  • Whether or not you checked YES to answer the question, Does this app use the Advertiser Identifier (IDFA)?
  • Whether or not you checked any of the 3 boxes under: This app uses the Advertising Identifier to (select all that apply).
  • What other tracking/conversion SDKs, if any, you are using in your app.

From this information, we can trouble-shoot.

 

idfauseragreementhd

A. Select the Following


Files for Download

Kochava PhoneGap Plugin Release Notes

 


NOTE: If a superseded version of the SDK is required, contact your Account Management team for more details.


Testing the Integration

For more information on testing the integration with Kochava, refer to our Testing an Integration with Kocahva support documentation.

 
 

Last Modified: Sep 1, 2017 at 5:08 pm