Download the WebSDK version 1.4.3

Overview

INFO: Web Attribution is an enterprise feature. Contact your Customer Success Manager to enable this feature for your account.

This guide walks through implementing the Singular WebSDK using native JavaScript. This method provides the most reliable tracking and is recommended for most implementations because it is not blocked by common ad blockers.

IMPORTANT!

Do not implement both Native JavaScript and Google Tag Manager methods. Choose only one to avoid duplicate tracking.
The Singular WebSDK is designed to run client-side in a user's browser. It requires access to browser features such as localStorage and the Document Object Model (DOM) to function correctly. Do not attempt to run the SDK server-side (for example, via Next.js SSR or node.js)—this will cause tracking failures, as server environments do not provide access to browser APIs.

Prerequisites

Before starting, ensure you have:

SDK Key & SDK Secret:
- Where to find them: Log into your Singular account and navigate to Developer Tools > SDK Integration > SDK Keys.
Product ID:
- What it is: A unique name for your website, ideally using reverse DNS format (e.g., com.website-name).
- Why it matters: This ID associates the website as an App in Singular and must match the Web App bundleID listed on your Apps Page in Singular.
Permission to edit your website's HTML code.
Access to add JavaScript in the <head> section of your pages.
A list of events you want to track. View our Singular Standard Events: Full List and Recommended Events by Vertical for ideas.

Implementation Steps

Step 1: Add the SDK Library Script

Add the following code snippet to the <head> section of every page on your website. Place it as early as possible, ideally near the top of the <head> tag.

TIP! Adding the script early ensures the Singular JavaScript Library is available for any Singular functions in your page source code.

<script src="https://web-sdk-cdn.singular.net/singular-sdk/latest/singular-sdk.js"></script>

Specify the specific version in the path of the WebSDK JavaScript library, for example: 1.4.3 is noted here:

<script src="https://web-sdk-cdn.singular.net/singular-sdk/1.4.3/singular-sdk.js"></script>

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

Using with Next.js / React

Next.js is a React framework that provides server-side rendering (SSR), static site generation (SSG), and React Server Components. Since the Singular WebSDK requires browser APIs (DOM, localStorage, cookies), you must load it client-side only.

IMPORTANT: Never load the Singular SDK in server-side code (e.g., getServerSideProps, React Server Components, or Node.js environments). This will cause errors because browser APIs are not available on the server.

Method 1: Using Next.js Script Component (Recommended)

The <Script> component from Next.js provides optimized loading strategies and prevents duplicate script injection across route changes.

// pages/_app.tsx (Pages Router) or app/layout.tsx (App Router)
import Script from 'next/script'

export default function App({ Component, pageProps }) {
  return (
    <>
      <Script
        src="https://web-sdk-cdn.singular.net/singular-sdk/latest/singular-sdk.js"
        strategy="afterInteractive"
      />
      <Component {...pageProps} />
    </>
  )
}

Script Strategy Options:

afterInteractive (recommended): Loads after the page becomes interactive - ideal for analytics and tracking.
lazyOnload: Loads during browser idle time - use for non-critical widgets.

Method 2: Dynamic Import for Component-Level Loading

For component-level control, use Next.js dynamic imports with ssr: false to load the script only when needed:

// pages/index.tsx
import dynamic from 'next/dynamic'

const SingularSDKLoader = dynamic(
  () => import('../components/SingularSDKLoader'),
  { ssr: false }
)

export default function Page() {
  return (
    <div>
      <SingularSDKLoader />
      <h1>Your Page Content</h1>
    </div>
  )
}

// components/SingularSDKLoader.tsx
'use client' // Required for Next.js App Router

import { useEffect } from 'react'

export default function SingularSDKLoader() {
  useEffect(() => {
    // Load Singular SDK script dynamically
    const script = document.createElement('script')
    script.src = 'https://web-sdk-cdn.singular.net/singular-sdk/latest/singular-sdk.js'
    script.async = true
    document.body.appendChild(script)
    
    // Cleanup on unmount
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script)
      }
    }
  }, [])
  
  return null
}

Environment Variables Setup

TIP! Store your Singular credentials in environment variables prefixed with NEXT_PUBLIC_ to make them available in the browser:

# .env.local
NEXT_PUBLIC_SINGULAR_SDK_KEY=your_sdk_key_here
NEXT_PUBLIC_SINGULAR_SDK_SECRET=your_sdk_secret_here
NEXT_PUBLIC_SINGULAR_PRODUCT_ID=com.your-website

These environment variables will be accessible in your client-side code and can be used during initialization in Step 2.

App Router vs Pages Router

Router Type	Key Differences	Script Location
App Router (Next.js 13+)	Components are server components by default. Add `'use client'` directive for browser APIs.	`app/layout.tsx`
Pages Router (Next.js 12 and earlier)	All components are client components by default.	`pages/_app.tsx`

Step 2: Initialize the SDK

Always initialize the SDK each time a page loads in the browser.
Initialization is required for all Singular attribution and event tracking features.
Initialization triggers a __PAGE_VISIT__ event.
The __PAGE_VISIT__ event is used to generate a new Session servers-side when the following conditions are met:
- The user arrives with new advertising data in the URL (such as UTM or WP parameters), or
- The previous session has expired (after 30 minutes of inactivity).
- Sessions are used to measure user retention and support re-engagement attribution.

Create an Initialization function and call this function on DOM Ready after page load.
Ensure initialization occurs before any other Singular events are reported.
For Single-Page Applications (SPA), initialize the Singular SDK on first page load and then call the Singular Page Visist function window.singularSdk.pageVisit() on every route change that represents a new page view.

Basic DOM-Ready Initialization

Add an Event Listener to call the initSingularSDK() on DOMContentLoaded

/**
 * Initializes the Singular SDK with the provided configuration.
 * @param {string} sdkKey - The SDK key for Singular.
 * @param {string} sdkSecret - The SDK secret for Singular.
 * @param {string} productId - The product ID for Singular.
 * @example
 * initSingularSDK(); // Initializes SDK with default config
 */
function initSingularSDK() {
  var config = new SingularConfig('sdkKey', 'sdkSecret', 'productId');
  window.singularSdk.init(config);
}

/**
 * Triggers Singular SDK initialization when the DOM is fully parsed.
 */
document.addEventListener('DOMContentLoaded', function() {
  initSingularSDK();
});

Basic Initialization with Global Properties

Due to the Singular SDK not being initialized, you must implement the custom function to set the Global Properties in the localstorage of the browser. See the custom function setGlobalPropertyBeforeInit(). Once implemented you can set properties as outlined below before the initialization of the SDK.

/**
 * Initializes the Singular SDK with the provided configuration.
 * @param {string} sdkKey - The SDK key for Singular.
 * @param {string} sdkSecret - The SDK secret for Singular.
 * @param {string} productId - The product ID for Singular.
 * @example
 * initSingularSDK(); // Initializes SDK with default config
 */
function initSingularSDK() {
  var sdkKey = 'sdkKey';
  var sdkSecret = 'sdkSecret';
  var productId = 'productId';
  
  // Set global properties before SDK initialization
  setGlobalPropertyBeforeInit(sdkKey, productId, 'global_prop_1', 'test', false);
  setGlobalPropertyBeforeInit(sdkKey, productId, 'global_prop_2', 'US', true);
  
  // Initialize SDK
  var config = new SingularConfig('sdkKey', 'sdkSecret', 'productId');
  window.singularSdk.init(config);
}

/**
 * Triggers Singular SDK initialization when the DOM is fully parsed.
 */
document.addEventListener('DOMContentLoaded', function() {
  initSingularSDK();
});

Basic Initialization with Single-Page Application (SPA) Routing

Scenario	What to Do
First page load	Call `window.singularSdk.init(config)`
Navigating to a new route/page	Call `window.singularSdk.pageVisit()`
On initial load in SPA	Do not call `window.singularSdk.pageVisit()` (The initialization will provide the first page visit event.)

Example for SPAs (React)

import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

/**
 * Initializes the Singular SDK with the provided configuration.
 * @param {string} sdkKey - The SDK key for Singular.
 * @param {string} sdkSecret - The SDK secret for Singular.
 * @param {string} productId - The product ID for Singular.
 * @example
 * // Initialize the Singular SDK
 * initSingularSDK();
 */
function initSingularSDK() {
  var config = new SingularConfig('sdkKey', 'sdkSecret', 'productId');
  window.singularSdk.init(config);
}

/**
 * Tracks a page visit event with the Singular SDK on route changes.
 * @example
 * // Track a page visit
 * trackPageVisit();
 */
function trackPageVisit() {
  window.singularSdk.pageVisit();
}

