Confirming the SDK Integration:
Ensure the SDK has been properly integrated.
After integrating the SDK or creating a new App GUID, we suggest performing these tests to ensure the SDK has been integrated successfully and is functioning as expected within your app.
Validate the Install:
The SDK will send an install for the app once, after a fresh install. This test ensures the SDK was configured properly and successfully sent the install to Kochava.
- Double check the SDK configuration in code, ensuring the correct App GUID.
- Run the app for approximately 30 seconds, which will allow more than enough time for the SDK to start and send an install to Kochava under typical conditions.
- Wait a minute or two and visit the Install Feed Validation page for your app within the Kochava dashboard, under Apps & Assets > Install Feed Validation. Within that page, look for the Integration Success! message which indicates integration was successful and that Kochava did receive an install from the SDK. At this point you have confirmed a successful SDK integration and can move ahead to Validate Post Install Events below.
- If instead you see a Integration Not Complete! message, wait a few more minutes and refresh the page. After refreshing, if the Integration Not Complete! message persists, double check the following, then repeat this test:
- Correct App GUID is used within SDK code configuration.
- Ensure the SDK configuration and startup code is being reached.
- Ensure the network connection from the test device is not limited behind a firewall or otherwise.
Validate Event Measurement:
If you are measuring user events, you can use this test to ensure the SDK was configured properly and is successfully sending these events to Kochava.
- Double check the SDK configuration in code, ensuring the correct App GUID.
- Double check your event measurement code and ensure it is reachable.
- Launch the app and perform necessary actions within the app to trigger the event(s) you wish to test. After performing these actions, wait 60 seconds to allow more than enough time for the SDK to send these events.
- Wait a minute or two and visit the Event Manager page for your app within the Kochava dashboard, under Apps & Assets > Event Manager. Within that page, ensure the tested event names are displayed here, in which case you have confirmed the SDK is successfully measuring these events.
- If your event names are not displayed here after waiting a few minutes, double check the following, then repeat this test:
- Correct App GUID is used within SDK code configuration.
- Ensure the SDK configuration and startup code is being reached prior to any event code.
- Ensure the SDK event code is being reached.
- Ensure the network connection from the test device is not limited behind a firewall or otherwise.
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 measure. 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 measure. 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.
- Send the event.
Example (Standard Event with Standard Parameters) —
var myEvent = new EventParameters(EventType.Purchase);
myEvent.SetName("Gold Token");
myEvent.SetPrice(0.99f);
SharedInstance.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) —
var myEvent = new EventParameters(EventType.LevelComplete);
myEvent.SetName("The Deep Dark Forest");
myEvent.SetCustomValue("info","{\"attempts\":3,\"score\":12000}");
SharedInstance.Tracker.SendEvent(myEvent);
If you wish to use a custom event type for your standard event, choose the Custom standard event type and then call the SetCustomEventName method with your desired event name. Be aware that if you choose the Custom type but do not also provide a custom event name, the event name will simply appear as “Custom”.
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 method to send the custom event.
Example (Send a Custom Event with Only a Name, no Event Data) —
SharedInstance.Tracker.SendEvent("Player Defeated","");
Example (Send a Custom Event with Event Data) —
SharedInstance.Tracker.SendEvent("Player Defeated","Angry Ogre");
Example (Send a Custom Event with Additional JSON Data) —
SharedInstance.Tracker.SendEvent("Player Defeated","{\"enemy\":\"Angry Ogre\"}");
Example (Standard Event of Custom Type with Custom Parameters) —
var myEvent = new EventParameters(KochavaWRT.EventType.Custom);
myEvent.SetCustomEventName("Enemy Defeated");
myEvent.SetCustomValue("info","{\"enemy\":\"The Angry Ogre\",\"reward\":\"Gold Token\"}");
SharedInstance.Tracker.SendEvent(myEvent);
NOTE: No custom event name pre-registration is required. However, a maximum of 100 unique event names can be measured 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:
SendEvent(string, string)
SendEvent(EventParameters)
EventParameters
Purchases and Subscriptions:
Track in-app purchases, subscriptions, and revenue.
In-app purchases and subscription can be easily measured 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.
Example (Standard Purchase Event):
var myEvent = new EventParameters(EventType.Purchase);
myEvent.SetPrice(4.99);
myEvent.SetName("Loot Box");
myEvent.SetCurrency("usd");
SharedInstance.Tracker.SendEvent(myEvent);
Example (Custom Purchase Event with Additional JSON Data):
SharedInstance.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) —
var myEvent = new EventParameters(EventType.Purchase);
myEvent.SetPrice(9.99);
myEvent.SetName("Monthly Subscription");
SharedInstance.Tracker.SendEvent(myEvent);
Example (Custom Subscription Event with Additional JSON Data) —
SharedInstance.Tracker.SendEvent("Purchase","{\"price\":4.99,\"name\":\"Loot Box\",\"receipt\":\""+myPurchaseReceiptXMLString+"\"}");
Developer API Reference:
SendEvent(string, string)
SendEvent(EventParameters)
EventParameters
Deeplinking:
Track deeplink related actions and user activity.
Measuring deeplinks is accomplished similar to any other type of event. In order to measure 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):
var myEvent = new EventParameters(EventType.DeepLink);
myEvent.SetUri("some_deeplink_uri");
SharedInstance.Tracker.SendEvent(myEvent);
Developer API Reference:
Tracker.SendEvent(string, string)
Tracker.SendEvent(EventParameters)
EventParameters
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 register this identity link information in the form of unique key and value pair(s) as early as possible. This can be done during the initial configuration of the measurement client if the identity link information is already known, or it can be done after starting the client.
Example (Register an Identity Link During Tracker Configuration):
var config = new Config();
config.AppGUID = "_YOUR_APP_GUID_";
config.SetIdentityLink("User ID","123456789");
config.SetIdentityLink("Login","username");
SharedInstance.Initialize(config);
Example (Register an Identity Link After Starting the Tracker):
SharedInstance.Tracker.SetIdentityLink("User ID","123456789");
SharedInstance.Tracker.SetIdentityLink("Login","username");
Developer API Reference:
Config.SetIdentityLink(string, string)
Tracker.SetIdentityLink(string, string)
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 measurement client when requested and returned to the app asynchronously via a callback. This process usually takes about 3-4 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):
var config = new Config();
config.AppGUID = "_YOUR_APP_GUID_";
config.SetAttributionResultsListener(new AttributionResultsListener(delegate (string results) {
// got the attribution results, now we need to parse it
if(JsonObject.TryParse(results, out JsonObject attributionDictionary))
{
// do something with attributionDictionary...
}
});
SharedInstance.Initialize(config);
Example (Using the Getter After Attribution Results Have Been Retrieved):
var results = SharedInstance.AttributionData;
if(results.Length>0) {
// got the attribution results, now we need to parse it
if(JsonObject.TryParse(results, out JsonObject attributionDictionary))
{
// 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:
Config.SetAttributionResultsListener(string, string)
AttributionResultsListener
Tracker.AttributionData
Getting The Kochava Device ID:
Obtain the unique device identifier assigned by Kochava.
If at any time after starting the measurement client you would like to get the universally unique identifier assigned to this install by Kochava, this identifier can be obtained by calling the retrieve function.
Example (Getting the Kochava Device ID):
string myKochavaDeviceId = SharedInstance.Tracker.DeviceId;
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:
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):
var config = new Config();
config.AppGUID = "_YOUR_APP_GUID_";
config.AppLimitAdTracking = true;
SharedInstance.Initialize(config);
Example (Enable App Limit Ad Tracking After Starting the Tracker):
SharedInstance.Tracker.AppLimitAdTracking = true;
Developer API Reference:
Config.AppLimitAdTracking
Tracker.AppLimitAdTracking
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. |
To enable logging, subscribe to Kochava.Tracker.LoggingEvent and set the desired log level during tracker configuration. When the tracker runs, each log message will be delivered to your event handler where you can output the message to the console or handle it some other way.
Example (Enabling trace logging in a non-production build):
// subscribe to the log event and configure the tracker with the desired log level
// (taking care that logging is only enabled in development builds)
var config = new Config();
config.AppGUID = "_YOUR_APP_GUID_";
#if DEBUG
config.LogLevel = LogLevel.trace;
Tracker.LoggingEvent += new LoggingEventHandler(delegate (string message) {
// output the message to the debug window
System.Diagnostics.Debug.WriteLine(message);
});
#endif
SharedInstance.Initialize(config);
Developer API Reference:
Config.LogLevel
Tracker.LoggingEvent
LoggingEventHandler
LogLevel
Sleeping the Tracker:
Delay the start of the tracker.
Placing the measurement client into sleep mode, the client will enter a state where all non-essential network transactions will be held and persisted until the client is woken up. This can be useful if you wish to start the client early but need the measurement client to wait before sending install data or events to Kochava servers.
For example, if you wanted the measurement startup process to wait for permission prompts, you might start the measurement client in sleep mode during the app launch but wait while the user provides input. Once ready, the measurement client 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):
var config = new Config();
config.AppGUID = "_YOUR_APP_GUID_";
config.Sleep = true;
SharedInstance.Initialize(config);
Example (Enabling Sleep Mode After Starting the Tracker):
SharedInstance.Tracker.Sleep = true;
Once you are ready to wake the measurement client simply set the sleep state to false. At that point the client will wake up and continue as normal, sending any waiting install data or queued events.
Example (Waking the Tracker from Sleep Mode) —
SharedInstance.Tracker.Sleep = 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 measurement client sleeping permanently. This allows the client 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 client is never woken from sleep mode, events and other activity will continue to build up in the queue, causing undesirable results.
Developer API Reference:
Consent — GDPR:
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.
GDPR applies to users within the EU and requires users to opt-in to data collection. For common questions and answers regarding both GDPR and CCPA consent models, refer to our Handling Consent support documentation.
Intelligent Consent Management:
As GDPR 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. For more information on this feature, see: Intelligent Consent Management
Self Managed Consent:
If you choose not to use our Intelligent Consent Management feature and you are handling consent on your own or using a 3rd party tool, startup and use of the tracker should not occur until after you have determined consent is not required or consent has been granted. Any calls to the tracker should be wrapped in this check, so that if a user revokes consent later calls to the tracker will stop. Ensure that the tracker has been started before any calls to the tracker are made when going this route.
Example (Starting the Tracker Only When Consent Allows) —
if(consentRequired == false || consentGranted == true) {
// we will not initialize Kochava unless consent requirements are met
SharedInstance.Initialize("_YOUR_APP_GUID_");
}
Example (Calling Tracker Methods Only When Consent Allows) —
if(consentRequired == false || consentGranted == true) {
// we will not call Kochava methods unless consent requirements are met
// (and we will make sure the tracker has been initialized)
if(SharedInstance.IsInitialized == true) {
SharedInstance.Tracker.SendEvent("My Event","");
}
}
NOTE: All consent-related API calls (such as granting or declining consent) will have no effect unless the Intelligent Consent Management feature has been enabled in code and has also been setup in your Kochava dashboard. Do not use these methods if you are handling consent on your own or through a 3rd party tool.
Consent — CCPA:
Handle CCPA and consent requirements.
CCPA applies to users within California and allows users to opt out of the sale of their data.
For purposes of CCPA, the Kochava Tracker SDK follows IAB’s CCPA Compliance Framework by reading the U.S. Privacy String from local storage, when present. The app or any entity within the app can set this string any time.
This means that if IAB’s U.S. Privacy String has been set within the app, the Kochava Tracker SDK will automatically adorn installs and post-install events with it’s value, when present. By doing so, CCPA consent status via the U.S. Privacy String can be associated with all user tracking and syndicated downstream for interested 3rd parties.
You do not need to take any action in the Kochava Tracker SDK for this functionality. However, it is your responsibility to ensure the U.S. Privacy String has been set within local storage when appropriate. The SDK will look for the U.S. Privacy String in local app storage under the key ‘IABUSPrivacy_String’ within default shared preferences on Android and default NSUserDefaults on iOS. As long as the value is present, the SDK will pick it up.
For more information regarding SDK-based solutions for CCPA, refer to our Handling Consent support documentation.
Intelligent Consent Management:
Kochava’s fully managed consent solution.
As GDPR 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. For complete details on how this feature works, see: Intelligent Consent Management.
Setting Up a Test Environment:
Create a test environment to ensure the integration is working properly.
During testing, debugging, and non-production app development, the following steps will help you get the most out of your test environment and help to ensure your integration is working properly.
- Use an alternate testing App GUID so that your testing activities do not have an impact on your live app analytics.
- Enable Logging, if helpful, to gain insight into the SDK’s behavior during runtime.
- If you would like the SDK to behave as it would during a new install, be sure to un-install the app before each test.
- Test your Kochava integration. For more information see: Testing the Integration.
Keep in mind that you should always add logic to ensure that you do not accidentally release to production a build with a development configuration used. Below is an example of how this type of configuration might look.
var config = new Config();
#if DEBUG
// development build configuration
config.AppGUID = "_YOUR_TEST_APP_GUID_";
config.IsDevelopment = true;
config.LogLevel = LogLevel.trace;
Tracker.LoggingEvent += new LoggingEventHandler(delegate (string message) { System.Diagnostics.Debug.WriteLine(message); });
#else
// production build configuration
config.AppGUID = "_YOUR_PRODUCTION_APP_GUID_";
config.LogLevel = LogLevel.none;
#endif
SharedInstance.Initialize(config);
In debug mode, the Config.IsDevelopment flag should be set to true during configuration to avoid handled exceptions or sluggish operation from the SDK while attempting to collect unavailable data from sideloaded apps, such as the campaign id and install receipt. This flag should explicitly be set only when debug mode is known, as the SDK itself has no knowledge of whether the app was compiled in debug or release mode.
Analyzing SDK Behavior:
While testing your integration, it is important to understand the measurement client’s basic flow of operations. When the client is started the following sequence of events occur:
- A handshake with Kochava may be made to determine dynamic settings for this app.
- If this is the first launch, the install data is sent to Kochava (this only happens once).
- At this point the SDK is idle and awaits requests from the app.
- If a request is made to the SDK by the app, the request is moved to a background thread for processing. After processing the request and performing any necessary network calls the SDK returns to an idle state.
- When the app is terminated or suspended, a session-end payload may be sent to Kochava.
- When the app is resumed or relaunched, a session-begin payload may be sent to Kochava.
NOTE: While testing, keep in mind that data sent from the SDK may sometimes be delayed up to a few minutes before being displayed within the Kochava analytics dashboard.
