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.

To learn more, see our Cross-Device Attribution FAQ and Web Attribution FAQ.

Prerequisites

Before you integrate the Singular Website SDK, make sure these prerequisites are satisfied:

• Google Tag Manager has been configured on your site.
• You have set up Google Tag Manager triggers as needed for the events that you want to send to Singular (your conversion event and any custom events).
• You have set up Google Tag Manager variables as needed for the events you want to send to Singular. For example, if you want to send transaction events and include the transaction revenue, you need to set up variables for the transaction sum and currency.

Tag 1 - Adding the SDK Library

The Singular JavaScript Library must be loaded or injected on the site before the Singular SDK is initialized or any Singular functions are triggered. To ensure this, the library will be injected using the Custom HTML tag option in Google Tag Manager (GTM).

To maintain proper functionality, the library must be included on all pages of the site. We will use the Window Loaded trigger in GTM to control the timing of the library injection, ensuring it loads after the page content is fully loaded.

• Create a Custom HTML tag to load the SDK Library and Add permission to fetch client hints data.
• Name the Tag "Singular - SDK Loader"
• Insert the following Code into the HTML window

  <script>
  (function() {
    // Check if singularSdk is already loaded
  
    if (window.singularSdk) {
      return; // SDK already loaded, no need to load again
  
    }
  
    // Inject the meta tag for client hints delegation
  
    var metaTag = document.createElement('meta');
    metaTag.setAttribute('http-equiv', 'delegate-ch');
    metaTag.setAttribute('content', 'sec-ch-ua-model https://sdk-api-v1.singular.net; sec-ch-ua-platform-version https://sdk-api-v1.singular.net; sec-ch-ua-full-version-list https://sdk-api-v1.singular.net');
    document.head.appendChild(metaTag);
    
    // Create and load the Singular SDK script
  
    var script = document.createElement('script');
    script.src = 'https://web-sdk-cdn.singular.net/singular-sdk/latest/singular-sdk.js';
    script.async = true;
  
    // Once the script is loaded, push to dataLayer
  
    script.addEventListener('load', function() {
      window.dataLayer = window.dataLayer || [];  // Ensure dataLayer is initialized
  
      window.dataLayer.push({
        event: 'singularSDKLibraryLoaded'
      });
    });
  
    // Append the script tag to the head of the document
  
    document.head.appendChild(script);
  })();
  </script>
  

• Under Advanced Settings, set the Tag firing priority to 99
• Under the Triggering section, add a Firing Trigger for "Window Loaded"
• Save the Tag

Tag 2 - SDK Initialization Tag

The Singular SDK initialization code must be executed every time a page is loaded, but only after the Singular - SDK Loader tag has fired. To ensure this, we will use the Data Layer event created by the Singular - SDK Loader tag as the trigger.

Initializing the Singular SDK is a prerequisite for all Singular attribution functionality. It serves two critical purposes:

• Creating a new user session when a user enters the site with new advertising data or when the session timeout has elapsed.
• Sending a "page visit" event to Singular.

These "page visit" events and user sessions are essential for calculating user retention and enabling re-engagement attribution. 

// Configure the SDK to pass the user ID to Singular

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

Sending the User ID to Singular (Optional)

You may send your internal User ID to Singular using a Singular SDK method.

• The User ID can be any identifier and should not expose PII (Personally Identifiable Information). For example, you should not use a User's email address, username, or phone number. Singular recommends using a hashed value unique only to your first-party data.
• The User ID value passed to Singular should also be the same internal User ID you capture across all platforms (Web/Mobile/PC/Console/Offline).
• Singular will include the User ID in user-level exports, ETL, and Internal BI postbacks (if configured). The User ID is first-party data, and Singular does not share it with other parties.
• The User ID value, when set with the Singular SDK Method, will persist until it is unset using the logout() method or until the browser local storage is deleted. Closing or refreshing the website does not unset the User ID.
• In private/incognito mode, the SDK cannot persist the user ID because the browser automatically deletes the local storage when it is closed.

To set the User ID, use the login() method. To unset it (for example, if the User "logs out" of the account), call logout() method.

If you already know the user ID when the Singular SDK is initialized on the website, set the User ID in the config object. This way, Singular can have the User ID from the first Session. However, the User ID is typically unavailable until the User registers or performs a login. In that case, call login() after the registration flow is complete. It is recommended to push a datalayer Event when a user performs an Authentication flow which can be used with a GTM Custom Event Trigger to fire the Singular Login function.

• Create a Custom HTML tag to handle Authentication
• Name the Tag "Singular - Authentication Tag"
• Insert the following Code into the HTML window

  <script>
  (function() {
    // Ensure sessionStorage is available
  
    if (typeof sessionStorage === 'undefined') {
      console.warn('sessionStorage is not supported in this environment.');
      return;
    }
  
    // Check if the event has already been triggered in this session
  
    if (sessionStorage.getItem('sng_login_triggered')) {
      console.log('Singular SDK event already triggered this session.');
      return; // Exit if the event was triggered before in this session
  
    }
  
    // Check if singularSdk is available and initialized
  
    if (window.singularSdk && typeof singularSdk.login === 'function' && typeof singularSdk.event === 'function') {
      
      // Dynamically fetch UserID if available (replace with actual method if applicable)
  
      var userID = window.userID || "User123456789"; // Example fallback value for userID
  
  
      try {
        // After Authentication, Pass the UserID as the Singular Custom User ID Value
  
        singularSdk.login(userID);
  
        // Send the Registration_Completed event (or similar event)
  
        singularSdk.event("sng_login");
  
        // Set a flag in sessionStorage to indicate that the event was triggered
  
        sessionStorage.setItem('sng_login_triggered', 'true');
  
        console.log('Singular SDK event triggered successfully.');
      } catch (error) {
        console.error('Error triggering Singular SDK event:', error);
      }
    } else {
      console.warn('Singular SDK is not loaded or required methods are unavailable.');
    }
  })();
  </script>
  

• Under the Triggering section, add a Firing Trigger for a Custom Event.
• Name the Trigger: "singularAuthentication"
• Specify the Trigger Event name corresponding to the datalayer Event name available after a user Authenticates on your website.
• Save the Tag