/**
 * A React component that initializes the Singular SDK on mount and tracks page visits on route changes.
 * @returns {JSX.Element} The component rendering the SPA content.
 * @example
 * // Use in a React SPA with react-router-dom
 * function App() {
 *   const location = useLocation();
 *   useEffect(() => {
 *     initSingularSDK();
 *   }, []);
 *   useEffect(() => {
 *     trackPageVisit();
 *   }, [location.pathname]);
 *   return <div>Your SPA Content</div>;
 * }
 */
function App() {
  const location = useLocation();

  useEffect(() => {
    initSingularSDK();
  }, []); // Run once on mount for SDK initialization

  useEffect(() => {
    trackPageVisit();
  }, [location.pathname]); // Run on route changes for page visits

  return (
    <div>Your SPA Content</div>
  );
}

export default App;

Basic Initialization Using an Initialization Callback

If you need to run code after the SDK is ready (for example, to get the Singular Device ID), set a callback with .withInitFinishedCallback():

/**
 * Initializes the Singular SDK with a callback to handle initialization completion.
 * @param {string} sdkKey - The SDK key for Singular.
 * @param {string} sdkSecret - The SDK secret for Singular.
 * @param {string} productId - The product ID for Singular.
 * @example
 * initSingularSDK(); // Initializes SDK and logs device ID
 */
function initSingularSDK() {
  var config = new SingularConfig('sdkKey', 'sdkSecret', 'productId')
    .withInitFinishedCallback(function(initParams) {
      var singularDeviceId = initParams.singularDeviceId;
      // Example: Store device ID for analytics
      console.log('Singular Device ID:', singularDeviceId);
      // Optionally store in localStorage or use for event tracking
      // localStorage.setItem('singularDeviceId', singularDeviceId);
    });

  window.singularSdk.init(config);
}

/**
 * Triggers Singular SDK initialization when the DOM is fully parsed.
 */
document.addEventListener('DOMContentLoaded', function() {
  initSingularSDK();
});

Next.js / React Initialization

After loading the SDK script in Step 1, initialize it when the DOM is ready. The initialization must occur client-side after the script has loaded.

TypeScript Type Declarations

Create a type declaration file to add TypeScript support for the Singular SDK:

// types/singular.d.ts
interface SingularConfig {
  new (sdkKey: string, sdkSecret: string, productId: string): SingularConfig;
  withCustomUserId(userId: string): SingularConfig;
  withAutoPersistentSingularDeviceId(domain: string): SingularConfig;
  withLogLevel(level: number): SingularConfig;
  withSessionTimeoutInMinutes(timeout: number): SingularConfig;
  withProductName(productName: string): SingularConfig;
  withPersistentSingularDeviceId(singularDeviceId: string): SingularConfig;
  withInitFinishedCallback(callback: (params: { singularDeviceId: string }) => void): SingularConfig;
}

interface SingularSDK {
  init(config: SingularConfig): void;
  event(eventName: string, attributes?: Record<string, any>): void;
  conversionEvent(eventName: string): void;
  revenue(eventName: string, currency: string, amount: number, attributes?: Record<string, any>): void;
  login(userId: string): void;
  logout(): void;
  pageVisit(): void;
  buildWebToAppLink(baseLink: string): string;
  getSingularDeviceId(): string;
  setGlobalProperties(key: string, value: string, override: boolean): void;
  getGlobalProperties(): Record<string, string>;
  clearGlobalProperties(): void;
}

interface Window {
  singularSdk: SingularSDK;
  SingularConfig: typeof SingularConfig;
}

Basic Initialization with Next.js Script Component

When using the Script component from Step 1, add the onLoad callback to initialize the SDK:

// pages/_app.tsx or app/layout.tsx
import Script from 'next/script'

export default function App({ Component, pageProps }) {
  return (
    <>
      <Script
        src="https://web-sdk-cdn.singular.net/singular-sdk/latest/singular-sdk.js"
        strategy="afterInteractive"
        onLoad={() => {
          // Initialize Singular SDK after script loads
          const config = new (window as any).SingularConfig(
            process.env.NEXT_PUBLIC_SINGULAR_SDK_KEY,
            process.env.NEXT_PUBLIC_SINGULAR_SDK_SECRET,
            process.env.NEXT_PUBLIC_SINGULAR_PRODUCT_ID
          );
          window.singularSdk.init(config);
        }}
      />
      <Component {...pageProps} />
    </>
  )
}

Initialization with useEffect Hook

If you're using the dynamic import method or need more control, initialize using useEffect:

// components/SingularInitializer.tsx
'use client'

import { useEffect } from 'react'

export default function SingularInitializer() {
  useEffect(() => {
    // Wait for script to load, then initialize
    const checkAndInit = () => {
      if (window.singularSdk && window.SingularConfig) {
        const config = new window.SingularConfig(
          process.env.NEXT_PUBLIC_SINGULAR_SDK_KEY!,
          process.env.NEXT_PUBLIC_SINGULAR_SDK_SECRET!,
          process.env.NEXT_PUBLIC_SINGULAR_PRODUCT_ID!
        );
        window.singularSdk.init(config);
      } else {
        // Retry if SDK not loaded yet
        setTimeout(checkAndInit, 100);
      }
    };
    
    checkAndInit();
  }, []); // Empty dependency - run once on mount
  
  return null;
}

Initialization with Configuration Options

Chain .with methods to enable additional features like cross-subdomain tracking or custom user IDs:

const config = new window.SingularConfig(
  process.env.NEXT_PUBLIC_SINGULAR_SDK_KEY!,
  process.env.NEXT_PUBLIC_SINGULAR_SDK_SECRET!,
  process.env.NEXT_PUBLIC_SINGULAR_PRODUCT_ID!
)
  .withAutoPersistentSingularDeviceId('your-domain.com')
  .withCustomUserId(userId)
  .withLogLevel(2); // 0=None, 1=Warn, 2=Info, 3=Debug

window.singularSdk.init(config);

Single-Page Application (SPA) Routing

For Next.js applications with client-side routing, you need to track route changes separately from the initial initialization.

IMPORTANT: Initialize the SDK only once on first page load. Then call window.singularSdk.pageVisit() on every subsequent route change.

// components/SingularPageTracker.tsx
'use client'

import { useEffect, useRef } from 'react'
import { usePathname } from 'next/navigation' // App Router
// or import { useRouter } from 'next/router' // Pages Router

export default function SingularPageTracker() {
  const pathname = usePathname() // App Router
  // const router = useRouter(); const pathname = router.pathname // Pages Router
  const isInitialized = useRef(false);

  // Initialize SDK once on mount
  useEffect(() => {
    if (!isInitialized.current && window.singularSdk && window.SingularConfig) {
      const config = new window.SingularConfig(
        process.env.NEXT_PUBLIC_SINGULAR_SDK_KEY!,
        process.env.NEXT_PUBLIC_SINGULAR_SDK_SECRET!,
        process.env.NEXT_PUBLIC_SINGULAR_PRODUCT_ID!
      );
      window.singularSdk.init(config);
      isInitialized.current = true;
    }
  }, []); // Empty dependency - runs once

  // Track page visits on route changes (NOT on initial mount)
  useEffect(() => {
    if (isInitialized.current && window.singularSdk) {
      window.singularSdk.pageVisit();
    }
  }, [pathname]); // Runs when pathname changes

  return null;
}

Using an Initialization Callback

If you need to run code after the SDK is ready (for example, to get the Singular Device ID), use .withInitFinishedCallback():

const config = new window.SingularConfig(
  process.env.NEXT_PUBLIC_SINGULAR_SDK_KEY!,
  process.env.NEXT_PUBLIC_SINGULAR_SDK_SECRET!,
  process.env.NEXT_PUBLIC_SINGULAR_PRODUCT_ID!
)
  .withInitFinishedCallback((initParams) => {
    const singularDeviceId = initParams.singularDeviceId;
    console.log('Singular Device ID:', singularDeviceId);
    // Store for analytics or pass to other services
  });

window.singularSdk.init(config);

Best Practices for Next.js Initialization

Initialize the SDK only once on application mount, not on every route change.
Use environment variables with the NEXT_PUBLIC_ prefix for SDK credentials.
For SPAs, call window.singularSdk.pageVisit() on route changes to track navigation.
Use useRef to track initialization state and prevent duplicate initialization.
Add null checks for window.singularSdk before calling methods to prevent errors during SSR.
Test in development mode to ensure the SDK initializes correctly without server-side errors.

Developer Checklist for Next.js

Verify the script loaded successfully in Step 1.
Set up environment variables with your SDK credentials.
Create TypeScript type declarations for better developer experience.
Choose initialization method: Script component onLoad or useEffect hook.
For SPAs, implement route change tracking with pageVisit().
Test initialization by checking the console for the __PAGE_VISIT__ event.

