Web – Using the SDK

Collapse

Example (Standard Purchase Event):

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

Collapse

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

Collapse

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

Collapse

Example (Set an Identity Link):

kochava.registerIdentityLink("User ID", "123456789");
kochava.registerIdentityLink("Login", "username");

Example (Set an Identity Link with the Install):

Collapse

Example (Getting the Kochava Device ID):

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

Collapse

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

Collapse

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

Collapse

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

Collapse

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.

Collapse