Integrating the SDK
Requirements:
- Android API 14
- iOS Target 10.3
- Xcode 12
- Adobe AIR 32
Supported Platforms:
- Android
- iOS
NOTE: Google has deprecated their legacy Play Install Referrer API which utilized a broadcast receiver. The updated version requires that the library com.android.installreferrer:installreferrer:1.0 be added to replace it. Our native Android SDK Integration documentation describes this change in more detail.
Data Privacy:
Integration:
In order to use the Kochava SDK you must first add it to your project. When downloading the SDK they are two variants to choose from based on your project requirements.
GMS Variant —
This includes Google Mobile (Play) Services bundled for you and does not require you to manually add Google Mobile Services to be able to perform attribution based on the Android Advertising Identifier.
Standard Variant —
If you are already using Google Mobile Services in your app, you can use this variant instead which does not have Google Mobile Services bundled. When using this variant you must ensure you include the play-services-ads-identifier and the installreferrer libraries and all of their dependencies.
- Create a new Android or iOS project.
- Select File>Publish Settings.
- Select the wrench icon next to Script for ActionScript Settings.
- Select the Library Path tab.
- Click Browse for Native Extension (ANE) File and Select the com.kochava.extensions.Kochava.ane file.
- Click OK.
- Select the wrench icon next to Target for Player Settings.
- Select the Permissions tab>Enable:
- INTERNET
- ACCESS_NETWORK_STATE
- ACCESS_WIFI_STATE
- Check Manually manage permissions and manifest additions for this app.
- Click OK.
- Go to Project Properties.
- Select Native Extensions under Actionscript Build Path.
- Choose Add ANE… and Navigate to the com.kochava.extensions.Kochava.ane file.
- Select the Native Extensions tab, and Click the Package checkbox next to the extension.
Update Application Descriptor —
For Kochava to work, changes are required to the application XML file for the app. Modify the XML file created by your IDE with the following changes:
- Set your AIR SDK to 32.0 or higher in the app descriptor file.
- Include a link to the extension in the descriptor.
- Update your Android Manifest Additions in the XML element.
<application xmlns="http://ns.adobe.com/air/application/32.0">
<extensions>
<extensionID>com.kochava.extensions.KochavaTracker</extensionID>
</extensions>
<android>
<manifestAdditions><![CDATA[
<manifest android:installLocation="auto">
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<application>
<meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version" />
<receiver android:name="com.kochava.base.ReferralReceiver" android:exported="true">
<intent-filter>
<action android:name="com.android.vending.INSTALL_REFERRER" />
</intent-filter>
</receiver>
</application>
</manifest>
]]></manifestAdditions>
</android>
Update AIR SDK —
The AIR SDK is missing some functionality required by the iOS platform of the SDK and must be patched with a file from Xcode in order to work properly. More information can be found on the AIR issue tracker.
The file “libclang_rt.ios.a” needs to be copied from Xcode into the AIR SDK. The version of Xcode is in the path and must be adjusted to match your installed version.
Copy the file after adjusting the 12.0.0 to the version of Xcode you have installed.
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/clang/12.0.0/lib/darwin/libclang_rt.ios.a
To
[AIRSDK_PATH]/lib/aot/lib/libclang_rt.ios.a
Permissions:
Permissions are added to the top level of the AndroidManifest.xml file.
//Required: ADID collection as of API 31+
<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
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 provide more accurate session reporting and help to ensure the tracker has been started before using it. Keep in mind the tracker can only be configured and started once per launch.
//Import
import com.kochava.nativeextensions.*;
import com.kochava.nativeextensions.events.*;
//Configure and Start
var configMapObject:Object = new Object();
configMapObject[KochavaTracker.PARAM_IOS_APP_GUID_STRING_KEY] = "_YOUR_IOS_APP_GUID_";
configMapObject[KochavaTracker.PARAM_ANDROID_APP_GUID_STRING_KEY] = "_YOUR_ANDROID_APP_GUID_";
KochavaTracker.configure(configMapObject);
Developer API Reference:
KochavaTracker.configure(MapObject)
Configuration Parameters
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.
Custom Tracker Configuration
If you would like to make adjustments to the tracker configuration beyond the default settings, set your App GUID and the desired parameters and then pass it to the tracker’s configure method.
Using a Custom Configuration:
var configMapObject:Object = new Object();
configMapObject[KochavaTracker.PARAM_IOS_APP_GUID_STRING_KEY] = "_YOUR_IOS_APP_GUID_";
configMapObject[KochavaTracker.PARAM_ANDROID_APP_GUID_STRING_KEY] = "_YOUR_ANDROID_APP_GUID_";
configMapObject[KochavaTracker.PARAM_LOG_LEVEL_ENUM_KEY] = KochavaTracker.LOG_LEVEL_ENUM_TRACE_VALUE;
KochavaTracker.configure(configMapObject);
NOTE: Setting values within a configuration object will have no effect after the tracker has been started.
Below is a list of all configuration options and their default settings. Keep in mind that in a typical integration these configuration settings should not be adjusted from their default values.
Default — None
This string should be set to your Kochava App GUID, which can be found in your Edit App page within the Kochava dashboard. This value is always required (unless a Partner Name is set).
configMapObject[KochavaTracker.PARAM_ANDROID_APP_GUID_STRING_KEY] = "_YOUR_ANDROID_APP_GUID";
configMapObject[KochavaTracker.PARAM_IOS_APP_GUID_STRING_KEY] = "_YOUR_IOS_APP_GUID";
Default — None
Provide an attribution event listener if you wish to be notified of attribution results from Kochava servers. This is not necessary unless you wish to parse the attribution results for use within the app.
For complete details and examples, see: Retrieving Attribution.
Default — None
Provide an Identity Link object of key/value pairs which is known before starting the tracker. Identity Links can also be set after starting the tracker.
For complete details and examples, see: Identity Linking.
Default — LOG_LEVEL_ENUM_INFO_VALUE
Set this value to the desired Log Level to be used by the SDK for debugging purposes.
For complete details and examples, see: Enabling Logging.
Default — False
If you wish to limit ad tracking at the application level, with respect to Kochava conversions, set this value to true. It can also be toggled after starting the tracker.
For complete details and examples, see: App Limit Ad Tracking.
Default — None
This is a reserved setting and should not be set unless provided by your Client Success Manager.
Default — None
This is a reserved value and should not be set unless provided by your Client Success Manager.
Default — False
As GDPR compliance can present many challenges during development, Kochava offers a fully managed solution for all your GDPR consent requirements through the use of our Intelligent Consent Management feature. By using this feature the Kochava SDK will handle determining when consent is required for any user while shouldering much the GDPR burden for you.
NOTE: This is an advanced feature requiring additional setup within your Kochava dashboard and should not be enabled without a full and complete understanding of how to use the Intelligent Consent Management feature.
For complete details and examples, see: Intelligent Consent Management.