Replace 'sdkKey' with your actual SDK Key.
Replace 'sdkSecret' with your actual SDK Secret.
Replace 'productId' with your actual Product ID. It should look like: com.website-name and it should match the BundleID value on the Apps page in the Singular platform.

Configuration Options

Enhance the WebSDK setup by chaining .with methods to enable extra features.

For example, to support cross-subdomain tracking by persisting the Singular Device ID (SDID) in a Cookie or to include a custom user ID for a returning site visitor with an active logged-in state:

var domain = 'website-name.com';
var config = new SingularConfig('sdkKey','sdkSecret','productId')
  .withAutoPersistentSingularDeviceId(domain)
  .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

Developer Checklist

Gather your SDK credentials and Product ID.
Decide if you need any custom settings (user ID, timeout, etc.).
Construct a Singular Intitialization function and SingularConfig object using the examples above.
Always test to make sure the initialization is only triggered once on the page load.

TIP! For advanced setups like Organic Search tracking, you may need to implement custom JavaScript—for example, to adjust query parameters—before the Singular SDK is initialized. Make sure your custom code executes before the Singular initialization function so changes will be captured correctly. More details on how to implement Organic Search Tracking can be found here.

Step 3: Tracking Events

After initializing the SDK, you can track custom events when users perform important actions on your website.

IMPORTANT! Singular does not block duplicate events! It is the developers responsibility to add protections against page refreshes or duplication. It is recommended to incorporate some deduplication method specificlly for revenue events to prevent erroneous revenue data. See "Step 5: Preventing Duplicate Events" below for an example..

Basic Event Tracking

Track a simple event or add custom attributes using valid JSON to provide more context about the event:

// Basic event tracking
var eventName = 'page_view';
window.singularSdk.event(eventName);

// Optional: With attributes for more context
var eventName = 'sng_content_view';
var attributes = {
  key1: 'value1', // First custom attribute
  key2: 'value2'  // Second custom attribute
};
window.singularSdk.event(eventName, attributes);

Conversion Event Tracking

Track a conversion event:

var eventName = 'sng_complete_registration';
window.singularSdk.conversionEvent(eventName);

Revenue Event Tracking

Track conversion events with revenue information and add optional attributes for more context:

Pass revenue currency as a three-letter ISO 4217 currency code, such as “USD”, “EUR”, or “INR".
Pass the revenue amount value as a decimal value.

// Revenue event tracking
var revenueEventName = 'sng_ecommerce_purchase';
var revenueCurrency = 'USD';
var revenueAmount = 49.99;
window.singularSdk.revenue(revenueEventName, revenueCurrency, revenueAmount);

// Optional: With attributes for more context
var revenueEventName = 'sng_ecommerce_purchase';
var revenueCurrency = 'USD';
var revenueAmount = 49.99;
var attributes = {
  key1: 'value1', // First custom attribute
  key2: 'value2'  // Second custom attribute
};
window.singularSdk.revenue(revenueEventName, revenueCurrency, revenueAmount, attributes);

Common Event Implementation Patterns

Page Load Events

The page load event tracking mechanism uses JavaScript to monitor when a webpage fully loads and then triggers an analytics event using the Singular SDK. Specifically, it leverages the window.addEventListener('load', ...) method to detect when all page resources (e.g., HTML, images, scripts) have loaded. Upon this event, the Singular SDK's event function is called to log a custom event with associated attributes, enabling tracking of user interactions for analytics purposes, such as monitoring page views or user actions like registrations. The mechanism is commonly used in web analytics to capture data about user behavior, such as page visits or specific actions, with customizable attributes for detailed insights.

The mechanism can be adapted to track a specific event (e.g., a page_view event) with custom attributes, as shown below. The code structure remains clean and modular, with the event name and attributes defined separately for clarity and maintainability.

/**
 * Tracks a registration event with the Singular SDK when the page fully loads.
 * @param {string} eventName - The name of the event to track (e.g., 'page_view').
 * @param {Object} attributes - A JSON object with custom event attributes.
 * @param {string} attributes.key1 - First custom attribute (e.g., 'value1').
 * @param {string} attributes.key2 - Second custom attribute (e.g., 'value2').
 */
window.addEventListener('load', function() {
  var eventName = 'page_view';
  var attributes = {
    key1: 'value1', // First custom attribute
    key2: 'value2'  // Second custom attribute
  };
  window.singularSdk.event(eventName, attributes);
});

Button Click Events

The button click event tracking mechanism uses JavaScript to monitor when a user clicks a button with the ID checkout-button and triggers a checkout_started event using the Singular SDK for analytics tracking. The code employs a click event listener to detect the button interaction, includes a mechanism to prevent multiple event triggers (using a data-event-fired attribute), and sends the event with custom attributes (cart_value and currency) to the Singular platform. This is ideal for e-commerce analytics to track when users initiate a checkout process, ensuring accurate data by firing the event only once per page session.

/**
 * Tracks a checkout started event with the Singular SDK when a button is clicked.
 * @param {string} eventName - The name of the event to track (e.g., 'checkout_started').
 * @param {Object} attributes - A JSON object with custom event attributes.
 * @param {number} attributes.cart_value - The total value of the cart (e.g., 99.99).
 * @param {string} attributes.currency - The currency of the cart value (e.g., 'USD').
 */
document.getElementById('checkout-button').addEventListener('click', function(e) {
  // Prevent multiple fires
  if (this.hasAttribute('data-event-fired')) {
    return;
  }
  this.setAttribute('data-event-fired', 'true');
  
  var eventName = 'checkout_started';
  var attributes = {
    cart_value: 99.99, // Total value of the cart
    currency: 'USD'    // Currency of the cart value
  };
  window.singularSdk.event(eventName, attributes);
});

Form Submission Events

The form submission event tracking mechanism uses JavaScript to monitor when a user submits a form with the ID signup-form and triggers a signup_completed event using the Singular SDK for analytics tracking. The code employs a submit event listener to detect form submission, includes a mechanism to prevent multiple event triggers (using a data-event-fired attribute), and sends the event with a custom attribute (signup_method) to the Singular platform. This is ideal for tracking user signups in analytics workflows, such as monitoring user acquisition or signup methods, ensuring accurate data by firing the event only once per page session.

Below is a clean example adapting the original code to use window.singularSdk.event, separating the event name and attributes for clarity.

/**
 * Tracks a signup completed event with the Singular SDK when a form is submitted.
 * @param {string} eventName - The name of the event to track (e.g., 'signup_completed').
 * @param {Object} attributes - A JSON object with custom event attributes.
 * @param {string} attributes.signup_method - The method used for signup (e.g., 'email').
 * @example
 * // Track a signup event with additional attributes
 * var eventName = 'signup_completed';
 * var attributes = {
 *   signup_method: 'email',
 *   email: document.getElementById('email')?.value || 'unknown'
 * };
 * window.singularSdk.event(eventName, attributes);
 */
document.getElementById('signup-form').addEventListener('submit', function(e) {
  // Prevent multiple fires
  if (this.hasAttribute('data-event-fired')) {
    return;
  }
  this.setAttribute('data-event-fired', 'true');
  
  var eventName = 'signup_completed';
  var attributes = {
    signup_method: 'email' // Method used for signup
  };
  window.singularSdk.event(eventName, attributes);
});

Step 4: Setting Customer User ID

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

NOTE: If you use Singular's Cross-Device solution, you must collect the User ID across all platforms.

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.

NOTE: If multiple Users use a single device, we recommend implementing a logout flow to set and unset the User ID for each login and logout.

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.

TIP! Use the same Customer User ID that you use in your mobile SDKs. This enables cross-device attribution and provides a complete view of user behavior across platforms.

Best practices for Customer User ID:

Set it as soon as the user logs in or signs up
Use the same ID across web and mobile platforms
Do not use personally identifiable information (email, phone number)
Use your internal user ID or database ID
Send as a string, even if it's numeric:

// After user logs in or signs up
var userId = 'user_12345';
window.singularSdk.login(userId);

// After user logs out
window.singularSdk.logout();

Step 5: Preventing Duplicate Events

IMPORTANT! This is one of the most common implementation errors. Without proper safeguards, events can fire multiple times, inflating your metrics.

Preventing duplicate revenue events in a web application is important for accurate analytics and avoiding overreporting conversions. The goal is to ensure each unique event only fires once per session or page visit, even if the user reloads the page or inadvertently triggers multiple submissions.

A unique key for each event (based on event details and optional custom attributes) is generated.
This key is stored in the browser’s sessionStorage (or localStorage for persistent deduplication).
Before sending, the code checks if a revenue event with the same payload has already been fired.
If not, it sends the event and saves the key.
If so, it blocks the repeat and notifies the user or developer.

Using Session Storage Method

