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:

Unity version 5.5.0 or higher
Mobile API compatibility level: net 2.0 subnet
Android Target: API level 9 (Version 2.3)
iOS Target: 8.0

NOTE: April 15, 2015 – Unity released Patch 5.0.1p1 which fixes the previous bug which prevented SSL communication on iOS. If you are using Unity 5, it is imperative you apply Patch 5.0.1p1 or later for the Kochava SDK to communicate with our servers on iOS.

NOTE: As of February 1, 2015 Apple requires all new apps be submitted with 64bit support. The iOS library supplied as an Asset within the Kochava Unity SDK is a universal binary, supporting both 32 and 64bit architectures.

SDK Integration

Launch Unity, and import the Kochava_Unity_xxxx.unitypackage file
The latest version of Kochava’s Unity SDK is provided for download at the bottom of this page.
Switch to the first scene in your Unity application
This scene should only be loaded once when your application is run.
Use “Game Object > Create Other > Kochava Integration Object” from Unity’s primary application menu
A “_Kochava Analytics” Game Object will appear in your scene, set itself to survive scene changes, and provide several globally accessible methods for advanced event logging.
Select the new “_Kochava Analytics” object in your scene, and copy the App GUID from your Kochava.com dashboard to the “Kochava App GUID” inspector slot.
If you publish this application on multiple platforms, enter each applicable Kochava App GUID in the appropriate application-specific App ID slot.
If publishing for iOS:
You must link Apple’s AdSupport framework to your Xcode project: Build for iOS, then manually link to the AdSupport framework in Xcode’s “Build Phases > Link with Binary” section. Skipping this step will likely result in “Undefined symbols for architecture” errors in the Xcode console. Subsequent iOS builds can be appended to your customized Xcode project, obviating the need to constantly redo this operation.
If publishing for Android:
You need to ensure that permissions for ACCESS_WIFI_STATE and ACCESS_NETWORK_STATE are defined in your app build’s AndroidManifest.xml file. Additionally, if you would like to take advantage of referrer data from the Google Play Store, you will need to declare the Kochava SDK’s Broadcast Receiver in your Android manifest as well. An appropriate _KOCHAVA_SAMPLE_AndroidManifest.xml file is provided in the Kochava SDK package, please customize it according to you app’s specific requirements and then remove _KOCHAVA_SAMPLE_ from the title to have it automatically incorporated into your Android builds. More information on AndroidManifest.xml files can be found in Unity’s Documentation and Google’s API Guides.
Usage analytics will begin appearing in your Freeappanalytics.com dashboard.

NOTE: The Kochava SDK will not run from the Unity Player and can only be initialized when building for the Android or iOS platform.

Android Add Google Play Services:

The Kochava SDK requires Google Play Services – Base and Google Play Services – Basement.
Optionally – Free App Analytics suggests you add Google Play Services – Location and it’s dependencies as well if you wish to collect location data. These files should all be added within the Assets > Plugins > Android folder. If collecting location you must also add the ACCESS_FINE_LOCATION and ACCESS_COARSE_LOCATION permissions to your android manifest. Below is a sample of how your file structure might look after adding these files.

NOTE: In our testing, using Google Play Services v10.0.1 AARs, we found that Google Play Services – Location additionally required the Support v4 library (“support_compat”), which we added in the sample above. Your mileage may vary depending on which versions you use and how you integrate Google Play Services. For more information on adding Google Play Services, refer to Android support documentation.

Integration Customization

To customize your Kochava SDK integration, select the “_Kochava Analytics” object in your app’s first scene.

Unity’s Inspector will show the following configurable parameters:

