Singular Website SDK: Native Integration

Follow
Avatar
Eyal Rabinovich
Updated

The Singular Website SDK is an enterprise feature. If you're interested in using this feature, reach out to your Customer Success Manager.

Singular Website SDK
Download Singular Website SDK version 1.3.5
Browser Compatibility
  • Chrome: 15+
  • Safari: 5.1+
  • Edge: 15+
  • Firefox: 6+
  • Internet Explorer: 10+
  • Opera: 15+

 

Introduction

The Singular Website SDK allows you to attribute website activities to marketing touchpoints and to track user events within your website. It is also a key component in Singular’s cross-device attribution solution, making it possible to analyze user journeys and calculate cross-platform LTV and ROAS.

In addition to the native JavaScript version described here, the Singular Website SDK is also available as a Google Tag Manager Template.

Adding the SDK Script to Your Site

Use one of the following methods to set up the SDK on your website or web app.

Linking to the Script on Singular's CDN

In this method, Singular hosts the SDK JavaScript code on Singular's CDN.

Add the following code inside the <head> tag of each page you want to track:

<head>
    <!-- Using the latest SDK version   -->
    <script src="https://web-sdk-cdn.singular.net/singular-sdk/latest/singular-sdk.js">
    </script>
</head>

Note: The code above links to the latest version of the SDK. If you want to use a specific version of the SDK, use the following code instead:

<head>
    <!-- Using a fixed SDK version   -->
    <script src="https://web-sdk-cdn.singular.net/singular-sdk/1.3.5/singular-sdk.js">
    </script>
</head>

Setting Up Using NPM

  1. Run npm i singular-sdk in your project’s root directory, or add "singular-sdk": "^1.3.5" to the dependencies section in your package.json file and then run npm install.
  2. Add the following code in the scripts you want to use the SDK.
import {singularSdk, SingularConfig} from "singular-sdk";

Initializing the SDK

The SDK initialization code should be called every time a page is loaded. It is a prerequisite to all Singular attribution functionality, and it also:

  • Creates a new user session when a user enters the site with new advertising data or when the session timeout has passed.
  • Sends a new "page visit" event to Singular

Page visits events and user sessions are used to calculate user retention and enable re-engagement attribution.

1. Constructing the SingularConfig Object

Before you can initialize the SDK, you have to create a SingularConfig object. This object will contain:

  • SDK Key and SDK Secret: To find these, log into your Singular account and go to Developer Tools > SDK Keys.
  • Your Product ID: A name for your website. We recommend using the reverse DNS notation of your main web domain, e.g., “com.example”. This will be used to identify your website throughout the Singular platform. This value must also match the App bundleID on the Apps Page in the Singular platform.
  • Optionally, any SDK preferences you may want to set (read on for details).

To create a basic SingularConfig object use this code:

const config = new SingularConfig(sdkKey, sdkSecret, productId);

However, you will probably want to add settings to enable various capabilities offered by Singular.

To add settings, you will use the SingularConfig object's ".with" methods. For example:

// Configure the SDK to pass the user ID to Singular
const config = new SingularConfig(sdkKey, sdkSecret, productId)
    .withCustomUserId(userId);

SingularConfig Method Reference

Here are all the available ".with" methods.

Method Description Learn More
.withCustomUserId(customId) Send the user ID to Singular Setting the User ID
.withProductName(productName) An optional display name for the product  
.withLogLevel(logLevel) Configure the logging level: 0 - None (Default); 1 - Warn; 2 - Info; 3 - Debug.  
.withSessionTimeoutInMinutes (timeout) Set the session timeout in minutes (default: 30 minutes)

 
.withAutoPersistentSingularDeviceId (domain) Enable automatic cross-subdomain tracking Auto-Persist using Cookies

.withPersistentSingularDeviceId (singularDeviceId)

 Enable manual cross-subdomain tracking Set Singular Device ID Manually
.withInitFinishedCallback(callback) Invoke a callback when SDK initialization is complete Invoking a Callback Function when Initialization is Complete

2. Initializing Singular

After creating the SingularConfig object, initialize Singular using the init method, passing the config object.

The init method can be called at any point in the code but must get called before any event is reported. We recommend calling init during the loading of each page you want to track.

init Method
Description Initialize the SDK with configuration options set in the SingularConfig object.
Signature init(config)
Usage Example 
function initSingular() {
    const config = new SingularConfig(sdkKey, 
        sdkSecret, productId);
    singularSdk.init(config);
}

Important: For Single Page Applications (SPAs), call singularSdk.pageVisit() every time you route to a different page. Do not call singularSdk.pageVisit() on the first page that is loaded since singularSdk.init already reports a page visit.

Invoking a Callback Function when Initialization is Complete

To set a callback function to be invoked once initialization is done, use .withInitFinishedCallback(callback) on the SingularConfig object.

withInitFinishedCallback Method
Description Sets the callback which will be invoked once the initialization process is finished.
Signature withInitFinishedCallback(callback)
Usage Example 
function initSingular() {      
  const config = new SingularConfig(sdkKey, sdkSecret, productId)
    .withInitFinishedCallback(initParams=> {
      // This callback will be called when the init method has finished

      // You can get Singular Device id here
      const singularDeviceId = initParams.singularDeviceId;
    });
singularSdk.init(config);
}

Optional: Setting the User ID

The Singular SDK can send a user ID from your website to Singular. This can be a username, email address, randomly generated string, or whichever identifier you use as a user ID.

