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 network and publisher partners via Kochava. This limits the number 3rd party SDKs required to run a successful UA (User Acquisition) strategy and greatly reduces complexity during update cycles. Find documentation for other SDKs, plugins, and Server-to-Server Integrations here.

Minimum Requirements:

• Adobe AIR – 18.0 or higher, supporting iOS 64bit
• iOS Target: iOS 6.0 or later
• Android Target: API level 9 (Version 2.3) or later

Before Beginning:

• The Kochava Extension uses Adobe AIR 16.0 or higher for iOS 64bit support. Download the latest version of Adobe AIR.
• Review ‘example/KochavaExample.as’ for a sample application.
• Retrieve the Kochava App ID(s).

NOTE: KochavaExample.as is a Document Class. If you’re a Flash Professional user and don’t know how to use a document class, refer to Troubleshooting and Frequently Asked Questions at the end of this guide.

Include the Library

Create a new AIR for Mobile project and add the native extension.

For Flash Professional CS6 or Higher:

1. Create a new Android or iOS project.
2. Choose File>Publish Settings.
3. Select the wrench icon next to Script for ActionScript Settings.
4. Select the Library Path tab.
5. Click Browse for Native Extension (ANE) File and select the com.kochava.extensions.Kochava.ane file.
6. Click OK.
7. Select the wrench icon next to Target for Player Settings.
8. Select the Permissions tab, and enable:
• ACCESS_NETWORK_STATE
• ACCESS_WIFI_STATE
9. Check the Manually manage permissions and manifest additions for this app box.
10. Click OK.

For Flash Builder 4.6 or Higher:

1. Go to Project Properties.
2. Select Native Extensions under Actionscript Build Path.
3. Choose Add ANE… and navigate to the com.kochava.extensions.Kochava.ane file.
4. Select Actionscript Build Packaging > Google Android (or iOS if building for that target).
5. 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:

NOTE: If you’re a Flash Professional user, make sure to follow the steps detailed in Include the Library, otherwise Flash might undo your changes as you make them.

1. Set your AIR SDK to 16.0 in the app descriptor file.

<application xmlns="http://ns.adobe.com/air/application/16.0">

 

2. Include a link to the extension in the descriptor.

<extensions>
    <extensionID>com.kochava.extensions.Kochava</extensionID>
</extensions>

 

3. Update your Android Manifest Additions in the <android> XML element.

<android>
    <manifestAdditions><![CDATA[
        <manifest android:installLocation="auto">
            <uses-permission android:name="android.permission.INTERNET" />
            <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> 
            <uses-sdk android:minSdkVersion="8" android:targetSdkVersion="18"/> 
 
            <application>
                <meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version" />
                <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>
        </manifest>
    ]]></manifestAdditions>
</android>

Set up API and Connect with Kochava

Once you’ve retrieved your Kochava App IDs from Kochava, you’re ready to start writing code.

1. Import the API Classes.

import com.kochava.nativeextensions.*;
import com.kochava.nativeextensions.events.*;

 

2. Initialize the API by calling Kochava.create(), and passing in the Kochava App GUID(s).
3. Check the Kochava.isSupported() method first, to ensure the current platform is not an unsupported platform (like Windows or Mac.)

// check if the current platform supports android extensions
if (Kochava.isSupported())
{
    Kochava.create("YOUR_KOCHAVA_APP_GUID_HERE");
}

 

4. If developing a multiplatform application, enter the iOS, Android and Kindle App GUIDs.

// check if the current platform supports android extensions
if (Kochava.isSupported())
{
    Kochava.create("YOUR_KOCHAVA_IOS_APP_GUID_HERE","YOUR_KOCHAVA_ANDROID_APP_GUID_HERE","YOUR_KOCHAVA_KINDLE_APP_GUID_HERE");
}

 

NOTE: By using the correct app GUID order, the correct GUID will be automatically used when targeting the relevant platform.

 

5. Once this method is called, the Kochava Tracker will report device and app information to Kochava, should those values be different than the last time this information was reported.

 

NOTE: Execute this code as early as possible in the lifespan of the application.

 

Parameters may be added to set the default currency, enable debug logging, limit ad tracking and send IdentityLink information on initialization of the library.

// check if the current platform supports android extensions
if (Kochava.isSupported())
{
    Kochava.create("YOUR_KOCHAVA_IOS_APP_GUID_HERE","YOUR_KOCHAVA_ANDROID_APP_GUID_HERE","YOUR_KOCHAVA_KINDLE_APP_GUID_HERE","CURRENCY",DEBUG_LOGGING,LIMIT_AD_TRACKING,IDENTITY_LINK_PAIRS);
}

 

NOTE: To view the debug/console output, run the iOS app in Xcode or Android app using “monitor” (supplied with Android Studio).

Tracking Events