Free App Analytics App GUID
The unique GUID for your app – available in your Freeappanalytics.com dashboard.
Should look like: kounitysdktest31950c6bcb3007b5
Free App Analytics App GUID + iOS / Android / Kindle / etc
When publishing to multiple platforms, populate these fields with platform-specific App GUIDs and they will be used in place of the primary Kochava App ID when appropriate.
Log Level
When enabled, the Kochava SDK will provide varying levels of diagnostic information within your target platform’s logging environment, such as LogCat for Android or Xcode for iOS.
Request Attribution Callback
Attribution data can be received from Free App Analytics server, 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 by a callback to your host app, by asking for the attribution data at any point, or both. You MUST check the request attribution option when you initialize the library for either of these approaches above to work. If you wish to receive attribution via a callback, this is accomplished differently for iOS and Android:
- For Android you can set your own listener using Tracker.Android.SetAttributionHandler() before initialization in the Kochava.cs file; simply pass in any method with a signature of: void KochavaAttributionListener(string data).
- For iOS create a method called “void KochavaAttributionListener(string data)”, which must belong to the _Kochava Analytics game object. A copy of this is also supplied for you in the _SAMPLE_CODE.txt file included in the unity package. The name must match as the native layer will be looking for that method name.
App Limit Ad Tracking
If you wish to limit ad tracking at the application level, with respect to Kochava conversions, you can turn off ad tracking when you initialize the Kochava library or by an individual method for the purpose of changing the limit ad tracking state, which will be off by default (user opts-in to advertising).

Scripting Reference

The Kochava Tracker class can be accessed via static method calls and belongs to the KochavaUnity namespace. For example, your app can call a static method such as: Tracker.SendEvent(). The _SAMPLE_CODE.txt document included with the SDK package illustrates how your code can interact with Kochava to register custom events and interact with the Kochava tracker. All methods are cross-platform friendly and can be called without the use of platform #if checks.

Standard Event:

No event pre-registration is required. Standard events with commonly used parameters may be sent using the SendEvent(KochavaEvent) method. To instrument a standard event, simply create a new KochavaEvent object with a chosen KochavaEventType and populate only the fields you would like to include with the event, if any. You may then call the SendEvent() method with the KochavaEvent object to send the event.

(void) Tracker.SendEvent (KochavaEvent):

// build and send a standard event using any desired parameters    	
var myEvent = new KochavaEvent(KochavaEventType.LevelComplete);
myEvent.name = "The Deep Dark Forest";
myEvent.duration = 320.0f;
Tracker.SendEvent(myEvent);

NOTE: The KochavaEventType.Custom standard event type is only available when building for iOS. Android support for the KochavaEventType.Custom standard event type will be added in the future.

Custom Event

If you’d like to send a custom event or use parameters which do not conform to the list of available standard parameters please use the Tracker.SendEvent (string eventName, string eventData) method as described below. You may optionally send a stringified dictionary within the eventData parameter.

(void) Tracker.SendEvent (string eventName, string eventData):

// send an event with a name and info string
Tracker.SendEvent("Found Treasure","Sword of Doom");

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

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

This function registers a custom analytics event – use it to record levels that players reach, monsters that challenge players, level areas that prove exceptionally easy or difficult, and other data relevant to your application.
EventData will be used to create a graph segmented by the unique values for each event in Free App Analytics’ analytics interface. Free App Analytics’ will also visualize the sum of any event’s data which can be parsed as a number over any given time period – which is a great way to keep track of the total value of purchase type events.
You can concatenate multiple data elements into a breadcrumb trail in order to visualize hierarchically relevant data.
For example: Tracker.SendEvent (“DeathByMonster”, level_id + ” > ” + monster_name); // graph challenging monsters, organized by the levels which they inhabit
Regardless of what is passed in eventData, Free App Analytics’ user dashboard will let you access all the data passed in eventData for any eventName, and present a count of all times FireEvent 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 eventData.

Tracker.Android.SendEventWithGooglePlayStoreReceipt(string eventName, string eventData, string receiptDataFromGooglePlayStore, string receiptDataSignatureFromGooglePlayStore)

