[NEW] Singular Website SDK: Native Integration

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


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:

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

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:

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

Setting Up Using NPM

  1. Run `npm i singular-sdk` in your project’s root directory or add `"singular-sdk": "^1.0.10"` 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 sends a new page visit to Singular. Page visits are used to calculate user retention.

1. Constructing the SingularConfig Object

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

  • Your API Key, API Secret and Product Id.
  • Optionally, any SDK preferences you may want to set.

To create a basic SingularConfig object use this code:

const config = new SingularConfig(apiKey, secretKey, 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(apiKey, secretKey, productId)

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 (default is Log.None) None = 0
Warn = 1
Info = 2
Debug = 3

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(apiKey, 
secretKey, 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.

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("apikey","secret",“productId”)
  • 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.


  • 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.
  • Browsing in private mode such as incognito will prevent us from persisting the user id since the local storage is deleted automatically when closing the browser.
login Method
Description Sends the user ID to Singular.
Signature login(customUserId)
Usage Example
logout Method
Description Unset the user ID that has been sent to Singular.
Signature logout()
Usage Example

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.


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

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

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


  • Pass currency as a three-letter ISO 4217 currency code, such as “USD”, “EUR”, or “INR".
  • 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');


Was this article helpful?
0 out of 0 found this helpful