// Sends a revenue event to Singular WebSDK, preventing duplicates in the same session
// @param {string} eventName - Name of the revenue event (defaults to "web_purchase")
// @param {number} amount - Revenue amount (defaults to 0)
// @param {string} currency - Currency code (defaults to "USD", normalized to uppercase)
// @param {object} [attributes] - Optional key-value pairs for additional event data
function sendRevenueEvent(eventName, amount, currency, attributes) {
  // Normalize inputs: set defaults and ensure currency is uppercase
  eventName = eventName ? eventName : "web_purchase";
  currency = currency ? currency.toUpperCase() : "USD";
  amount = amount ? amount : 0;

  // Create a payload object to standardize event data
  var payload = {
    eventName: eventName,
    amount: amount,
    currency: currency,
    attributes: attributes ? attributes : null // Null if no attributes provided
  };

  // Generate a unique key for sessionStorage by hashing the payload
  // This ensures deduplication of identical events in the same session
  var storageKey = 'singular_revenue_' + btoa(JSON.stringify(payload));

  // Check if the event was already sent in this session to prevent duplicates
  if (!sessionStorage.getItem(storageKey)) {
    // Mark event as sent in sessionStorage
    sessionStorage.setItem(storageKey, 'true');

    // Send revenue event to Singular SDK, including attributes if provided and valid
    if (attributes && typeof attributes === 'object' && Object.keys(attributes).length > 0) {
      window.singularSdk.revenue(eventName, currency, amount, attributes);
    } else {
      // Fallback to basic revenue event without attributes
      window.singularSdk.revenue(eventName, currency, amount);
    }
    // Log event details for debugging
    console.log("Revenue event sent:", payload);
  } else {
    // Log and alert if a duplicate event is detected
    console.log("Duplicate revenue event prevented:", payload);
    alert("Duplicate revenue event prevented!");
  }
}

Step 6: Testing Your Implementation

After implementing the SDK, verify that it's working correctly using your browser's developer tools.

Verify SDK Loaded

Open your website in a browser
Open Developer Tools (F12 or Right-click → Inspect)
Go to the Console tab
Type typeof singularSdk and press Enter
You should see a "function" object, not "undefined"

Verify Network Requests

Open Developer Tools (F12)
Go to the Network tab
Reload your page
Filter by singular or sdk-api
Look for requests to sdk-api-v1.singular.net
Click on a request to view details
Verify the Status Code is 200
Check the request payload contains your Product ID. This will be in the "i" parameter of the payload.

SUCCESS! If you see requests to sdk-api-v1.singular.net with status code 200, your SDK is successfully sending data to Singular.

Verify Events

Trigger an event on your website (click a button, submit a form, etc.)
In the Network tab, look for a new request to sdk-api-v1.singular.net
Click on the request and view the Payload or Request tab
Verify your event name "n" parameter appears in the request

For End-to-End testing, use the Testing Console

You can test the Web SDK integration using SDK Console available in the Singular dashboard.

In the Singular platform, go to Developer Tools > Testing Console.
Click Add Device.
Select the platform "Web" and enter the Singular Device ID.
Get the Singular Device ID from the browser payload. Check the above screenshot to locate the SDID on an event.
The testing console must remain in active state while you test in a separate window. The console will not display any events that are triggered while it is closed or offline.
Once the SDID is added, you can reload the webpage and trigger some events. The "__PAGE_VISIT__" and other events (if triggered) will be shown in SDK Console.
Utilizing the Export logs (Reports & Insights Export Logs) is another way to verify the testing results. This data set is delayed by 1 hour.

Step 7: Implement Web-to-App Forwarding

Web-to-App Attribution Forwarding

Use the Singular WebSDK to track user journeys from your website to your mobile app, enabling accurate web campaign attribution to mobile app installs and reengagements. Follow these steps to set up web-to-app forwarding, including QR code support for desktop users.

