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:
- Download and install the Google Play Services library.
- Add the Kochava Android SDK .jar file into your application code base.
- Update the Manifest file for the Application.
- 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.
dependencies {
compile fileTree(include: ['*.jar'], dir: 'libs')
}
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
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.INTERNET" />
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.
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
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.
<uses-permission android:name="android.permission.GET_ACCOUNTS" />
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.
<application …> <meta-data android:name ="com.google.android.gms.version" android:value ="@integer/google_play_services_version"/> </application>
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.
<application …> <receiver android:name ="com.kochava.android.tracker.ReferralCapture" android:exported ="true" > <intent-filter> <action android:name ="com.android.vending.INSTALL_REFERRER" /> </intent-filter> </receiver> </application>
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:
import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;
import com.kochava.android.tracker.ReferralCapture;
/*
* A simple Broadcast Receiver to receive an INSTALL_REFERRER
* intent and pass it to other receivers.
*/
public class MasterReferrerReceiver extends BroadcastReceiver
{
@Override
public void onReceive(Context context, Intent intent)
{
// Pass the intent to other receivers.
// Pass the intent to the Kochava receiver.
new ReferralCapture().onReceive(context, intent);
}
}
The receiver would be declared in your manifest as follows:
<receiver android:name="YOUR_PACKAGE.MasterReferrerReceiver" android:exported="true"> <intent-filter> <action android:name="com.android.vending.INSTALL_REFERRER" /> </intent-filter> </receiver>
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.
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_APP_GUID_” with your App GUID.
HashMap<String, Object> datamap = new HashMap<String, Object>(); datamap.put(Feature.INPUTITEMS.KOCHAVA_APP_ID ,"_YOUR_APP_GUID_" ); Feature kTracker = new Feature( contextObject , datamap);
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
HashMap<String, String> identityLinkMap = new HashMap<String, String>();
identityLinkMap.put("yourKey", "yourValue" );
datamap.put(Feature.INPUTITEMS.IDENTITY_LINK , identityLinkMap);
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.
kTracker.eventStandard(new EventParameters(EventType.TutorialComplete));
EventParameters eventParameters = new EventParameters(EventType.Purchase);
eventParameters.name("Game Token");
eventParameters.price(1.99f);
eventParameters.quantity(10);
kTracker.eventStandard(eventParameters);
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.
kTracker.event( "InAppPurchase" , ".99");
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.
kTracker.eventSpatial( "a spatial event" , 16, 45, 2342, "spatial extra data");
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.
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
if (requestCode == 10001 && data != null) {
int responseCode = data.getIntExtra("RESPONSE_CODE", 0);
String purchaseData = data.getStringExtra("INAPP_PURCHASE_DATA");
String dataSignature = data.getStringExtra("INAPP_DATA_SIGNATURE");
if (resultCode == RESULT_OK) {
String eventName = "Purchase";
JSONObject valuePayload = new JSONObject();
try
{
valuePayload.put("customer_id", "my internal customer id ");
valuePayload.put("currency", "usd");
valuePayload.put("sum", 0.99);
valuePayload.put("items_in_basket", 1);
valuePayload.put("checkout_as_guest", 0);
String valueString = valuePayload.toString();
// place the Purchase Data and Data Signature into an object to pass to the method
HashMap < String, String > receiptObject = new HashMap < String, String > ();
receiptObject.put("purchaseData", purchaseData);
receiptObject.put("dataSignature", dataSignature);
kTracker.eventWithReceipt(eventName, valueString, receiptObject);
}
catch (JSONException e)
{
Log.d(TAG, "json exception populating payload - purchase with receipt ");
}
}
}
}
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:
// Instantiate your key/value pair object and fill with desired data Map<String, String> data = new HashMap<String, String>(); data.put( "key1" , "someData1" ); data.put( "key2" , "someData2" ); // Lastly, call the method, passing your map as the parameter. kTracker.linkIdentity(data);
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.
// after gathering your deep link intent.... Uri data = intent.getData(); kTracker.deepLinkEvent(data.toString());
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.
HashMap<String, Object> datamap = new HashMap<String, Object>(); datamap.put(Feature.INPUTITEMS.KOCHAVA_APP_ID ,"_YOUR_APP_GUID_" ); datamap.put(Feature.INPUTITEMS.REQUEST_ATTRIBUTION, true); Feature kTracker = new Feature( contextObject ,datamap)
To receive attribution data via a callback, add the following handler to your application:
{
@Override
public void handleMessage(Message msg)
{
String attributionDataString = msg.getData().getString(Feature.ATTRIBUTION_DATA);
// do something with attributionDataString
}
};
Then, register the handler with the library before you initialize it:
Feature.setAttributionHandler(callback); HashMap<String, Object> datamap = new HashMap<String, Object>(); datamap.put(Feature.INPUTITEMS.KOCHAVA_APP_ID ,"_YOUR_APP_GUID_" ); datamap.put(Feature.INPUTITEMS.REQUEST_ATTRIBUTION, true); Feature kTracker = new Feature( contextObject ,datamap)
To learn what attribution data has been retrieved from the Server at any time, you can call the getAttributionData method.
String attributionData = Feature.getAttributionData();
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:
{
"network": "KochavaTestVPPN_11_4",
"network_id": "1484",
"campaign": "SDK Testing",
"tier": "",
"tracker": "Tracker 3860a",
"tracker_id": "kospeedyiostest4743213e08eeu4a8cb8b1107e4f6dc ",
"site": "1",
"country": "USA",
"timestamp": 1426525910,
"date": "2015-03-16 17:11:50",
"ko_click_id": "ko_a13c55070ebf7174b",
"user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 7_1_2 like Mac OS X) AppleWebKit/537.51.2 (KHTML, like Gecko) Version/7.0 Mobile/11D257 Safari/9537.53",
"click": {
"meta": {
"control_server": "172.18.95.75",
"original_request": "campaign_id=kospeedyiostest4743213e08eeu4a8cb8b1107e4f6dc&network_id=1484&device_id=device_id&site_id=1&ko_click_id=ko_a13c55070ebf7174b&in_time=1426525887&inboarder=d4",
"origination_ip": "84.175.168.54"
},
"id": 42,
"deeplink": "",
"date": "2015-03-16 17:11:27"
},
"install": {
"meta": {
"device": "iPhone-iOS-7.1.2",
"control_server": "172.18.95.78",
"matched_by": "fingerprint",
"in_time": "1426525910",
"inboarder": "d3",
"debug": "1",
"alt_device_id": "a:0:{}",
"device_id": "DE5DCF67-116A-450A-E5A3-117A36341FA6",
"device_id_type": "idfa",
"origination_ip": "84.175.168.54",
"device_limit_tracking": "1",
"app_limit_tracking": "0",
"device_ver": "iPhone-iOS-7.1.2",
"advertiser_tracking_enabled": "0",
"application_tracking_enabled": "1"
},
"id": 124
}
}
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:
Feature.setErrorDebug(true);
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.
Feature.enableDebug(true);
Files for Download
[ithoughts_tooltip_glossary-tooltip href=”/wp-content/uploads/2017/03/Android-SDK-Release-Notes_20170303.pdf” target=”_blank” tooltip-content=”<h6><strong>SDK Version – 20170303</strong></h6><br/><ul><br/><li><br/><h6>Modify data points collected for identity link.</h6><br/></li><br/></ul><h6><strong>SDK Version – 20170216</strong></h6><br/><ul><br/><li><br/><h6>Updated decoder to better handle improperly encoded install referrer.</h6><br/></li><br/></ul>
<h6><strong>SDK Version – 20170127</strong></h6><br/><ul><br/><li><br/><h6>Added support for the Amazon Fire advertising ID.</h6><br/></li><br/></ul><br/><ul><br/><li><br/><h6>Added additional standard event parameters, including parameters for sending Google Play receipts.</h6><br/></li><br/></ul><br/>”]Kochava Android SDK Release Notes[/ithoughts_tooltip_glossary-tooltip]
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.
