The Kochava Android SDK is a lightweight plugin which can be easily integrated into your Android project. The entire integration process takes less than five minutes and simply requires adding the SDK within your project and then starting the Kochava Tracker in code. If you have already integrated the SDK and started the tracker, please visit Using the SDK and choose a topic.
Integrating the SDK
Requirements:
- Android API 16
- Internet Permission
- Java 8 Compatibility
Supported Platforms:
- Android
- Android TV
- Android Wear OS
- Android Auto
- Android Instant App
- Amazon Fire
- Windows Subsystem for Android
Data Privacy:
Migration:
If you are migrating from a Kochava SDK prior to version 4.0.0 to version 4.x or newer, first remove the old version by removing the following from your module’s build.gradle dependency block.
implementation 'com.kochava.base:tracker:x.y.z'Once removed the new version can be integrated by following the integration steps below. SDK usage can then be updated by reviewing the code samples for any given topic, as the overall usage of the SDK remains the same.
Integration:
Release Notes
In order to use the Kochava SDK, first add it within your project. This can be accomplished using Gradle (recommended) or by downloading the SDK AAR files manually and adding them.
Name Description Badge OptionalTracker Attribution and analytics. No Events Event tracking. Yes Engagement Push notification support. Yes Network Datapoints Collection of networking related data points. Yes Legacy Referrer Legacy install referrer support. Yes Add the required Tracker module along with any additional optional modules to your module level build.gradle file. If you have a multiple module project they should be added to your base module. Replace “x.y.z” with the latest version obtained from the Download Badge above.
dependencies { def kochava_tracker_version = "x.y.z" implementation("com.kochava.tracker:tracker:$kochava_tracker_version") // Required implementation("com.kochava.tracker:events:$kochava_tracker_version") // Optional implementation("com.kochava.tracker:engagement:$kochava_tracker_version") // Optional implementation("com.kochava.tracker:datapointnetwork:$kochava_tracker_version") // Optional implementation("com.kochava.tracker:legacyreferrer:$kochava_tracker_version") // Optional }NOTE: The Kochava SDK is hosted on Maven Central. If it’s not already added then add mavenCentral() to your project’s repositories list.
Name Description Badge OptionalCore Core SDK functionality. No Tracker Attribution and analytics. No Events Event tracking. Yes Engagement Push notification support. Yes Network Datapoints Collection of networking related data points. Yes Legacy Referrer Legacy install referrer support. Yes Download the required Core and Tracker module’s AAR files along with any additional optional modules from the above badge links and add them to your project.
Release Notes
In order to use the Kochava SDK, first add it within your project. This can be accomplished using Gradle (recommended) or by downloading the SDK AAR files manually and adding them.
Add the Kochava SDK to your module level build.gradle file. If you have a multiple module project this should be added to your base module. Replace “x.y.z” with the latest version obtained from the Download Badge above.
dependencies { implementation 'com.kochava.base:tracker:x.y.z' // Required implementation 'com.kochava.base:tracker-network:x.y.z' // Optional: Networking Datapoints }NOTE: The Kochava SDK is hosted on Maven Central. If not already added then add mavenCentral() to your project’s repositories list.
Download the tracker and tracker-network AAR files from the Download Badge above and either add them directly or extract the JAR files and other resources from them and add them individually.
Additional Integration Steps:
Google Play Store:
If you wish for the SDK to collect the Google Play Ads Identifier (ADID), App Set ID (ASID) and/or make use of the Install Referrer, you must integrate Google Play Services by adding the appropriate dependencies. Collection is handled by the Kochava SDK with only the dependency itself needing to be included. The Kochava SDK does not require specific versions of its dependencies however we recommend keeping them up to date whenever possible.
Maven Repository —
google()
Dependencies —
implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'NOTE: If using a version prior to version 17.1.0 you must also add the following permission.
<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
implementation 'com.android.installreferrer:installreferrer:2.2'
implementation 'com.google.android.gms:play-services-appset:16.0.2'Huawei App Gallery:
If you wish for the SDK to collect the Huawei Advertising ID (OAID) and/or make use of the Install Referrer, you must integrate the Huawei Ads SDK by adding the appropriate dependencies. Collection is handled by the Kochava SDK with only the dependency itself needing to be included. The Kochava SDK does not require specific versions of its dependencies however we recommend keeping them up to date whenever possible.
Maven Repository —
maven { url 'https://developer.huawei.com/repo/' }
Dependencies —
implementation 'com.huawei.hms:ads-identifier:3.4.39.302'
implementation 'com.huawei.hms:ads-installreferrer:3.4.39.302'Samsung Galaxy Store:
SDK VERSION NOTE: This feature requires Kochava Android SDK Version 4.3.0 or higher.
If you wish for the SDK to collect and/or make use of the Samsung Install Referrer, you must integrate Samsung Install Referrer by adding the appropriate dependencies. Collection is handled by the Kochava SDK with only the dependency itself needing to be included. The Kochava SDK does not require specific versions of its dependencies however we recommend keeping them up to date whenever possible.
implementation 'store.galaxy.samsung.installreferrer:samsung_galaxystore_install_referrer:4.0.0'Samsung Cloud Gaming:
SDK VERSION NOTE: This feature requires Kochava Android SDK Version 5.2.0 or higher.
If you wish for the SDK to collect and/or make use of the local user’s ADID (CGID) when running in the cloud gaming environment, you must integrate the Samsung Cloud Dev SDK by adding the appropriate dependencies and permissions. Collection is handled by the Kochava SDK with only the dependency itself needing to be included. The Kochava SDK does not require specific versions of its dependencies however we recommend keeping them up to date whenever possible.
Dependencies —
Add the clouddevsdk.aar file to your project, this can be obtained by contacting your Samsung representative directly.
Permissions —
<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>Meta/Facebook:
SDK VERSION NOTE: This feature requires Kochava Android SDK Version 5.1.0 or higher.
If you wish for the SDK to collect and/or make use of the Facebook Attribution ID or Meta Install Referrer, you must add the appropriate manifest entries. Collection is handled by the Kochava SDK with no additional dependencies needing to be included.
NOTE: In order for the Meta Referrer to be collected by the SDK you must have the Facebook Partner configured on the Free App Analytics Dashboard with your Facebook App ID.
Manifest
The following items should be added to the top level of your manifest file.
<queries>
<package android:name="com.facebook.katana" />
<package android:name="com.instagram.android" />
</queries>
Permissions:
The following permissions are split by module and are automatically included with the module. Optional permissions are noted and can be removed if desired using the manifest entry shown.
// Tracker Module
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
// Optionally remove the automatically included Network State permission.
<!-- <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" tools:node="remove"/> -->
// Network Module
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
// Optionally remove the automatically included Wifi State permission.
<!-- <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" tools:node="remove"/> -->
Minification (ProGuard / R8):
The following minification rules are required when code minification is enabled. They are automatically included when adding the Kochava SDK and typically do not require manual inclusion. If you are experiencing issues after enabling minification you can manually include the rules in your configuration file.
# KochavaCore: Ignore SDK warnings for missing dependencies.
-dontwarn com.kochava.core**
# KochavaCore: Keep annotations used for json serialization.
-keepattributes Signature
-keepattributes *Annotation*
# KochavaCore: BuildConfig
-keep class com.kochava.core.BuildConfig { *; }
# KochavaCore: Google Instant Apps Collection.
-keep class com.google.android.gms.common.wrappers.InstantApps {
boolean isInstantApp(android.content.Context);
}
# KochavaTracker: Ignore SDK warnings for missing dependencies.
-dontwarn com.kochava.tracker**
# KochavaTracker: BuildConfig
-keep class com.kochava.tracker.BuildConfig { *; }
# KochavaTracker: Internal SDK
-keep class com.kochava.tracker.modules.internal.Module {
void setController(***);
*** getController();
}
-keep class com.kochava.tracker.Tracker {
static com.kochava.tracker.TrackerApi getInstance();
}
# KochavaTracker: Google ADID Collection.
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient {
com.google.android.gms.ads.identifier.AdvertisingIdClient$Info getAdvertisingIdInfo(android.content.Context);
}
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient$Info {
java.lang.String getId();
boolean isLimitAdTrackingEnabled();
}
# KochavaTracker: Google Install Referrer Collection.
-keep class com.android.installreferrer.api.InstallReferrerClient { *; }
-keep class com.android.installreferrer.api.InstallReferrerClient$InstallReferrerResponse { *; }
-keep class com.android.installreferrer.api.InstallReferrerStateListener { *; }
-keep class com.android.installreferrer.api.ReferrerDetails { *; }
# KochavaTracker: Google App Set ID Collection
-keep class com.google.android.gms.appset.AppSet {
com.google.android.gms.appset.AppSetIdClient getClient(android.content.Context);
}
-keep class com.google.android.gms.appset.AppSetIdClient {
com.google.android.gms.tasks.Task getAppSetIdInfo();
}
-keep class com.google.android.gms.appset.AppSetIdInfo {
java.lang.String getId();
int getScope();
}
-keep class com.google.android.gms.tasks.Tasks {
*** await(com.google.android.gms.tasks.Task, long, java.util.concurrent.TimeUnit);
}
# KochavaTracker: Huawei OAID Collection.
-keep class com.huawei.hms.ads.identifier.AdvertisingIdClient {
com.huawei.hms.ads.identifier.AdvertisingIdClient$Info getAdvertisingIdInfo(android.content.Context);
}
-keep class com.huawei.hms.ads.identifier.AdvertisingIdClient$Info {
java.lang.String getId();
boolean isLimitAdTrackingEnabled();
}
# KochavaTracker: Huawei Install Referrer Collection.
-keep class com.huawei.hms.ads.installreferrer.api.InstallReferrerClient { *; }
-keep class com.huawei.hms.ads.installreferrer.api.InstallReferrerClient$InstallReferrerResponse { *; }
-keep class com.huawei.hms.ads.installreferrer.api.InstallReferrerStateListener { *; }
-keep class com.huawei.hms.ads.installreferrer.api.ReferrerDetails { *; }
# KochavaTracker: Samsung Install Referrer Collection.
-keep class com.samsung.android.sdk.sinstallreferrer.api.InstallReferrerClient { *; }
-keep class com.samsung.android.sdk.sinstallreferrer.api.InstallReferrerClient$InstallReferrerResponse { *; }
-keep class com.samsung.android.sdk.sinstallreferrer.api.InstallReferrerStateListener { *; }
-keep class com.samsung.android.sdk.sinstallreferrer.api.ReferrerDetails { *; }
# KochavaTracker: Notifications Enabled Collection.
-keep class androidx.core.app.NotificationManagerCompat {
static androidx.core.app.NotificationManagerCompat from(android.content.Context);
boolean areNotificationsEnabled();
}
# KochavaTracker: Samsung Cloud Game Dev
-keepclassmembers, includecode class
com.samsung.android.game.cloudgame.dev.sdk.* { *;}
# KochavaTrackerDatapointNetwork: Ignore SDK warnings for missing dependencies.
-dontwarn com.kochava.tracker.datapointnetwork**
# KochavaTrackerDatapointNetwork: BuildConfig
-keep class com.kochava.tracker.datapointnetwork.BuildConfig { *; }
# KochavaTrackerDatapointNetwork: Internal SDK
-keep class com.kochava.tracker.datapointnetwork.internal.DataPointCollectionNetwork {
public <methods>;
}
# KochavaTrackerEngagement: Ignore SDK warnings for missing dependencies.
-dontwarn com.kochava.tracker.engagement**
# KochavaTrackerEngagement: BuildConfig
-keep class com.kochava.tracker.engagement.BuildConfig { *; }
# KochavaTrackerEngagement: Internal SDK
-keep class com.kochava.tracker.engagement.Engagement {
static com.kochava.tracker.engagement.EngagementApi getInstance();
}
# KochavaTrackerEvents: Ignore SDK warnings for missing dependencies.
-dontwarn com.kochava.tracker.events**
# KochavaTrackerEvents: BuildConfig
-keep class com.kochava.tracker.events.BuildConfig { *; }
# KochavaTrackerEvents: Internal SDK
-keep class com.kochava.tracker.events.Events {
static com.kochava.tracker.events.EventsApi getInstance();
}
# KochavaTrackerLegacyReferrer: Ignore SDK warnings for missing dependencies.
-dontwarn com.kochava.tracker.legacyreferrer**
# KochavaTrackerLegacyReferrer: BuildConfig
-keep class com.kochava.tracker.legacyreferrer.BuildConfig { *; }
# KochavaTrackerLegacyReferrer: Referrer Receiver
-keep class com.kochava.tracker.legacyreferrer.LegacyReferrerReceiver {
void onReceive(android.content.Context, android.content.Intent);
}
Starting the Tracker
Once you have added the Kochava SDK to your project, the next step is to configure and start the Kochava Tracker in code. Only your App GUID is required to start the tracker with the default settings, which is the case for typical integrations.
We recommend starting the tracker as soon as the application starts, although this can be done later if needed. Starting the tracker as early as possible will ensure it’s started before use, provide more accurate session reporting, and quicker deeplink results.
class MyApp : Application() { override fun onCreate() { super.onCreate() Tracker.getInstance().startWithAppGuid(applicationContext, "YOUR_ANDROID_APP_GUID") } }public class MyApp extends Application { @Override public void onCreate() { super.onCreate(); Tracker.getInstance().startWithAppGuid(getApplicationContext(), "YOUR_ANDROID_APP_GUID"); } }class MyApp : Application() { override fun onCreate() { super.onCreate() Tracker.configure(Tracker.Configuration(applicationContext) .setAppGuid("YOUR_ANDROID_APP_GUID") ) } }public class MyApp extends Application { @Override public void onCreate() { super.onCreate(); Tracker.configure(new Tracker.Configuration(getApplicationContext()) .setAppGuid("YOUR_ANDROID_APP_GUID") ); } }
Confirm the Integration
After integrating the SDK and adding the code to start the measurement client, launch and run the app for at least 10 seconds or more. During this time the client will start and send an install payload to Kochava. To confirm integration was successful, visit the app’s Install Feed Validation page Apps & Assets > Install Feed Validation. On this page you should see one of two integration messages, indicating integration success or failure.
Integration Successful:
Along with this message you will also see a variety of data points associated with the device used for testing. At this point your integration is successful and you can proceed to the next step(s).
NOTE: It may take a few minutes for the first install to appear within the Install Feed Validation page. If you do not see this message immediately, you may simply need to wait a few minutes and check again.
Integration Not Complete:
If you encounter this message, please review the integration steps, uninstall and reinstall the app, and check again.
Where to Go From Here:
Now that you have completed integration you are ready to utilize the many features offered by the Kochava SDK. Continue on to Using the SDK and choose a topic.
