Support Home > SDK Integration > Unity SDK Integration

Unity SDK Integration

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:

  • IDE Level 5.0 or later
  • 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

  1. 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.
  2. Switch to the first scene in your Unity application
    This scene should only be loaded once when your application is run.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. Usage analytics will begin appearing in your Kochava.com dashboard.
  8.  

    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:

    1. The Kochava SDK requires Google Play Services – Base and Google Play Services – Basement.
    2. Optionally – Kochava 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:

    • Kochava App GUID
      The unique GUID for your app – available in your Kochava.com dashboard.
      Should look like: kounitysdktest31950c6bcb3007b5
    • Kochava 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 Kochava server, usually in less than 10 seconds from the initial application launch. 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 the attribution data will be delivered to the KochavaAttributionListener() method included in the Kochava.cs file. For Android you can optionally set your own listener using Tracker.Android.SetAttributionHandler() immediately after initialization; simply pass in any method with a signature of: void AttributionCallback(string data).

     

    Attribution data via static method (if available at the time of the call):

     

    • 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):

     

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

     

    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 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 Kochava’s analytics interface. Kochava 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, Kochava’s 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.

     

    Sending In App Purchase Receipts


    • 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 Kochava 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 Kochava Events

    • Kochava 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, Kochava will repost it after a one minute rest period.
    • If an application is paused or exited, Kochava will automatically serialize this queue into persistent storage and rebuild it on the next app launch. This allows Kochava to record events with an extremely high degree of reliability, even if the user’s device is offline. This also allows Kochava to record events (such as application exits) which would normally be impossible to send to the server.

     

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

    • Kochava 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.

    Email Attribution (Android Only)

    If enabled in the Kochava 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:


    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 Kochava database.

    Kochava reports can be output 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.

    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.


    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 Kochava account manager.


    Files for Download

    Unity SDK Release Notes

     

    Kochava_Unity_2.0.0

     

    Version for Android that cannot collect email addresses:

    If an Android build that does not have the capability to collect email is needed, please contact your account manager.

     


    Testing the Integration

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

     
     

    Last Modified: Mar 14, 2017 at 8:48 am