Post-install events can be sent to Kochava for tracking. Post-install event tracking is optional, basic installation information will be automatically handled after calling Kochava.create().

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

Many advertisers want to understand and correlate the relationship between conversion and attribution source information with post-install behaviors. This can only be achieved by tracking post-install events.

Events are stored in memory 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 performance impact it could make on the application.

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

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 the event’s value.

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

Send the Event Track Request:

1. Call Kochava.kochava.trackEvent().
2. Pass in the event name.
3. Pass a string of extra event data. (optional)

 

NOTE: If the optional additional data is not desired to be passed, pass an empty string (“”) rather than null for that parameter.

// track event named 'myEvent' with data 'myValue'
Kochava.kochava.trackEvent("myEvent","myValue");

 

// track event named 'myEvent' with no additional data
Kochava.kochava.trackEvent("myEvent","");

 

4. Kochava also supports tracking of Spatial Events, allowing you to associate x, y, and z values with the event, using the trackSpatialEvent() method.

 

FAA Limited Option: This feature is not available within Free App Analytics. Contact us for more information on upgrading to a paid Kochava account.


 

// track spatial event named 'mySpatialEvent' at the x,y,z location 300,400,500
Kochava.kochava.trackSpatialEvent("mySpatialEvent",300,400,500);

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 trackEventWithReceipt method.

// track event named 'Purchase' with data 'myValue' as optional data 
// and a Base64 encoded string containing the App Store receipt.
Kochava.kochava.trackEventWithReceipt("Purchase","myValue",encodedReceiptString);

IdentityLink Events

IdentityLink events provide the opportunity to “link different identities” together. For example, you may have assigned each user of your app an internal user ID which you want to connect to a user’s Facebook account. Using the linkIdentity method, you can send both your internal ID and their Facebook ID and connect them in the Kochava database. Kochava reports can be generated 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.

NOTE: Although you can call the linkIdentity 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.

1. Insert dd event listeners for KochavaEvent.IDENTITY_LINKED and KochavaEvent.IDENTITY_LINK_FAILED.

 

NOTE: These callbacks will let you know if the link request was successful.

 

// listen for link events
Kochava.kochava.addEventListener(KochavaEvent.IDENTITY_LINKED, onIdentityLinked);
Kochava.kochava.addEventListener(KochavaEvent.IDENTITY_LINK_FAILED, onLinkFailed);
 
function onIdentityLinked(e:KochavaEvent):void
{
    trace("Identity link complete.");
}
 
function onLinkFailed(e:KochavaEvent):void
{
    trace("Something went wrong linking identities.");
}

 

2. Start the link request by calling Kochava.kochava.linkIdentity().

 

NOTE: This method takes a single parameter, data, an ActionScript generic object containing the key-value pairs, to link. For instance, you might link a Facebook user ID to an internal user ID by passing {myInternalUserID:”john123″, UserFacebookID:”123456789123456″} . The data parameter must contain at least one key-value pair, and all values must be strings.

 

// link identity john123 to facebook id 123456789123456
Kochava.kochava.linkIdentity({myInternalUserID:"john123", UserFacebookID:"123456789123456"});

Deep Linking

Kochava provides a specific event to use when tracking deep links. The method is as follows, where “uri” is a string object that could hold the incoming deeplink uri.

Kochava.kochava.deepLink(uri);

NOTE: You will need to enable deep links for both Android and iOS.

iOS: https://developer.apple.com/library/ios/documentation/UIKit/Reference/UIApplication_Class/index.html#//apple_ref/occ/instm/UIApplication/openURL:

Android: https://developer.android.com/training/app-indexing/deep-linking.html

Attribution Data Request

Attribution data can be received from a Kochava server, usually in less than 10 seconds from the initial application launch. You can receive attribution through a callback to your host app, or you can call a method that will try and gather attribution data that has already been returned to the SDK.

Set the request attribution data boolean and tell the library to set up the callback when you initialize the library for either of the two approaches to work.

Kochava._requestAttribution = true;
Kochava.kochava.setAttributionHandler();

For the callback, create a function with a KochavaEvent parameter as your callback, and register it with Kochava (this can happen after the above calls):

private function onAttributionData(e:KochavaEvent):void
{
    log("Attribution Data received: " + e.level);
}
 
Kochava.kochava.addEventListener(KochavaEvent.ATTRIBUTION_DATA, onAttributionData);

When the library receives attribution data, it stores it. The data can then be retrieved with the following method.

var data:String = Kochava.kochava.requestAttributionData();

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
	}
}

iBeacon Detection

NOTE: iBeacon Detection is not included with the standard Kochava SDK, an ANE (Adobe Native Extension) SDK capable of iBeacon detection is available upon request (iOS only). For further information on iBeacon Detection, contact a Kochava Client Success Managers.

Files for Download

KochavaANE_20161207

Testing the Integration

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

Frequently Asked Questions