The following document describes the common use cases for the Kochava SDK after integration is complete. For information on integrating the SDK or configuring and starting the Tracker, refer to our Unity SDK Integration support documentation.
Tracking Events:
Track user behavior and actions beyond the install.
Examples include in-app purchases, level completions, or other noteworthy user activity you wish to track. Events can be instrumented either by using the standard format provided by the SDK or using your own custom event name and data.
Standard Events:
Standard events are built by first selecting a standard event type and then setting any applicable standard parameters you wish to include with the event. For example, you might choose a Purchase standard event type and set values for the Price and Name parameters. There are a variety of standard event types to choose from and dozens of standard parameters available. When creating a standard event, you only need to set values for the parameters you wish to track. A maximum of 16 parameters can be set.
- Create an event object using the desired standard event type.
- Set the desired parameter value(s) within the event object.
- Pass the event object to the tracker’s Send Event method.
Example (Standard Event with Standard Parameters) —
|
1 2 3 4 |
Kochava.Event myEvent = new Kochava.Event (Kochava.EventType.Purchase); myEvent.name = "Gold Token"; myEvent.price = 0.99; Kochava.Tracker.SendEvent (myEvent); |
Custom event parameters (which can also be serialized JSON) may also be set within a standard event.
Example (Standard Event with Standard and Custom Parameters) —
|
1 2 3 4 5 |
Kochava.Event myEvent = new Kochava.Event (Kochava.EventType.LevelComplete); myEvent.name = "The Deep Dark Forest"; myEvent.SetCustomValue ("attempts", 3); myEvent.SetCustomValue ("score", 12000); Kochava.Tracker.SendEvent (myEvent); |
For a detailed list of standard event types and parameters, see: Post Install Event Examples
Custom Events:
For scenarios where the standard event types and standard parameters do not meet your needs, custom events can be used. To instrument a custom event, pass the event’s name and data (which can also be serialized JSON) to the tracker’s Send Event method.
Example (Custom Event with Custom Parameters) —
|
1 2 3 4 |
Kochava.Event myEvent = new Kochava.Event ("Enemy Defeated"); myEvent.SetCustomValue ("enemy", "The Angry Ogre"); myEvent.SetCustomValue ("reward", "Gold Token"); Kochava.Tracker.SendEvent (myEvent); |
Example (Send a Custom Event with Only a Name, no Event Data) —
|
1 |
Kochava.Tracker.SendEvent ("Player Defeated"); |
Example (Send a Custom Event with Event Data) —
|
1 |
Kochava.Tracker.SendEvent ("Player Defeated", "Angry Ogre"); |
Example (Send a Custom Event with Serialized JSON Data) —
|
1 |
Kochava.Tracker.SendEvent ("Player Defeated", "{\"enemy\":\"Angry Ogre\"}"); |
NOTE: No custom event name pre-registration is required. However, a maximum of 100 unique event names can be tracked within the Kochava dashboard (including any standard event types also used), so keep this in mind as you create new custom event names.
Developer API Reference:
Kochava.Tracker.SendEvent(String)
Kochava.Tracker.SendEvent(String, String)
Kochava.Tracker.SendEvent(Kochava.Event)
Kochava.Event
Purchases and Subscriptions:
Track in-app purchases, subscriptions, and revenue.
In-app purchases and subscription can be easily tracked and attributed by creating a purchase event. To accomplish this, simply create an event of type Purchase and include the total amount of revenue as the price value within the event data parameters.
Purchases:
Example (Standard Purchase Event) —
12345Kochava.Event myEvent = new Kochava.Event (Kochava.EventType.Purchase);myEvent.price = 4.99;myEvent.name = "Loot Box";myEvent.setReceiptFromGooglePlayStore (receiptOriginalJson, receiptSignature);Kochava.Tracker.SendEvent (myEvent);-
12345Kochava.Event myEvent = new Kochava.Event (Kochava.EventType.Purchase);myEvent.price = 4.99;myEvent.name = "Loot Box";myEvent.setReceiptFromAppleAppStoreBase64EncodedString (receiptBase64EncodedString);Kochava.Tracker.SendEvent (myEvent);
-
1234Kochava.Event myEvent = new Kochava.Event (Kochava.EventType.Purchase);myEvent.price = 4.99;myEvent.name = "Loot Box";Kochava.Tracker.SendEvent (myEvent);
Example (Custom Purchase Event with Serialized JSON Data) —
|
1 |
Kochava.Tracker.SendEvent ("Purchase", "{\"price\":4.99,\"name\":\"Loot Box\"}"); |
Subscriptions:
Subscriptions are tracked no differently than purchase events. When a subscription purchase has surfaced within the app, create and send a purchase event.
Example (Standard Subscription Purchase Event) —
12345Kochava.Event myEvent = new Kochava.Event (Kochava.EventType.Purchase);myEvent.price = 9.99;myEvent.name = "Monthly Subscription";myEvent.setReceiptFromGooglePlayStore (receiptOriginalJson, receiptSignature);Kochava.Tracker.SendEvent (myEvent);-
12345Kochava.Event myEvent = new Kochava.Event (Kochava.EventType.Purchase);myEvent.price = 9.99;myEvent.name = "Monthly Subscription";myEvent.setReceiptFromAppleAppStoreBase64EncodedString (receiptBase64EncodedString);Kochava.Tracker.SendEvent (myEvent);
-
1234Kochava.Event myEvent = new Kochava.Event (Kochava.EventType.Purchase);myEvent.price = 9.99;myEvent.name = "Monthly Subscription";Kochava.Tracker.SendEvent (myEvent);
Example (Custom Subscription Purchase Event with Serialized JSON Data) —
|
1 |
Kochava.Tracker.SendEvent ("Purchase", "{\"price\":9.99,\"name\":\"Monthly Subscription\"}"); |
Developer API Reference:
Tracker.sendEvent(String, String)
Tracker.sendEvent(Event)
Tracker.Event
Deeplinking:
Track deeplink related actions and user activity.
Tracking deeplinks is accomplished similar to any other type of event. In order to track a deeplink event, create a standard event of type Deeplink and set the uri parameter along with any other relevant parameters to the values provided when the deeplink occurred.
Example (Standard Deeplink Event):
|
1 2 3 4 |
Kochava.Event myEvent = new Kochava.Event (Kochava.EventType.DeepLink); myEvent.uri = "some_deeplink_uri"; myEvent.source = "some_source_application"; Kochava.Tracker.SendEvent (myEvent); |
Example (Custom Deeplink Event with Serialized JSON Data):
|
1 |
Kochava.Tracker.SendEvent ("_Deeplink", "{\"uri\":\"some_deeplink_uri\"}"); |
Developer API Reference:
Kochava.Tracker.SendEvent(String, String)
Kochava.Tracker.SendEvent(Kochava.Event)
Kochava.Event
Identity Linking:
Link existing user identities with kochava devices.
Setting an Identity Link provides the opportunity to link different identities together in the form of key and value pairs. For example, you may have assigned each user of your app an internal ID which you want to connect to a user’s service identifier. Using this feature, you can send both your internal ID and their service identifier to connect them in the Kochava database.
In order to link identities, you will need to pass this identity link information in the form of unique key and value pairs to the tracker as early as possible. This can be done during tracker configuration if the identity link information is already known, or it can be done after starting the tracker using the Set Identity Link method.
Example (Set an Identity Link During Tracker Configuration):
|
1 2 3 4 5 6 7 8 |
// An Identity Link cannot be set in the configuration object. Instead it must be set directly after starting the Kochava SDK. // This can be done during the Start lifecycle stage // or during the Awake lifecycle stage if the KochavaConfiguration.cs occurs first in the Script Execution Order list. Dictionary<string, string> identityLink = new Dictionary<string, string> (); identityLink.Add ("User ID","123456789"); identityLink.Add ("Login","ljenkins"); Kochava.Tracker.SetIdentityLink (identityLink); |
Example (Set an Identity Link After Starting the Tracker):
|
1 2 3 4 |
Dictionary<string, string> identityLink = new Dictionary<string, string> (); identityLink.Add ("User ID","123456789"); identityLink.Add ("Login","ljenkins"); Kochava.Tracker.SetIdentityLink (identityLink); |
Developer API Reference:
Kochava.Tracker.SetIdentityLink(Dictionary
Retrieving Attribution:
Access the attribution results within the app.
Install attribution results can be retrieved from Kochava servers if you wish to use these results within your app. Be aware that attribution results are always determined by Kochava servers; this feature simply provides the app with a copy of whatever the results were.
For example, you may wish to present a user with a different path if you have determined they installed the app from a certain advertising network or source.
Attribution results are fetched by the tracker as soon as requested and returned to the app asynchronously via a callback. This process usually takes about 7-10 seconds but can take longer depending on network latency and other factors. Once attribution results have been retrieved for the first time, they are not retrieved again and the results are persisted. From that point on they can be queried synchronously by calling the attribution data getter which always provides the persisted attribution results from the original retrieval.
NOTE: For purposes of deferred deeplinking, care should be taken to act upon the attribution results only once, as the original results will continue to be reported after the first retrieval, and are not refreshed on a per-launch basis.
Example (Requesting Attribution Results):
Your attribution listener can be configured using the Unity Event Inspector UI. When using this method ensure that you select your method with the “Dynamic string” setting in the UI and that the targeted GameObject cannot be destroyed.
-
12345678Kochava.Tracker.Config.SetAppGuid ("_YOUR_APP_GUID_");Kochava.Tracker.Config.SetRetrieveAttribution (true);Kochava.Tracker.SetAttributionHandler ((attribution) => {// got the attribution results, now we need to parse it.Dictionary<string, object> attributionDictionary = JsonFx.Json.JsonReader.Deserialize<Dictionary<string, object>>(attribution);// do something with attributionDictionary...});Kochava.Tracker.Initialize ();
Example (Using the Getter After Attribution Results Have Been Retrieved):
|
1 2 3 4 5 6 |
string attribution = Kochava.Tracker.GetAttribution(); if (attribution.Length > 0) { // got the attribution results, now we need to parse it. Dictionary<string, object> attributionDictionary = JsonFx.Json.JsonReader.Deserialize<Dictionary<string, object>>(attribution); // do something with attributionDictionary... } |
Once you have the attribution results, you will need to parse and handle them in some meaningful way. A variety of data exists within this json object and you will need to determine which data is meaningful for your purposes. For an overview of the attribution dictionary contents, see: Attribution Response Examples.
NOTE: If you wish to send attribution results to your own server, this should be done directly through Kochava’s postback system, rather than retrieving attribution in the app and then sending the results to your own server.
Developer API Reference:
Kochava.Tracker.Config
Kochava.Tracker.SetAttributionHandler(AttributionCallbackDelegate)
Kochava.AttributionCallbackDelegate
string Kochava.Tracker.GetAttribution()
Getting The Kochava Device ID:
Obtain the unique device identifier assigned by Kochava.
If at any time after starting the tracker you would like to get the unique identifier assigned to this device by Kochava, this string (represented as a GUID) can be obtained by calling the device id getter.
Example (Getting the Kochava Device ID):
|
1 |
string myKochavaDeviceId = Kochava.Tracker.GetDeviceId(); |
NOTE: If you have enabled the Intelligent Consent Management feature, this unique device ID may change between consent status changes when consent is required and has not been granted.
Developer API Reference:
string Kochava.Tracker.GetDeviceId()
Getting the SDK Version:
Obtain the current version of the SDK.
Example (Getting the SDK Version String)
|
1 |
string sdkVersion = Kochava.Tracker.GetVersion (); |
Developer API Reference:
string Kochava.Tracker.GetVersion()
Enabling App Limit Ad Tracking:
Limit the ad tracking at the application level.
If you wish to limit ad tracking at the application level, with respect to Kochava conversions, you can set this value during or after configuration. By default the limit ad tracking state is not enabled (false).
For example, you might provide an option for a user to indicate whether or not they wish to allow this app to use their advertising identifier for tracking purposes. If they do not wish to be tracked, this value would be set to true.
Example (Enabling App Limit Ad Tracking During Tracker Configuration):
123Kochava.Tracker.Config.SetAppGuid ("_YOUR_APP_GUID_");Kochava.Tracker.Config.SetAppLimitAdTracking (true);Kochava.Tracker.Initialize ();
Example (Enable App Limit Ad Tracking After Starting the Tracker):
|
1 |
Kochava.Tracker.SetAppLimitAdTracking (true); |
Developer API Reference:
Kochava.Tracker.Config
Kochava.Tracker.SetAppLimitAdTracking(bool)
Enabling Logging:
Enable logging output from the SDK.
Logging provides a text-based log of the SDK’s behavior at runtime, for purposes of debugging.
For example, while testing you may wish to see the contents of certain payloads being sent to Kochava servers, in which case you would enable logging at a debug (or higher) level.
Six different log levels are available, each of which include all log levels beneath them. Info log level is set by default, although trace log level should be used when debugging so that all possible log messages are generated.
| Log Level: none
No logging messages are generated. |
| Log Level: error
Errors which are usually fatal to the tracker. |
| Log Level: warn
Warnings which are not fatal to the tracker. |
| Log Level: info
Minimal detail, such as tracker initialization. |
| Log Level: debug
Granular detail, including network transaction payloads. |
| Log Level: trace
Very granular detail, including low level behavior. |
Example (Enabling trace logging in a non-production build):
123Kochava.Tracker.Config.SetAppGuid ("_YOUR_APP_GUID_");Kochava.Tracker.Config.SetLogLevel (Debug.isDebugBuild ? Kochava.DebugLogLevel.trace : Kochava.DebugLogLevel.info);Kochava.Tracker.Initialize ();
Developer API Reference:
Kochava.Tracker.Config
Kochava.DebugLogLevel
Sleeping the Tracker:
Delay the start of the tracker.
Android and iOS only.
Placing the tracker into sleep mode, the tracker will enter a state where all non-essential network transactions will be held and persisted until the tracker is woken up. This can be useful if you wish to start the tracker early and begin tracking events but need the tracker to wait before sending events or the install data to Kochava servers.
For example, if you wanted the tracker startup process to have little or no impact on your own loading process, you might start the tracker in sleep mode during the app launch but wait while your app’s resource-intensive loading process completes. When the app’s loading process completes, the tracker can be woken and will continue with its own startup process without losing any events that may have been queued beforehand.
Example (Enabling Sleep Mode During Tracker Configuration):
123Kochava.Tracker.Config.SetAppGuid ("_YOUR_APP_GUID_");Kochava.Tracker.Config.SetSleep (true);Kochava.Tracker.Initialize ();
Example (Enabling Sleep Mode After Starting the Tracker):
|
1 |
Kochava.Tracker.SetSleep (true); |
Once you are ready to wake the tracker simply set the sleep state to false. At that point the tracker will wake up and continue as normal, sending any queued events or install data.
Example (Waking the Tracker from Sleep Mode):
|
1 |
Kochava.Tracker.SetSleep (false); |
NOTE: For every call to set sleep to true, there should be a matching call at some point setting sleep to false. While these calls do not necessarily have to be balanced, care should be taken to not inadvertently leave the tracker asleep permanently. This allows the tracker to wake up and continue with necessary logic and processing of data. Any events or other activity queued while sleeping will be held but not sent until sleep mode is set to false. This means that if the tracker is never woken from sleep mode, events and other activity will continue to build up in the queue, causing undesirable results and resource usage.
Developer API Reference:
Kochava.Tracker.Config
Kochava.Tracker.SetSleep(bool)
bool Kochava.Tracker.GetSleep()
GDPR and Consent:
Handle GDPR and consent requirements.
The Kochava SDK does deal with GDPR-sensitive data, such as device identifiers. Care should be taken to ensure that your use of the Kochava SDK remains GDPR compliant when applicable.
Example (Starting the Tracker Only When Consent Allows) —
|
1 2 3 4 5 |
if(!consentRequired || consentGranted) { // we will not initialize Kochava unless consent requirements are met Kochava.Tracker.Config.SetAppGuid ("_YOUR_APP_GUID_"); Kochava.Tracker.Initialize (); } |
Example (Calling Tracker Methods Only When Consent Allows) —
|
1 2 3 4 5 6 7 |
if(!consentRequired || consentGranted) { // we will not call Kochava methods unless consent requirements are met // (and we will make sure the tracker has been initialized) if (Kochava.IsInitialized ()) { Kochava.Tracker.SendEvent("My Event"); } } |
Intelligent Consent Management:
Kochava’s fully managed consent solution.
Push Engagement:
Kochava’s push services.
