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 track. Events can be instrumented either by using the standard format provided by the SDK or using your own custom event name and data.
Custom Events:
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 (Send a Custom Event with Only a Name, no Event Data) —
kochava.sendEvent("Player Defeated");
Example (Send a Custom Event with Event Data) —
kochava.sendEvent("Player Defeated", "Angry Ogre");
Example (Send an Event with Additional Data) —
kochava.sendEvent("Enemy Defeated", {
"enemy": "Angry Ogre"
});
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.
Tracking Purchases:
Track in-app purchases 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):
kochava.sendEvent("Purchase", {
"name": "Loot Box",
"price": 4.99,
});
Tracking Subscriptions and Trials:
Track user subscriptions and free trials.
In order to effectively track user subscriptions and free trials, an event should be instrumented at the time of the subscription purchase or start of the free trial along with an accompanying identity link.
When a subscription or free trial begins, first set an identity link for this subscriber and then instrument a standard Subscription or Trial event populated with the following values:
- Price
- Currency
- Product Name
- User or Subscriber ID (hash suggested)
- Receipt (if available)
Example (Identity Link with Subscription):
// first set an identity link for this user
kochava.registerIdentityLink("Subscriber ID", "ABCDEF123456789");
// next, instrument the subscription event
kochava.sendEvent("Subscribe", {
"price": 9.99,
"currency": "usd",
"name": "Monthly Subscription",
"user_id": "ABCDEF123456789",
});
A free trial is handled in a similar way, although the price should be set to 0 and the event type should indicate Trial rather than Subscription. The product name should remain the same, as the event type indicates whether this was free trial or subscription.
Example (Identity Link with Free Trial):
// first set an identity link for this user
kochava.registerIdentityLink("Subscriber ID","ABCDEF123456789");
// next, instrument the trial event
kochava.sendEvent("Start Trial", {
"price": 0.0,
"currency": "usd",
"name": "Monthly Subscription",
"user_id": "ABCDEF123456789",
});
Pages:
Track which pages on the site were visited by a user.
Pages are dedicated events sent to kochava, for the purpose of seeing which pages on a particular site are visited by the user. The name of the page will automatically be detected by the SDK, but an optional string can be passed in to override the page name. The page event can also include other useful data in the form of an object.
Example (Send a Page with Current Page Name):
kochava.sendPageEvent();
Example (Send a Page with Current Page Name and Additional Data):
// In order to get the current page name alongside additional data, you must pass the empty string "" as the first argument to the function.
kochava.sendPageEvent("", {
"instructions_step": 5,
});
Example (Send a Page with Overwritten Page Name):
kochava.sendPageEvent("Instructions Step 5");
Example (Send a Page with Overwritten Page Name and Additional Data):
kochava.sendPageEvent("Instructions", {
"step": 5,
});
Auto Page:
By default a page event with the current page name will automatically be sent following the start of the SDK. To disable this feature, refer to your chosen integration method’s integration instructions: [Integration documentation].
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 (Set an Identity Link):
kochava.registerIdentityLink("User ID", "123456789");
kochava.registerIdentityLink("Login", "username");
Example (Set an Identity Link with the Install):
// Ensure setSleep: true was passed in when configuring the sdk during the integration step. kochava.registerIdentityLink("User ID", "123456789"); // ... // When you are ready to send the install kochava.setSleep(false);// Wherever you call start, call registerIdentityLink first kochava.registerIdentityLink("User ID", "123456789"); kochava.startWithAppGuid("YOUR_APP_GUID");
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):
kochava.getDeviceId((guid) => { console.log(guid); });
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):
// If in non-production and wanting to debug:
kochava.setLogLevel("Trace");
// If in production:
kochava.setLogLevel("Info");
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 Before Starting the SDK):
kochava.setSleep(true);
kochava.startWithAppGuid("YOUR_APP_GUID");
// kochava.setSleep(false) should be called at a later time
Example (Enabling Sleep Mode After Starting the SDK):
kochava.setSleep(true);
// kochava.setSleep(false) should be called at a later time
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 SDK from Sleep Mode) —
kochava.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 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.
Shutting Down the Measurement Client:
Shutting down the SDK after starting.
The SDK can be shut down after starting, which will completely disable the SDK and stop all tracking from continuing.
The SDK should not be shutdown in typical scenarios, but this may be useful during consent-applicable instances when consent has been declined or revoked after starting the SDK and you wish to completely stop tracking the user.
After shutting down, all network communication with Kochava will cease, events will no longer queue, and any API calls will fail just as if the SDK had never been started. The SDK must be configured and started again if you wish for tracking to resume.
NOTE: Shutting down and restarting the SDK should not be done frequently during the same app launch without an explicit reason for doing so. While it is thread safe, frequent shutdown and restart could cause contention between storage and background tasks in-flight, resulting in incomplete or unintended task completion. If you would like additional guidance for your specific implementation please contact our support team.
Example (Shut Down the SDK) —
kochava.shutdown(false);
Clearing SDK Data:
The shutdown() method accepts a boolean indicating whether you wish to also clear all persisted SDK data from disk when shutting down. This should always be set to false and should never be set to true without a complete understanding of the ramifications of clearing this data, as it could create duplicate user metrics or worse.
Example (Clear SDK Data) —
// WARNING: This is a destructive action, ensure you understand the
// ramifications of deleting data before using.
kochava.shutdown(true);
Shutdown vs. Sleep:
The SDK’s Sleep() functionality can also be used to temporarily prevent the SDK from sending data to Kochava. However, Sleep() will continue to queue events and track the user, but will simply not send that data to Kochava until awoken. For this reason, Sleep() should not be used as a solution for consent-applicable situations because tracking is still queuing locally and may be sent on the next app launch.
Shutting down the SDK, on the other hand, completely stops the SDK from functioning and no tracking will occur until it is configured and started again.
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 “uninstall” the app before each test. On web, simply clearing the browsers cache and refreshing should be sufficient for this purpose.
- Test your Kochava integration. For more information see: Testing the Integration.
// If in non-production and wanting to debug:
kochava.setLogLevel("Trace");
kochava.startWithAppGuid("YOUR_TEST_APP_GUID");
// If in production:
kochava.setLogLevel("Info");
kochava.startWithAppGuid("YOUR_PROD_APP_GUID");
Analyzing SDK Behavior:
While testing your integration, it is important to understand the tracker’s basic flow of operations. When the tracker 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 SDK will process the request and perform any necessary network calls before returning to an idle state.
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.
