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

Web – Using the SDK

This feature is available only with paid Kochava accounts. Contact us to learn more.

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.


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

 


 

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


 

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


 

Example (Getting the Kochava Device ID):

kochava.getDeviceId((guid) => { console.log(guid); });


 

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

 


 

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

 

 

Example (Waking the SDK from Sleep Mode)

kochava.setSleep(false);

 


5 Minutes
Estimated Time to Complete
5 Minutes
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);

 


  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: Jun 12, 2024 at 8:25 am