Similar to the SendEvent method, SendEventWithGooglePlayStoreReceipt sends a name/value pair and the Purchase Data and Data Signature from a Google Play purchase to Free App Analytics servers. For documentation on retrieving the Purchase Data and Data Signature, refer to (Implementing In-app Billing).
Tracker.iOS.SendEventWithiOSAppStoreReceipt(string eventName, string eventInfo, string appStoreReceiptBase64EncodedString)

This convenience method can be used to create and send a post-install event similar to SendEvent but includes the additional appStoreReceiptBase64EncodedString parameter which allows you to provide a base64 encoded purchase receipt string. For more information about collecting receipt data, refer to Apple’s support documentation.

About Free App Analytics Events

Free App Analytics maintains an internal queue of tracking events pending analytics server posting. The eventQueueLength accessor lets your code determine how many items are in that queue.
If an event posting fails due to internet connectivity or other issues, Free App Analytics will repost it after a one minute rest period.
If an application is paused or exited, Free App Analytics will automatically serialize this queue into persistent storage and rebuild it on the next app launch. This allows Free App Analytics to record events with an extremely high degree of reliability, even if the user’s device is offline. This also allows Free App Analytics to record events (such as application exits) which would normally be impossible to send to the server.

(void) Tracker.SendDeepLink (string deepLinkURI, string sourceApplication):

Free App Analytics offers this method for a convenient way to track your deep links. After receiving the uri, you can pass it along with your namespace to the deep link method. In iOS only, you may optionally pass the calling application.

(string) Tracker.GetKochavaDeviceId():

Returns the Kochava Device Id

(string) Tracker.GetAttributionData():

Returns the attribution data if requested and available. Typically this data will not be available until 7-10 seconds after the first launch of the app, but could take longer. Once it has been received it can be retrieved any time using this method, otherwise the return value is an empty string. Please note that it is up to you to parse the attribution response and decide how you wish to use it.

Email Attribution (Android Only)

If enabled in the Free App Analytics dashboard for your app, the Kochava SDK can retrieve email addresses on the device, for use in attribution. If you wish to enable this capability, you need to add the following to your app’s AndroidManifest.xml file:

<uses-permissionandroid:name ="android.permission.GET_ACCOUNTS"/>

Identity Link

Identity Link events provide the opportunity to tie a Kochava device ID to your internal identifier. For example, you may have assigned each user of your app an internal userid which you want to connect to a user’s service identifier. Using the Identity Link method, you can send both your internal id with a device identifier and connect them in the Free App Analytics database.

Free App Analytics reports can be output to show additional identity information for devices in the Free App Analytics database so that you can supplement your reports with internal identifiers that are useful to you and your application.

Although you can call the identityLink 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.

// create the identity link dictionary
var idLink = new Dictionary();
idLink.Add("username","Ljenkins");
idLink.Add("name","Leroy Jenkins");
// set during initialization in Kochava.cs:
Tracker.Config.setIdentityLinkDictionary(idLink);
...
// ...or send during runtime:
Tracker.SendIdentityLink(idLink);

NOTE: When possible, Identity Link should always be set before initialization using the Tracker.Config.setIdentityLinkDictionary() method. This will ensure that your identity values are always associated with any install postbacks.

iBeacon Detection

NOTE: iBeacon Detection is not included with the standard Kochava SDK , a Unity SDK capable of iBeacon detection is available upon request. For further information on iBeacon Detection, contact a Free App Analytics Client Success Managers.

Files for Download

Kochava_Unity_2.0.3

NOTE: If updating from version 2.0.1 or 2.0.0 you will need to delete the KochavaUnity.dll file located in Assets > Plugins > Kochava after importing the new package. This is necessary as the KochavaUnity.dll is now specific to each platform and is located within the Android and iOS plugin directories.

NOTE: Some browsers may unzip this file automatically. After unzipping you will be left with the unitypackage itself, which is what you will import to your project and should not be unzipped again.

Testing the Integration

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

Unity SDK Integration (Legacy)