Follow our Website-to-Mobile App Attribution Forwarding Guide to configure the Singular WebSDK for mobile web attribution.
For Desktop Web-to-App tracking:
- Complete the setup in the guide above.
- Use the Singular Mobile Web-to-App Link (e.g., https://yourlink.sng.link/...) and the WebSDK function buildWebToAppLink(link) with a dynamic QR code library like QRCode.js.
- Generate a QR code on your webpage that encodes the link. Desktop users can scan it with their mobile device to open the app, passing campaign data for attribution.
- Explore our Singular WebSDK Demo for a working example of QR code generation and web-to-app link handling.

TIP! Mobile in-app browser web views (like those used by Facebook, Instagram, and TikTok) can cause the Singular Device ID to change if a user moves to the device’s native browser, disrupting attribution.

To prevent this, always use the proper Singular tracking link format for each ad network:

Singular WebSDK Demo

Below is a simple but comprehensive implementation using the documented Singular WebSDK API. This sample provides clear separation for custom events, conversion events, revenue events, and web-to-app link support using WebSDK supported Web-to-App forwarding.

You can run this code in a local HTML file or modify it in your site for advanced integration and troubleshooting.

Singular WebSDK Demo (Source Code)

Copy and paste the code below as an HTML file and open it in your browser.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>Singular WebSDK Demo</title>
  <script src="https://cdn.jsdelivr.net/npm/qrcodejs/qrcode.min.js"></script>
  <script src="https://web-sdk-cdn.singular.net/singular-sdk/latest/singular-sdk.js"></script>

  <style>
    * {
      margin: 0;
      padding: 0;
      box-sizing: border-box;
    }

    body {
      font-family: -apple-system, BlinkMacSystemFont, 'Inter', 'Segoe UI', Roboto, sans-serif;
      line-height: 1.6;
      color: #1a1d29;
      background: linear-gradient(135deg, #f8fafc 0%, #e2e8f0 100%);
      padding: 40px 20px;
      min-height: 100vh;
    }

    .container {
      max-width: 800px;
      margin: 0 auto;
      background: white;
      padding: 48px;
      border-radius: 16px;
      box-shadow: 0 4px 24px rgba(30, 41, 59, 0.08);
      border: 1px solid rgba(148, 163, 184, 0.1);
    }

    .header-brand {
      display: flex;
      align-items: center;
      margin-bottom: 32px;
      padding-bottom: 24px;
      border-bottom: 2px solid #f1f5f9;
    }

    .brand-dot {
      width: 12px;
      height: 12px;
      background: linear-gradient(135deg, #6366f1 0%, #8b5cf6 100%);
      border-radius: 50%;
      margin-right: 12px;
    }

    h1 {
      font-size: 32px;
      font-weight: 700;
      color: #0f172a;
      letter-spacing: -0.025em;
    }

    h2 {
      font-size: 24px;
      font-weight: 600;
      margin: 48px 0 24px 0;
      color: #1e293b;
      padding-bottom: 12px;
      border-bottom: 2px solid #e2e8f0;
      position: relative;
    }

    h2:before {
      content: '';
      position: absolute;
      bottom: -2px;
      left: 0;
      width: 60px;
      height: 2px;
      background: linear-gradient(90deg, #6366f1, #8b5cf6);
    }

    p {
      margin-bottom: 18px;
      color: #475569;
      font-size: 15px;
    }

    strong {
      color: #1e293b;
      font-weight: 600;
    }

    .form-group {
      margin-bottom: 24px;
    }

    .radio-group {
      display: flex;
      gap: 24px;
      margin-bottom: 24px;
      padding: 16px;
      background: #f8fafc;
      border-radius: 12px;
      border: 1px solid #e2e8f0;
    }

    .radio-group label {
      display: flex;
      align-items: center;
      gap: 10px;
      cursor: pointer;
      font-size: 14px;
      font-weight: 500;
      color: #475569;
      transition: color 0.2s ease;
    }

    .radio-group label:hover {
      color: #1e293b;
    }

    input[type="radio"] {
      width: 20px;
      height: 20px;
      cursor: pointer;
      accent-color: #6366f1;
    }

    input[type="text"] {
      width: 100%;
      padding: 14px 18px;
      font-size: 15px;
      font-weight: 400;
      border: 2px solid #e2e8f0;
      border-radius: 12px;
      transition: all 0.2s ease;
      background: #fafbfc;
      color: #1e293b;
    }

    input[type="text"]:focus {
      outline: none;
      border-color: #6366f1;
      background: white;
      box-shadow: 0 0 0 4px rgba(99, 102, 241, 0.1);
    }

    input[type="text"]::placeholder {
      color: #94a3b8;
      font-weight: 400;
    }

    button {
      padding: 14px 32px;
      font-size: 15px;
      font-weight: 700;
      color: #fff;
      background: linear-gradient(90deg, #2363f6 0%, #1672fe 100%);
      border: none;
      border-radius: 4px;  /* Pill shape */
      cursor: pointer;
      box-shadow: 0 2px 8px rgba(35, 99, 246, 0.12);
      transition: background 0.2s, transform 0.2s;
      letter-spacing: 0.03em;
    }
    button:hover {
      background: linear-gradient(90deg, #1672fe 0%, #2363f6 100%);
      transform: translateY(-2px);
      box-shadow: 0 8px 24px rgba(22, 114, 254, 0.18);
    }
    button:active {
      transform: translateY(0);
    }

    a {
      color: #6366f1;
      text-decoration: none;
      font-weight: 600;
      transition: all 0.2s ease;
      position: relative;
    }

    a:hover {
      color: #4f46e5;
    }

    a:after {
      content: '';
      position: absolute;
      width: 0;
      height: 2px;
      bottom: -2px;
      left: 0;
      background: #6366f1;
      transition: width 0.2s ease;
    }

    a:hover:after {
      width: 100%;
    }

    ol {
      margin-left: 10px;
      margin-bottom: 18px;
    }

    ol li {
      margin-left: 10px;
    }

    .info-box {
      background: linear-gradient(135deg, #eff6ff 0%, #f0f9ff 100%);
      border-left: 4px solid #6366f1;
      padding: 20px;
      margin: 24px 0;
      border-radius: 12px;
      border: 1px solid rgba(99, 102, 241, 0.1);
    }

    .info-box p {
      color: #1e40af;
      margin-bottom: 0;
    }

    .section-label {
      font-size: 12px;
      font-weight: 700;
      color: #6b7280;
      margin-bottom: 10px;
      text-transform: uppercase;
      letter-spacing: 1px;
    }

    .button-group {
      display: flex;
      align-items: center;
      gap: 16px;
      flex-wrap: wrap;
    }

    .analytics-badge {
      display: inline-flex;
      align-items: center;
      gap: 8px;
      background: linear-gradient(135deg, #6366f1 0%, #8b5cf6 100%);
      color: white;
      padding: 6px 12px;
      border-radius: 20px;
      font-size: 12px;
      font-weight: 600;
      margin-bottom: 16px;
    }

    .feature-grid {
      display: grid;
      grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
      gap: 16px;
      margin: 24px 0;
    }

    .feature-item {
      padding: 16px;
      background: #f8fafc;
      border-radius: 10px;
      border: 1px solid #e2e8f0;
      text-align: center;
    }

    .feature-item strong {
      display: block;
      color: #6366f1;
      font-size: 14px;
      margin-bottom: 4px;
    }

    .metric-dot {
      width: 8px;
      height: 8px;
      background: #10b981;
      border-radius: 50%;
      display: inline-block;
      margin-right: 8px;
      animation: pulse 2s infinite;
    }

    @keyframes pulse {
      0%, 100% { opacity: 1; }
      50% { opacity: 0.5; }
    }
  </style>

</head>

<body>
  <div class="container">
    <div class="header-brand">
      <div class="brand-dot"></div>
      <h1>Singular WebSDK Demo</h1>
    </div>

    <p>
      Below is a simple but comprehensive implementation using the documented Singular WebSDK API. 
      This sample provides clear separation for <strong>custom events</strong>, <strong>conversion events</strong>, <strong>revenue events</strong>, and <strong>web-to-app link support using WebSDK supported Web-to-App forwarding</strong>. </p>
      <p>You can run this code in a local HTML file or modify it in your site for advanced integration and troubleshooting.
    </p>

    <h2>SDK Initialization Testing</h2>
    <ol>
      <li>Open your browsers developer tools.</li>
      <li>Inspect the Network tab and filter for "sdk-api-v1.singular.net"</li>
      <li>Refresh this page, and examin the payload of the request.</li>
    </ol>


    <hr>

    <h2>User Authentication</h2>
    <p>User authentication is key to supporting cross-device attribution. Pass the common User ID value that would also be sent to Singular from mobile SDKs for cross-device continuity.</p>
    <div class="form-group">
      <div class="section-label">Simulate User Authentication</div>
      <input type="text" id="userId" placeholder="Enter a User ID"/>
    </div>
    <div class="form-group">
      <div class="button-group">
        <button onclick="setUserId()">Set the User ID (Login)</button>
        <button onclick="unsetUserId()">Unset the User ID (Logout)</button>
      </div>
    </div>

    <hr>

    <h2>SDK Event Testing</h2>
    <div class="form-group">
      <div class="section-label">Event Type Selection</div>
      <div class="radio-group">
        <label>
          <input type="radio" name="eventType" value="custom" checked onchange="handleRevenueFields(this)">
          <span>Custom Event</span>
        </label>
        <label>
          <input type="radio" name="eventType" value="conversion" onchange="handleRevenueFields(this)">
          <span>Conversion Event</span>
        </label>
        <label>
          <input type="radio" name="eventType" value="revenue" onchange="handleRevenueFields(this)">
          <span>Revenue Event</span>
        </label>
      </div>
    </div>

    <div class="form-group">
      <div class="section-label">Event Configuration</div>
      <input type="text" id="eventName" placeholder="Enter event name"/>
    </div>

    <div class="form-group" id="currencyGroup" style="display:none">
      <input type="text" id="currency" placeholder="Currency code (e.g., USD, EUR)"/>
    </div>

    <div class="form-group" id="amountGroup" style="display:none">
      <input type="text" id="amount" placeholder="Revenue amount (e.g., 29.99)"/>
    </div>

    <div class="form-group" id="attributesGroup" style="display:none">
      <input type="text" id="attributes" placeholder='Optional attributes (JSON, e.g. {"color":"blue"})'/>
    </div>

    <div class="form-group">
      <button id="send" onclick="sendCustomEvent()">Send Event to Singular</button>
    </div>

    <hr>
    <h2>Web-to-App Forwarding</h2>
    <div class="form-group">
    <ol>
      <li><a href="https://support.singular.net/hc/en-us/articles/360042283811" target="_blank">Learn more about Web-to-App Forwarding</a></li>
    <li>In the page source code you will find the mobile web-to-app base link "<strong>https://seteam.sng.link/D0mvs/y3br?_smtype=3</strong>" used for demonstration purposes.</li>
    <li>Replace all occurances of the link with your own Singular Mobile Web-to-App link to test functionality.</li>
    <li>Add Singular Web Parameters to the URL and refresh the page. (example: "<strong>?wpsrc=SingularTest&wpcn=MyCampaign</strong>").</li>
  </ol>

    <hr>
    <div class="section-label">Mobile Web-to-App Test</div>
    <div class="form-group">
      <div class="button-group">
        <button onclick="displayWebLink()">Display Constructed Web-to-App Link</button>
        <button onclick="testWebLink()">Test Web-to-App Link</button>
      </div>
    </div>
  </div>
    <hr>
    <div class="section-label">Desktop Web-to-App Configuration</div>
    <div class="form-group">
    <p>Use a dynamic QR Code generation library like <a href="https://davidshimjs.github.io/qrcodejs/" target="_blank">QRCode.js</a> to build and display a QR code using the Singular Mobile Web-to-App link with constructed campaign parameters.</p>
    <div id="qrcode"></div>
    </div>

  </div>
  
  <script>
    /**
     * Initializes the Singular SDK with the provided configuration.
     * @param {string} sdkKey - The SDK key for Singular (e.g., 'se_team_9b3431b0').
     * @param {string} sdkSecret - The SDK secret for Singular (e.g., 'bcdee06e8490949422c071437da5c5ed').
     * @param {string} productId - The product ID for Singular (e.g., 'com.website').
     * @example
     * // Initialize the Singular SDK
     * initSingularSDK('se_team_9b3431b0', 'bcdee06e8490949422c071437da5c5ed', 'com.website');
     */
    function initSingularSDK() {
      var sdkKey = 'se_team_9b3431b0';
      var sdkSecret = 'bcdee06e8490949422c071437da5c5ed';
      var productId = 'com.website';
      
      var config = new SingularConfig(sdkKey, sdkSecret, productId)
        .withInitFinishedCallback(function(initParams) {
          var singularDeviceId = initParams.singularDeviceId;
          console.log('Singular Device ID:', singularDeviceId);
          // Optionally store for use in events
          // sessionStorage.setItem('singularDeviceId', singularDeviceId);
        });

      window.singularSdk.init(config);
      generateDesktopWebToAppQRCode(); // Generate QR code after initialization
    }

    /**
     * Triggers Singular SDK initialization when the DOM is fully parsed.
     * @example
     * document.addEventListener('DOMContentLoaded', function() {
     *   initSingularSDK();
     * });
     */
    document.addEventListener('DOMContentLoaded', function() {
      initSingularSDK();
    });


    // Fires a custom event using the Singular SDK
    function sendCustomEvent() {
      var eventName = document.getElementById('eventName').value;
      window.singularSdk.event(eventName);
    }

    // Fires a conversion event using the Singular SDK
    function sendConversionEvent() {
      var eventName = document.getElementById('eventName').value;
      window.singularSdk.conversionEvent(eventName);
    }

    // Fires a revenue event only once per session with deduplication
    // Parameters:
    //   - eventName: string (name of event), default "web_purchase" if blank
    //   - amount: revenue amount, default 0 if blank
    //   - currency: string, defaults to "USD" if blank
    //   - attributes: optional object with extra payload
    function sendRevenueEvent(eventName, amount, currency, attributes) {
      // Fill in defaults and normalize values
      eventName = eventName ? eventName : "web_purchase";
      currency = currency ? currency.toUpperCase() : "USD";
      amount = amount ? amount : 0;

      // Create a unique key based on event data for deduplication
      // btoa(JSON.stringify(...)) ensures order consistency in local/sessionStorage
      var payload = {
        eventName: eventName,
        amount: amount,
        currency: currency,
        attributes: attributes ? attributes : null
      };
      var storageKey = 'singular_revenue_' + btoa(JSON.stringify(payload));

      // Only fire event if no identical event has already fired in this tab/session
      if (!sessionStorage.getItem(storageKey)) {
        sessionStorage.setItem(storageKey, 'true');
        if (attributes && typeof attributes === 'object' && Object.keys(attributes).length > 0) {
          // Fire event with attributes payload
          window.singularSdk.revenue(eventName, currency, amount, attributes);
        } else {
          // Fire simple revenue event
          window.singularSdk.revenue(eventName, currency, amount);
        }
        console.log("Revenue event sent:", payload);
      } else {
        // Duplicate detected, don't send to SDK
        console.log("Duplicate revenue event prevented:", payload);
        alert("Duplicate revenue event prevented!");
      }
    }

    // Collects form values, validates attributes JSON, and calls sendRevenueEvent()
    // Ensures only valid values are sent and blocks on malformed JSON
    function fireFormRevenueEvent() {
      var eventName = document.getElementById('eventName').value;
      var currency = document.getElementById('currency').value;
      var amount = document.getElementById('amount').value;
      
      var attributesRaw = document.getElementById('attributes').value;
      var attributes = null;
      if (attributesRaw) {
        try {
          // Try to parse the optional attributes field from JSON string
          attributes = JSON.parse(attributesRaw);
        } catch (e) {
          alert("Optional attributes must be valid JSON.");
          return; // Stop if invalid JSON
        }
      }

      // Calls main revenue logic for deduplication and event sending
      sendRevenueEvent(eventName, amount, currency, attributes);
    }

    // Controls which form fields are visible depending on selected event type
    // Revenue events require currency, amount, and attributes fields
    function handleRevenueFields(sender) {
      var isRevenue = sender.value === "revenue";
      document.getElementById("currencyGroup").style.display = isRevenue ? "block" : "none";
      document.getElementById("amountGroup").style.display = isRevenue ? "block" : "none";
      document.getElementById("attributesGroup").style.display = isRevenue ? "block" : "none";

      // Dynamically assign the event button's onclick handler
      var send = document.getElementById("send");
      send.onclick = (sender.value === "custom") ? sendCustomEvent
        : (sender.value === "conversion") ? sendConversionEvent
        : fireFormRevenueEvent; // Only fires revenue logic for "revenue"
    }

    // Opens demo Singular web-to-app link in a new tab/window
    function testWebLink() {
      var singularWebToAppBaseLink = 'https://seteam.sng.link/D0mvs/y3br?_smtype=3';
      window.open(singularWebToAppBaseLink);
    }

    // Displays constructed Singular web-to-app link with campaign parameters
    function displayWebLink() {
      var singularWebToAppBaseLink = 'https://seteam.sng.link/D0mvs/y3br?_smtype=3';
      var builtLink = window.singularSdk.buildWebToAppLink(singularWebToAppBaseLink);
      console.log("Singular Web-to-App Link: ", builtLink);
      alert("Singular Web-to-App Link: " + builtLink);
    }

    // Generates QR code for desktop deep linking using Singular Mobile Web-to-App link
    function generateDesktopWebToAppQRCode() {
      var singularWebToAppBaseLink = 'https://seteam.sng.link/D0mvs/y3br?_smtype=3';
      const value = window.singularSdk.buildWebToAppLink(singularWebToAppBaseLink);
      new QRCode(document.getElementById("qrcode"), {
        text: value,
        width: 128,
        height: 128,
        colorDark: "#000",
        colorLight: "#fff",
        correctLevel: QRCode.CorrectLevel.H
      });
    }

    // Simulate user authentication and send login event
    function setUserId() {
      var userId = document.getElementById('userId').value;
      window.singularSdk.login(userId);
      console.log("Singular User ID is Set to: " + userId);
      window.singularSdk.event("sng_login");
    }

    // Simulate user logout and unset Singular user ID
    function unsetUserId() {
      window.singularSdk.logout();
      console.log("Singular User ID is Unset");
    }
  </script>
</body>
</html>

Advanced Topics

Singular Banners

Enable Singular Banners

INFO: Singular Banners is an enterprise feature. To learn more about this feature, reach out to your Customer Success Manager.

Singular Banners can be displayed in your mobile website to lead web users seamlessly to your app and display the most relevant app content. Once you enable Singular Banners in your website, your organization can easily design, deploy, and maintain banners through the Singular Banners UI.

Step-by-Step Implementation Guide

Add the Singular Native JavaScript WebSDK Script to your website.

Follow the Integration guide above to add the Singular Native JavaScript WebSDK to your website before proceeding with the Banners implementation.
Give Singular Permission to Access Client Hints Data

With the limitations on user agent data in Chromium-based web browsers, rolled out in February-March 2023, advertisers now need to fetch client hints data as well as give the Singular WebSDK permission to receive this data. For more information, see the Banners FAQ.

The website needs to:
- Start asking for Client Hints (accept-ch header).
- Grant Singular permission (as a third party) so that the browser will send Singular the client hints on the fetch banner requests (permissions-policy header).
Add the following response headers to the page load response:
```
accept-ch:
sec-ch-ua-model,
sec-ch-ua-platform-version,
sec-ch-ua-full-version-list

permissions-policy:
ch-ua-model=("https://sdk-api-v1.singular.net"),
ch-ua-platform-version=("https://sdk-api-v1.singular.net"),
ch-ua-full-version-list=("https://sdk-api-v1.singular.net")
```

Add the Banner config option to the WebSDK Initialization

Singular Banners display smart app download prompts on your mobile website while preserving attribution from the original marketing source. When enabled with web-to-app support, the SDK tracks which ad network or campaign brought the user to your site, then attributes the subsequent app install back to that original source.

/**
 * Initialize Singular SDK with Banner support and web-to-app attribution.
 * This enables smart banners that direct mobile web users to download your app
 * while preserving the original marketing source (UTM parameters, ad network, etc.)
 * for proper attribution when the app is installed.
 * @param {string} sdkKey - Your Singular SDK Key
 * @param {string} sdkSecret - Your Singular SDK Secret
 * @param {string} productId - Your Product ID (e.g., com.your-website)
 */
function initSingularSDK() {
  // Enable web-to-app tracking to preserve attribution data
  var bannersOptions = new BannersOptions().withWebToAppSupport();
  
  // Configure SDK with banner support
  var config = new SingularConfig(sdkKey, sdkSecret, productId)
    .withBannersSupport(bannersOptions);
  
  // Initialize the SDK
  window.singularSdk.init(config);
  
  // Display the smart banner
  window.singularSdk.showBanner();
}

// Call on DOM ready
document.addEventListener('DOMContentLoaded', function() {
  initSingularSDK();
});

Reshow Banner on Page Route (Single-Page Applications Only)

If your application is Single-Page Application, you have to hide and re-show the banner on each page route. This ensures that Singular delivers the appropriate banner for your web experience.

To hide and re-show the banner, use the following code:
```
window.singularSdk.hideBanner();
window.singularSdk.showBanner();
```

[Advanced Option] Customize Link Settings

Singular provides a way to personalize the links in the banner through code.

To personalize links:

Create a LinkParams object and use one or more of the functions below. Do this before calling window.singularSdk.showBanner().
Then pass the LinkParams object when you call window.singularSdk.showBanner().

Example:

// Define a LinkParams object
let bannerParams = new LinkParams();

// Configure link options (see details on each option below)
bannerParams.withAndroidRedirect("androidRedirectValue");
bannerParams.withAndroidDL("androidDLParamValue");
bannerParams.withAndroidDDL("androidDDLparamValue");
bannerParams.withIosRedirect("iosRedirectValue");
bannerParams.withIosDL("iosDLValue");
bannerParams.withIosDDL("iosDDLValue");

// Show the banner with the defined options
window.singularSdk.showBanner(bannerParams);

List of options:

Method	Description
`withAndroidRedirect`	Pass a redirect link to your Android app download page, usually a Play Store page.
`withAndroidDL`	Pass a deep link for a page within your Android app.
`withAndroidDDL`	Pass a deferred deep link, i.e., a link to a page in your Android app that the user hasn't installed yet.
`withIosRedirect`	Pass a redirect link to your iOS app download page, usually an App Store page.
`withIosDL`	Pass a deep link to a page within your iOS app.
`withIosDDL`	Pass a deferred deep link, i.e., a link to a page in your iOS app that the user hasn't installed yet.

[Advanced Option] Use Code to Force Hiding/Showing of Banners

As mentioned in step 3, if you have a single-page application, you have to use the hideBanner() and showBanner() methods on each page route to ensure the appropriate banner is delivered (see above).

hideBanner() and showBanner() are also available to you to use throughout your code if you want to hide a banner that would otherwise be displayed, or re-show a banner that you hid.

Method	Description
`singularSdk.hideBanner()`	Hide a visible banner from your page.
`singularSdk.showBanner()`	Show the pre-configured banner.
`singularSdk.showBanner(params)`	Show the pre-configured banner but override links with the options defined in the linkParams object (see step 4).

Global Properties

The Singular SDK lets you define custom properties to be sent to the Singular servers along with every session and event sent from the app. These properties can represent any information you want about the user, the app mode/status, or anything else.

You can define up to 5 global properties as a valid JSON object. The global properties are persisted in the browsers localstorage until it is cleared or the browser context is changed.
Each property name and value can be up to 200 characters long. If you pass a longer property name or value, it will be truncated to 200 characters.
Global properties are currently reflected in Singular's user-level event logs (see Exporting Attribution Logs) and in postbacks.
Global properties are available to me sent in postbacks from Singular to a third party for matching purposes is needed.

To support setting Global Properties before the WebSDK is initialized you must implement the custom setGlobalPropertyBeforeInit function, and call this prior to SDK Initialization. If you do not require the setting of Global Properites prior to Initialization you may omit this custom code.

To handle Global Properites after initialization, you must use the SDK functions: setGlobalProperties(), getGlobalProperties(), clearGlobalProperties().

/**
 * Set a Singular global property before SDK initialization.
 * Allows up to 5 key/value pairs. Optionally overwrites existing value for a key.
 * 
 * @param {string} sdkKey - The Singular SDK key.
 * @param {string} productId - The Singular product ID.
 * @param {string} propertyKey - The property key to set.
 * @param {string} propertyValue - The property value to set.
 * @param {boolean} overrideExisting - Whether to overwrite the property if it already exists.
 */
function setGlobalPropertyBeforeInit(sdkKey, productId, propertyKey, propertyValue, overrideExisting) {
  const storageKey = `${sdkKey}_${productId}_global_properties`;
  let properties = {};

  // Try to load any existing properties
  const existing = localStorage.getItem(storageKey);
  if (existing) {
    try {
      properties = JSON.parse(existing) || {};
    } catch (e) {
      // If parsing fails, reset properties
      properties = {};
    }
  }

  // Only allow up to 5 keys
  const propertyExists = Object.prototype.hasOwnProperty.call(properties, propertyKey);
  const numKeys = Object.keys(properties).length;
  if (!propertyExists && numKeys >= 5) {
    console.warn("You can only set up to 5 Singular global properties.");
    return;
  }

  // Apply logic for overwrite or skip
  if (propertyExists && !overrideExisting) {
    console.log(`Global property '${propertyKey}' exists and overrideExisting is false; property not changed.`);
    return;
  }

  properties[propertyKey] = propertyValue;
  localStorage.setItem(storageKey, JSON.stringify(properties));
  console.log("Singular Global Properties set:", storageKey, properties);
}

/**
 * Set a Singular global property before SDK initialization.
 * Allows up to 5 key/value pairs. Optionally overwrites existing value for a key.
 * 
 * @param {string} propertyKey - The property key to set.
 * @param {string} propertyValue - The property value to set.
 * @param {boolean} overrideExisting - Whether to overwrite the property if it already exists.
 */

// Usage
window.singularSdk.setGlobalProperties(propertyKey, propertyValue, overrideExisting);

// Get the JSON Object of global property values.

// Usage
window.singularSdk.getGlobalProperties();

// Clears all global property values.

// Usage
window.singularSdk.clearGlobalProperties();

Organic Search Tracking

Organic Search Tracking Example

IMPORTANT! This example is provided as a workaround soluton to enable Organic Search tracking. The code should be used as an example only and updated and maintained by the web developer based on the needs of your marketing department. Organic Search tracking may have different meanings per advertiser. Please review the sample and adjust for your needs.

Why Use This?

Ensures organic search visits are properly tracked, even if no campaign parameters are present.
Appends the Singular "Source" parameter wpsrc with the value from the (referrer) and the "Campaign Name" parameter wpcn as "OrganicSearch" to the URL for clear attribution.
Stores the current URL and referrer in localStorage for later use.
Pure JavaScript, zero dependencies, and easy to integrate.

How It Works

Checks the page URL for known campaign parameters from (Google, Facebook, TikTok, UTMs, etc.).
If no campaign parameters are present and the referrer is a search engine, appends:
- wpsrc (with the referrer as its value)
- wpcn (with OrganicSearch as its value)
Updates the URL in the browser without reloading the page.
Stores the current URL and referrer in localStorage as sng_url and sng_ref.

Usage

Add setupOrganicSearchTracking.js to your site as a library.
Call the setupOrganicSearchTracking() function BEFORE initializing the WebSDK.

// singular-web-organic-search-tracking: setupOrganicSearchTracking.js
// Tracks organic search referrals by appending wpsrc and wpcn to the URL if no campaign parameters exist and the referrer is a search engine.

// Configuration for debugging (set to true to enable logs)
const debug = true;

// List of campaign parameters to check for exclusion
const campaignParams = [
    'gclid', 'fbclid', 'ttclid', 'msclkid', 'twclid', 'li_fat_id',
    'utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'wpsrc'
];

// Whitelist of legitimate search engine domains (prevents false positives)
const legitimateSearchEngines = new Set([
    // Google domains
    'google.com', 'google.co.uk', 'google.ca', 'google.com.au', 'google.de', 
    'google.fr', 'google.it', 'google.es', 'google.co.jp', 'google.co.kr',
    'google.com.br', 'google.com.mx', 'google.co.in', 'google.ru', 'google.com.sg',
    
    // Bing domains  
    'bing.com', 'bing.co.uk', 'bing.ca', 'bing.com.au', 'bing.de',
    
    // Yahoo domains
    'yahoo.com', 'yahoo.co.uk', 'yahoo.ca', 'yahoo.com.au', 'yahoo.de',
    'yahoo.fr', 'yahoo.it', 'yahoo.es', 'yahoo.co.jp',
    
    // Other search engines
    'baidu.com', 'duckduckgo.com', 'yandex.com', 'yandex.ru',
    'ask.com', 'aol.com', 'ecosia.org', 'startpage.com', 
    'qwant.com', 'seznam.cz', 'naver.com', 'daum.net'
]);

// Extract main domain from hostname (removes subdomains)
function getMainDomain(hostname) {
    if (!hostname) return '';
    
    const lowerHost = hostname.toLowerCase();
    
    // Handle special cases for known search engines with country codes
    const searchEnginePatterns = {
        'google': (host) => {
            // Match google.TLD patterns more precisely
            if (host.includes('google.co.') || host.includes('google.com')) {
                const parts = host.split('.');
                const googleIndex = parts.findIndex(part => part === 'google');
                if (googleIndex !== -1 && googleIndex < parts.length - 1) {
                    return parts.slice(googleIndex).join('.');
                }
            }
            return null;
        },
        'bing': (host) => {
            if (host.includes('bing.co') || host.includes('bing.com')) {
                const parts = host.split('.');
                const bingIndex = parts.findIndex(part => part === 'bing');
                if (bingIndex !== -1 && bingIndex < parts.length - 1) {
                    return parts.slice(bingIndex).join('.');
                }
            }
            return null;
        },
        'yahoo': (host) => {
            if (host.includes('yahoo.co') || host.includes('yahoo.com')) {
                const parts = host.split('.');
                const yahooIndex = parts.findIndex(part => part === 'yahoo');
                if (yahooIndex !== -1 && yahooIndex < parts.length - 1) {
                    return parts.slice(yahooIndex).join('.');
                }
            }
            return null;
        }
    };
    
    // Try specific patterns for major search engines
    for (const [engine, patternFn] of Object.entries(searchEnginePatterns)) {
        if (lowerHost.includes(engine)) {
            const result = patternFn(lowerHost);
            if (result) return result;
        }
    }
    
    // Handle other known engines with simple mapping
    const otherEngines = {
        'baidu.com': 'baidu.com',
        'duckduckgo.com': 'duckduckgo.com', 
        'yandex.ru': 'yandex.ru',
        'yandex.com': 'yandex.com',
        'ask.com': 'ask.com',
        'aol.com': 'aol.com',
        'ecosia.org': 'ecosia.org',
        'startpage.com': 'startpage.com',
        'qwant.com': 'qwant.com',
        'seznam.cz': 'seznam.cz',
        'naver.com': 'naver.com',
        'daum.net': 'daum.net'
    };
    
    for (const [domain, result] of Object.entries(otherEngines)) {
        if (lowerHost.includes(domain)) {
            return result;
        }
    }
    
    // Fallback: Extract main domain by taking last 2 parts (for unknown domains)
    const parts = hostname.split('.');
    if (parts.length >= 2) {
        return parts[parts.length - 2] + '.' + parts[parts.length - 1];
    }
    
    return hostname;
}

// Get query parameter by name, using URL.searchParams with regex fallback for IE11
function getParameterByName(name, url) {
    if (!url) url = window.location.href;
    try {
        return new URL(url).searchParams.get(name) || null;
    } catch (e) {
        if (debug) console.warn('URL API not supported, falling back to regex:', e);
        name = name.replace(/[\[\]]/g, '\\$&');
        const regex = new RegExp('[?&]' + name + '(=([^&#]*)|&|#|$)');
        const results = regex.exec(url);
        if (!results) return null;
        if (!results[2]) return '';
        return decodeURIComponent(results[2].replace(/\+/g, ' '));
    }
}

// Check if any campaign parameters exist in the URL
function hasAnyParameter(url, params) {
    return params.some(param => getParameterByName(param, url) !== null);
}

// Improved search engine detection - only checks hostname, uses whitelist
function isSearchEngineReferrer(referrer) {
    if (!referrer) return false;
    
    let hostname = '';
    try {
        hostname = new URL(referrer).hostname.toLowerCase();
    } catch (e) {
        // Fallback regex for hostname extraction
        const match = referrer.match(/^(?:https?:\/\/)?([^\/\?#]+)/i);
        hostname = match ? match[1].toLowerCase() : '';
    }
    
    if (!hostname) return false;
    
    // First check: exact match against whitelist
    if (legitimateSearchEngines.has(hostname)) {
        if (debug) console.log('Exact match found for:', hostname);
        return true;
    }
    
    // Second check: subdomain of legitimate search engine
    const hostParts = hostname.split('.');
    if (hostParts.length >= 3) {
        // Try domain.tld combination (e.g., google.com from www.google.com)
        const mainDomain = hostParts[hostParts.length - 2] + '.' + hostParts[hostParts.length - 1];
        if (legitimateSearchEngines.has(mainDomain)) {
            if (debug) console.log('Subdomain match found for:', hostname, '-> main domain:', mainDomain);
            return true;
        }
        
        // Try last 3 parts for country codes (e.g., google.co.uk from www.google.co.uk)
        if (hostParts.length >= 3) {
            const ccDomain = hostParts[hostParts.length - 3] + '.' + hostParts[hostParts.length - 2] + '.' + hostParts[hostParts.length - 1];
            if (legitimateSearchEngines.has(ccDomain)) {
                if (debug) console.log('Country code domain match found for:', hostname, '-> cc domain:', ccDomain);
                return true;
            }
        }
    }
    
    if (debug) {
        console.log('Hostname not recognized as legitimate search engine:', hostname);
    }
    
    return false;
}

// Main function to update URL with organic search tracking parameters
function setupOrganicSearchTracking() {
    const url = window.location.href;
    const referrer = document.referrer || '';

    // Store URL and referrer in localStorage
    try {
        localStorage.setItem('sng_url', url);
        localStorage.setItem('sng_ref', referrer);
    } catch (e) {
        if (debug) console.warn('localStorage not available:', e);
    }

    if (debug) {
        console.log('Current URL:', url);
        console.log('Referrer:', referrer);
    }

    // Skip if campaign parameters exist or referrer is not a search engine
    const hasCampaignParams = hasAnyParameter(url, campaignParams);
    if (hasCampaignParams || !isSearchEngineReferrer(referrer)) {
        if (debug) console.log('Skipping URL update: Campaign params exist or referrer is not a legitimate search engine');
        return;
    }

    // Extract and validate referrer hostname
    let referrerHostname = '';
    try {
        referrerHostname = new URL(referrer).hostname;
    } catch (e) {
        if (debug) console.warn('Invalid referrer URL, falling back to regex:', e);
        referrerHostname = referrer.match(/^(?:https?:\/\/)?([^\/]+)/i)?.[1] || '';
    }

    // Extract main domain from hostname
    const mainDomain = getMainDomain(referrerHostname);
    
    if (debug) {
        console.log('Full hostname:', referrerHostname);
        console.log('Main domain:', mainDomain);
    }

    // Only proceed if main domain is valid and contains safe characters
    if (!mainDomain || !/^[a-zA-Z0-9.-]+$/.test(mainDomain)) {
        if (debug) console.log('Skipping URL update: Invalid or unsafe main domain');
        return;
    }

    // Update URL with wpsrc and wpcn parameters
    const urlObj = new URL(url);
    
    // Set wpsrc to the main domain (e.g., google.com instead of tagassistant.google.com)
    urlObj.searchParams.set('wpsrc', mainDomain);
    
    // Set wpcn to 'Organic Search' to identify the campaign type
    urlObj.searchParams.set('wpcn', 'Organic Search');

    // Update the URL without reloading (check if history API is available)
    if (window.history && window.history.replaceState) {
        try {
            window.history.replaceState({}, '', urlObj.toString());
            if (debug) console.log('Updated URL with organic search tracking:', urlObj.toString());
        } catch (e) {
            if (debug) console.warn('Failed to update URL:', e);
        }
    } else {
        if (debug) console.warn('History API not supported, cannot update URL');
    }
}

Cross-subdomain Tracking

By default, the Singular WebSDK 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 initSingularSDK() { const config = new SingularConfig(sdkKey, sdkSecret, productId) .withAutoPersistentSingularDeviceId('website-name.com'); window.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 initSingularSDK() { const config = new SingularConfig(sdkKey, sdkSecret, productId) .withPersistentSingularDeviceId(singularDeviceId); window.singularSdk.init(config); }`

Next Steps

Create website links in Singular for your web campaigns
Follow our guides for Google Ads Web, Facebook Web, and TikTok Ads Web, if you run web campaigns for mobile inventory.
Monitor your data in Singular reports

Web SDK - Native JavaScript Implementation Guide

Overview

Prerequisites

Implementation Steps

Step 1: Add the SDK Library Script

Using with Next.js / React

Method 1: Using Next.js Script Component (Recommended)

Method 2: Dynamic Import for Component-Level Loading

Environment Variables Setup

App Router vs Pages Router

Step 2: Initialize the SDK

Basic DOM-Ready Initialization

Basic Initialization with Global Properties

Basic Initialization with Single-Page Application (SPA) Routing

Example for SPAs (React)

Basic Initialization Using an Initialization Callback

Next.js / React Initialization

TypeScript Type Declarations

Basic Initialization with Next.js Script Component

Initialization with useEffect Hook

Initialization with Configuration Options

Single-Page Application (SPA) Routing

Using an Initialization Callback

Best Practices for Next.js Initialization

Developer Checklist for Next.js

Configuration Options

SingularConfig Method Reference

Developer Checklist

Step 3: Tracking Events

Basic Event Tracking

Conversion Event Tracking

Revenue Event Tracking

Common Event Implementation Patterns

Page Load Events

Button Click Events

Form Submission Events

Step 4: Setting Customer User ID

Step 5: Preventing Duplicate Events

Using Session Storage Method

Step 6: Testing Your Implementation

Verify SDK Loaded

Verify Network Requests

Verify Events

For End-to-End testing, use the Testing Console

Step 7: Implement Web-to-App Forwarding

Web-to-App Attribution Forwarding

Singular WebSDK Demo

Advanced Topics

Singular Banners

Related Articles

Step-by-Step Implementation Guide

Add the Singular Native JavaScript WebSDK Script to your website.

Give Singular Permission to Access Client Hints Data

Add the Banner config option to the WebSDK Initialization

Reshow Banner on Page Route (Single-Page Applications Only)

[Advanced Option] Customize Link Settings

[Advanced Option] Use Code to Force Hiding/Showing of Banners

Global Properties

Organic Search Tracking

Why Use This?

How It Works

Usage

Cross-subdomain Tracking

Method A: Auto-Persist using Cookies

Method B (Advanced): Set Singular Device ID Manually

Next Steps

Related Articles