Support Home > SDK Integration > Android SDK Integration

Android SDK Integration


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

 

Minimum Requirements:

  • Android API Level 9

Integrating the SDK

To integrate your application with the Kochava SDK, simply complete the following steps:

  1. Download and install the Google Play Services library.
  2. Add the Kochava Android SDK .jar file into your application code base.
  3. Update the Manifest file for the Application.
  4. Call the Constructor of the Kochava SDK.

Download and Install Google Play Services

Google Play Services is bundled all together or as individual API packages. The Kochava SDK will work with the complete bundle or with the following individual API packages.

 

Required:

  • Google Mobile Ads

Optional:

  • Google Location and Activity Recognition (if gathering location)

Add the Kochava Android SDK

If using Android Studio add the Kochava SDK .jar file to the “libs” directory of your application. Then update your “build.gradle” dependencies block to include the following before running a gradle sync.


Updating the Application Manifest File

Detailed documentation on Android permissions can be found here.

Please confirm that your AndroidManifest.xml file has the following permissions:

 

Required:

 

Optional:

Location –

If gathering location at least one of the following permissions is required. For Android 6 and above the Kochava SDK will never make a permissions request dialog to the user. Location will only be gathered if permission has already granted.

 

Email –

If gathering user email addresses the following permission is required. For Android 6 and above the Kochava SDK will never make a permissions request dialog to the user. Email addresses will only be gathered if permission has already been granted.

 

Google Play Services:

As part of integrating Google Play Services you must include the version info meta-data into the manifest between the application tags. If you have previously integrated Google Play Services into your app this should already be present.

 

Broadcast Receiver:

Single Receiver –

If the Kochava SDK is the only broadcast receiver in your app that has an intent filter on INSTALL_REFERRER then you will add our broadcast receiver between the application tags as shown.

 

Multiple Receivers –

If you already have a receiver that is listening for the INSTALL_REFERRER, you need to create your own “master” receiver to catch the INSTALL_REFERRER intent and pass it along to the appropriate receivers. Such a solution might look like this:

 

The receiver would be declared in your manifest as follows:

 

NOTE: If you use the above method, you can safely ignore any error message from the SDK warning of a missing implementation of the Kochava broadcast receiver.


Calling the Constructor

By calling the Kochava Constructor (initializing the Feature object), you have completed the basic integration with Kochava. The Constructor should be called somewhere within the start-up logic of your application (such as the onCreate method of your application class or in a Singleton created from the Application class), and you should use only a single instance of the SDK’s Feature object.

The Android SDK has a Constructor that takes a Context object and a HashMap object to contain key/value pairs where the key is the name of the parameter you want to use, and the value is the value of that parameter. Here is a bit of sample code in which the Constructor is initialized with a HashMap. To use the correct key strings use the static Feature.INPUTITEMS class.

 

BEST PRACTICES: Before initializing the SDK make sure you’ve obtained your unique App GUID, as you will need to pass it to the initializer. For more information on obtaining your App GUID, refer to our Locating an App GUID support documentation.

Once you’ve obtained your App GUID it can be passed as the Kochava App ID value during initialization. In the sample code below simply replace “_YOUR_KOCHAVA_APP_GUID_” with your App GUID.

 

Adding IdentityLink Data to the Initialization:

In order to pass your IdentityLink data with the initialization of the library, refer to the following code sample.
 
NOTE: The type of HashMap here is a HashMap, and the datamap object is theHashMap object you create using the initialization method above.

 


Event Methods

Sending Kochava post-install events is not a requirement; to track installation information, you must ONLY call the Constructor. 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 methods 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 persisted and sent individually or in bulk depending on the volume of events collected and instrumented. This is done to separate event collection from event transmission and removes any impact it could make on your application.

 

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

NOTE: For examples of post-install events for Android, refer to our Post-Install Event Examples support documentation.

NOTE: No event pre-registration is required.

 

Standard Events:

Standard events with commonly used parameters may be sent using the eventStandard() method. To instrument a standard event, simply create a new EventParameters object with a chosen EventType and populate only the fields you would like to include with the event, if any. You may then call the eventStandard() method with the EventParameters object to send the event.

 

 

Custom Events:

Custom events allow you to build dynamic event content and may be sent using the event() method. To instrument a custom event, simply send an event name via the eventName parameter. Optionally, you can also send an eventValue. The optional eventValue parameter is used to gather in-app purchase information that can be used for LTV calculation.

Regardless of what is passed in eventName, Kochava’s user dashboard will let you access all the data passed in eventValue for any eventName, and present a count of all times an event passed any given eventName. Note that 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.

 

 

In addition to the standard event tracker, Kochava provides a method called eventSpatial. EventSpatial is similar to the event method, but it offers the ability to send x, y, and z coordinates for tracking positions in 3D space.

 

 

Sending Google Play In-App Purchase Receipts

Similar to the event method, eventWithReceipt sends a name/value pair and the Purchase Data and Data Signature from a Google Play purchase to Kochava servers. For documentation on retrieving the Purchase Data and Data Signature, refer to (Implementing In-app Billing).

After receiving the BUY_INTENT intent from the purchase, you might call eventWithReceipt as follows in your onActivityResult method.

 

NOTE: In order for Kochava to fully validate In-App Purchase receipts you must include your Google Play License Key within the Google Creds of the Partner Configuration UI.


IdentityLink

The IdentityLink feature is used to associate an account identity to an individual device. This is useful in the event that you want to report by an account id and not device identifiers.

 

NOTE: When possible, IdentityLink should be sent with your initializer to ensure that your identity values are always associated with your install. See “Adding IdentityLink Data to the Initialization” above.

 

If the account identify information is not available at the time of initialization, you can call the linkIdentity method as follows:


Deep Linking

Pass deep link events to Kochava using this method: After retrieving the URI you receive from Android, just pass it as a parameter deepLinkEvent and Kochava will register that event specifically as a deep link. You can learn more about deep linking for the Android platform here.


Attribution Data Request

Attribution data can be received from Kochava servers usually in less than 10 seconds from the initial application launch.

 

NOTE: This should only be done if your application makes use of this information, otherwise it causes needless network communication. Attribution will performed server-side regardless of the application requesting the results.

 

You can receive attribution data by a callback to your host app, by asking for the attribution data at any point, or both. You MUST request attribution data from the server when you initialize the library for either of the two approaches above to work.

 

To receive attribution data via a callback, add the following handler to your application:

 

Then, register the handler with the library before you initialize it:

 

To learn what attribution data has been retrieved from the Server at any time, you can call the getAttributionData method.

 

Possible return values from getAttributionData:

  • null – if no attribution data has been received
  • false – if the install was organic
  • a JSON payload containing the attribution data – if the install was non-organic

 

Sample Payload:

 

Possible return values from the callback:

  • false – if the install was organic
  • a JSON payload containing the attribution data – if the install was non-organic

Logging

By default, the Kochava SDK provides error messages to assist in debugging problems you might be having with integrating the SDK into your app. If you would like to turn these off, you can make the following static method call:

 

Additionally, if you are having problems with your integration, you can enable debug logging to possibly gain some insight as to what the problem might be.


Files for Download

Kochava Android SDK Release Notes

Kochava_Android_20170303


Testing the Integration

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

 
 

Last Modified: May 18, 2017 at 3:29 pm