Singular uses the user ID in user-level data exports as well as internal BI postbacks (if you configure such postbacks).

There are two ways to send the user ID to Singular:

  • Recommended: If you know the user ID when the website opens, set the user ID in the SingularConfig object before initializing the SDK. This makes the user ID available to Singular from the very first page visit. 
    const config = new SingularConfig(sdkKey, sdkSecret, productId)
    .withCustomUserId("custom_user_id");
singularSdk.init(config);
  • Alternatively, you can call the login method at any point in the run. We recommend calling it as soon as the user ID becomes available.

Notes:

  • The user ID persists until you unset it using the logout method or until the user deletes their local storage.
  • Closing/refreshing the website does not unset the user ID.
  • When a user browses in private/incognito mode, the SDK cannot persist the user ID because the local storage is deleted automatically when the browser is closed.
login Method
Description Sends the user ID to Singular.
Signature login(customUserId)
Usage Example 
singularSdk.login("custom_user_id");
logout Method
Description Unset the user ID that has been sent to Singular.
Signature logout()
Usage Example 
singularSdk.logout();

Optional: Tracking Events and Revenue

Tracking Events

Singular can collect data about user events within the site to help analyze the performance of your campaigns and measure KPIs. For example, your organization may want to collect data about user logins, registrations, or tutorial completions.

You can send events to Singular using the event method.

Note:

  • We highly recommend passing event names and attributes in English to guarantee compatibility with third-party partners and analytics solutions if you plan to use them.
  • Event names are limited to 32 ASCII characters. Strings in non-ASCII characters have to be under 32 bytes once converted to UTF-8.
  • Attributes and values are limited to 500 ASCII characters.
event Method
Description Report a user event to Singular with or without additional information.
Signature

singularSdk.event(eventName, args)

Note: 'args' is a JavaScript map object. If you don’t want to pass any additional args call the event method with only the event name.
Usage Example 
// Send a Registration_Completed event with no arguments
singularSdk.event("Registration_Completed");

// Send an event called "Registration_Completed" 
// with email and phone number
singularSdk.event("Registration_Completed",
{phone: '111-222-3333',
email: 'example@mail.com'});

Tracking Revenue

Singular can collect data about revenue gained through the website to help analyze the performance and ROI of your campaigns. Singular will make the data available to you in reports, log exports, and postbacks.

Use the revenue method to report events. Revenue allows you to pass a custom event name, so that you'll be able to view revenue in Singular reports broken down by the different types of revenue events.

Notes: Any revenue reported in a different currency will be auto-converted to your organization's preferred currency, as set in your Singular account.

revenue Method
Description Send a revenue event to Singular with optional additional information.
Signature

singularSdk.revenue(eventName, currency, amount, args)

Note:

  • Pass currency as a three-letter ISO 4217 currency code, such as “USD”, “EUR”, or “INR".
  • The amount value can be passed as a decimal value.
Usage Example 
// Send a revenue event to Singular 
singularSdk.revenue("Item_Purchased","USD", 5.50);

// Send a revenue event to Singular with additional args
singularSdk.revenue("Item_Purchased","USD", 5.50,
{phone: '111-222-3333',
 email: 'example@mail.com');

Optional: Cross-Subdomain Tracking

By default, the Singular Website SDK generates a Singular Device ID and persists it using browser storage. Since this storage can't be shared between subdomains, the SDK ends up generating a new ID for each subdomain.

If you want to persist the Singular Device ID across subdomains, you can use one of the following options:

Method A: Auto-Persist using Cookies

You can have the Singular SDK persist the Singular Device ID using a custom first-party cookie. Use the following method and set the main domain you want to track.

withAutoPersistentSingularDeviceId Method
Description Initialize the SDK with configuration options including the main domain for auto persisting Singular Device Id.
Signature withAutoPersistentSingularDeviceId(domain)
Usage Example 
function initSingular() {
  const config = new SingularConfig(sdkKey, sdkSecret, productId)
    .withAutoPersistentSingularDeviceId(“example.com”);
  singularSdk.init(config);
}

Method B (Advanced): Set Singular Device ID Manually

If you don’t want Singular SDK to persist the Device ID automatically, you can persist the ID manually across domains - for example, using a top-level domain cookie or a server-side cookie. The value should be an ID previously generated by Singular, in valid uuid4 format.

Note: You can read the Singular Device ID using singularSdk.getSingularDeviceId() after calling the init method or using InitFinishedCallback.

withPersistentSingularDeviceId Method

Description

Initialize the SDK with configuration options including the Singular Device Id you want to persist.
Signature withPersistentSingularDeviceId(singularDeviceId)
Usage Example 
function initSingular() {
  const config = new SingularConfig(sdkKey, sdkSecret, productId)
    .withPersistentSingularDeviceId(singularDeviceId);
  singularSdk.init(config);
}

Custom User ID Device Mapping

Important: This is an advanced feature. Consult with one of Singular’s Solution Engineers before implementing it.

Singular can receive additional web tracking data via server to server integration. In order to utilize this feature, we need to map the custom user id to Singular’s web tracking identifier.

Note: Call this method as soon as possible after initializing the SDK or once you have the custom user id.

setDeviceCustomUserId Method
Description Sets the Custom User Id the same as login and maps it to Singular’s web tracking identifier.
Signature

singularSdk.setDeviceCustomUserId(userId)
Usage Example 
// Sets the custom user id and maps it to Singular’s web tracking identifier
singularSdk.setDeviceCustomUserId(customUserId);