Manual Script Implementation
Integrating the SDK
Requirements:
None
Supported Platforms:
Web (Browser)
Data Privacy
Integration:
Estimated Time to Complete
5 Minutes
Copy and paste the following snippet into the head of the site:
function loadScript() {
if (window.pubSuite) {
console.log("pubSuite snippet already included");
return;
}
const pubSuiteScript = document.createElement("script");
pubSuiteScript.type = "text/javascript";
pubSuiteScript.src = "https://storage.googleapis.com/kochava-web-assets/ps/v1.0.0/pubsuite.js";
pubSuiteScript.async = true;
pubSuiteScript.onload = () => {
// YOUR CODE HERE
};
document.head.appendChild(pubSuiteScript);
}
loadScript();
Starting the SDK
Estimated Time to Complete
1 Minute
Once you have added the PubSuite SDK to your project, the next step is to create and start the SDK class in code. Only your Product ID and access token are required to start the SDK with default settings.
Kochava recommends starting the SDK as soon as the application starts, although this can be done later if needed. Starting the tracker as early as possible will ensure it is started before use, resulting in more accurate data/behavior.
Where your web page starts:
Call startWithProductId using your Product ID and access token. Edit the snippet your included earlier to the following:
function loadScript() {
if (window.pubSuite) {
console.log("pubSuite snippet already included");
return;
}
const pubSuiteScript = document.createElement("script");
pubSuiteScript.type = "text/javascript";
pubSuiteScript.src = "https://storage.googleapis.com/kochava-web-assets/ps/v1.0.0/pubsuite.js";
pubSuiteScript.async = true;
pubSuiteScript.onload = () => {
const product_id = 'YOUR_PRODUCT_ID_HERE';
const access_token = 'YOUR _ACCESS_TOKEN_HERE';
window.pubSuite.startWithProductId(product_id, access_token);
};
document.head.appendChild(pubSuiteScript);
}
loadScript();
Optional Configuration
Simplified Element Tracking
For those who don’t have full edit access to the application, a configuration option has been provided that enables a conversion to be sent when an element is clicked on without having to write any code. Simply provide a list of element ids and their associated conversion types in your configuration object, then pass the config object to the SDK via a call to startWithConfig
Example
<script>function loadScript() {
if (window.pubSuite) {
console.log("pubSuite snippet already included");
return;
}
const pubSuiteScript = document.createElement("script");
pubSuiteScript.type = "text/javascript";
pubSuiteScript.src = "https://storage.googleapis.com/kochava-web-assets/ps/test/pubsuite.js?v=0.0.5";
pubSuiteScript.async = true;
pubSuiteScript.onload = function() {
var product_id = "YOUR_PRODUCT_ID_HERE";
var access_token = "YOUR _ACCESS_TOKEN_HERE";
var config = {
"general": {
"product_id": product_id,
"access_token": access_token
}
"element_conversions": {
"id1": "purchase",
"id2": "subscription",
"id3": "ad_initiated",
"id4": "first_open",
"id5": "custom1"
}
}
window.pubSuite.startWithConfig(config);
};
document.head.appendChild(pubSuiteScript);
}
loadScript();</script>
In this example, a click on an element with an id of ‘id1’ will send a ‘purchase’ conversion.
Additionally, any elements that contain the custom data attribute ‘data-ps-conversion’ will also send a conversion when clicked on. A conversion type will need to be provided in the custom data attribute.
Example
<div data-ps-conversion="subscription">
...
</div>
In this example, when the div is clicked, it will send a registration conversion. No additional configuration is needed to enable this functionality.
Adding Metadata to Conversions
Metadata can be included in conversion payloads by adding a ‘conversion_metadata’ field to the configuration object before passing the object to the startWithConfig call.
Example
<script>function loadScript() {
if (window.pubSuite) {
console.log("pubSuite snippet already included");
return;
}
const pubSuiteScript = document.createElement("script");
pubSuiteScript.type = "text/javascript";
pubSuiteScript.src = "https://storage.googleapis.com/kochava-web-assets/ps/test/pubsuite.js?v=0.0.5";
pubSuiteScript.async = true;
pubSuiteScript.onload = function() {
var product_id = "YOUR_PRODUCT_ID_HERE";
var access_token = "YOUR _ACCESS_TOKEN_HERE";
var config = {
"general": {
"product_id": product_id,
"access_token": access_token
}
"element_conversions": {
"id1": "purchase",
"id2": "subscription",
"id3": "ad_initiated",
"id4": "first_open",
"id5": "page_view"
},
"conversion_metadata": {
"user_id": "abcd"
}
}
window.pubSuite.startWithConfig(config);
};
document.head.appendChild(pubSuiteScript);
}
loadScript();</script>
Note: The conversion_metadata fields will be added to all conversion payloads.
Custom Conversion Endpoint
Contact your CSM to learn how to deliver conversion signal to a custom URL.
Using the PubSuite SDK
The following document describes the common use cases for the PubSuite SDK after integration is complete. For information on integrating or configuring and starting the SDK, refer to our PubSuite SDK Integration support doc.
Tracking Conversions
Track user behavior and actions.
Estimated Time to Complete
15 minutes
Examples include purchases, adviews, user registrations, or other noteworthy activity you wish to track. To send a conversion, provide one of the following standard conversion names. Optional custom data can be provided as well.
Example (Send conversion with only standard name)
window.pubSuite.sendConversion('first_open');
Example (Send conversion with custom data as object)
window.pubSuite.sendConversion('purchase', '{
"price": 12.99,
"content_id": "item_1"
})
Allowed Conversion Names and Data
The allowed conversion names are limited to a specific pre-registered list with Kochava. To determine allowed names contact Kochava.
Conversion metadata keys are limited to those in the following list and all values must be sent as a string.
"partner_event_name", "user_id", "url", "duration", "user_name", "description", "referral_from", "method", "results", "content_id", "item_quantity", "sum", "price", "rating_value", "max_rating_value", "level", "currency", "checkout_as_guest", "ad_type", "ad_network", "ad_placement", "ad_mediation_name", "ad_campaign_id", "ad_campaign_name", "ad_size"
Enabling Logging
Enable logging output from the SDK.
Estimated Time to Complete
5 minutes
Logging provides a text-based log of the SDK’s behavior at runtime, for purposes of debugging. Note that logging should be disabled for production deployments, as it will add unnecessary noise and resources consumption.
For example, while testing you may wish to see the contents of certain payloads, in which case you would enable logging at a debug (or higher) level.
Three 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: info
Minimal detail, such as SDK initialization, warnings and errors
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:
window.pubSuite.setLogLevel("Trace");
// If in production:
window.pubSuite.setLogLevel("Info");
Sleeping the SDK
Delay the start of the SDK.
Estimated Time to Complete
10 Minutes
Placing the SDK into sleep mode, the SDK will enter a state where all conversion network transactions will be held and persisted until the SDK is woken up. This can be useful if you wish to start the SDK early and begin tracking conversions but need the SDK to wait before sending conversions.
For example, if you wanted the SDK startup process to have little or no impact on your own loading process, you might start the SDK in sleep mode during the app launch but wait while your app’s resource-intensive loading process completes. When the app’s loading process completes, the SDK can be awoken and will continue with its own startup process without losing any conversions that may have been queued beforehand.
Example (Enabling Sleep Mode Before Starting the SDK):
window.pubSuite.setSleep(true);
window.pubSuite.startWithProductId("YOUR_PRODUCT_ID", "YOUR_ACCESS_TOKEN");
// window.pubSuite.setSleep(false) should be called at a later time to wake the SDK
Shutting Down the SDK
Shutting down the SDK after starting.
Estimated Time to Complete
5 Minutes
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 will cease, conversions 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.
Example (Shut Down the SDK)
window.pubSuite.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 will cause any queued conversions to be lost, and could cause duplicate user metrics.
Example (Clear SDK Data)
// WARNING: This is a destructive action, ensure you understand
// the ramifications of deleting data before using.
window.pubSuite.shutdown(true);