Support Home > Web SDK Integration > Web – Using the SDK

Web – Using the SDK

The following document describes the common use cases for the Kochava Web SDK after integration is complete. For information on integrating the SDK or configuring and starting the Tracker, refer to our Web SDK Integration support documentation.


Estimated Time to Complete
5 Minutes

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.

  1. Double check the SDK configuration in code, ensuring the correct App GUID.
  2. 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.
  3. 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.
  4. 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.

  1. Double check the SDK configuration in code, ensuring the correct App GUID.
  2. Double check your event measurement code and ensure it is reachable.
  3. 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.
  4. 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.
  5. 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.

15 Minutes
Estimated Time to Complete
15 Minutes

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.


Estimated Time to Complete
10 Minutes

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.

 

BEST PRACTICES: Include the name parameter, so that you can easily identify the SKU from the analytics side. It is also highly recommended to set a currency.

 

Example (Standard Purchase Event):

kochava.sendEvent("Purchase", {
  "name": "Loot Box",
  "price": 4.99,
});


10 Minutes
Estimated Time to Complete
10 Minutes

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)

 

BEST PRACTICES: Always set the identity link before sending the event, otherwise the identity link will not be properly associated with the event.

 

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",
});

 


5 Minutes
Estimated Time to Complete
5 Minutes

 

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].


Estimated Time to Complete
10 Minutes

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.

 

BEST PRACTICES: Keep from sending Personal Identifiable Information (PII) such as email addresses or deprecated platform identifiers such as IMEI to Kochava..

 

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");


Estimated Time to Complete
1 Minute

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); });


Estimated Time to Complete
5 Minutes

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");

 

BEST PRACTICES: Logging should be set to info log level or lower for production builds. This will limit the log messages generated by the SDK to errors, warnings, and basic information messages which contain no sensitive information.


Estimated Time to Complete
10 Minutes

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.


5 Minutes
Estimated Time to Complete
5 Minutes

The SDK can be shut down at any time, which will completely disable and stop all features from continuing execution.

The SDK should not be expected to be shutdown in typical scenarios, but this may be useful during consent-applicable cases when consent has been declined or revoked after starting the client and you wish to completely stop all forms of measurement or tracking.

After shutting down, all network communication with Kochava will cease, events will no longer be sent to Kochava, and any API calls will respond as if the SDK had never been started. The SDK must be configured and started again if you wish for measurement to resume.

 

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 allow certain select activities behind the scenes. This includes periodic communication with Kochava for new operating parameters, and ultimately the SDK still presents itself to the host as started. Local persistent data for the SDK is also maintained.

Shutting down the SDK, on the other hand, completely stops the SDK from functioning and no operations will occur until it is configured and started again. Persistent local data for the SDK can be optionally removed as part of the shutdown process using a parameter.


Estimated Time to Complete
5 Minutes

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.

  1. Use an alternate testing App GUID so that your testing activities do not have an impact on your live app analytics.
  2. Enable Logging, if helpful, to gain insight into the SDK’s behavior during runtime.
  3. 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.
  4. 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:

  1. A handshake with Kochava may be made to determine dynamic settings for this app.
  2. If this is the first launch, the install data is sent to Kochava (this only happens once).
  3. At this point the SDK is idle and awaits requests from the app.
  4. 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.

 
 
Last Modified: Feb 23, 2024 at 4:51 pm