SDK Integration

Audience

This API surface is for integration partners building on top of the Rokt network. Rokt ecommerce partners integrating placements on their own checkout should use the Rokt Ecommerce developer docs instead.

Once a merchant is registered via POST /v1/accounts/register/partnership, the response carries the account_id and, if you supplied pages, one page_identifier per surface. The merchant's pages need:

The Rokt SDK loaded once per page (the loader script in step 1 below).
A selectPlacements call on each surface, passing the matching page_identifier. For embedded surfaces, an anchor element (<div id="rokt-container"></div> by default) where the placement should render.

See Pages and Layouts for the surface vocabulary and how the response maps to your SDK code.

This page covers the standard multipage-application integration. For single-page applications, see the SPA notes at the bottom.

1. Load the SDKDirect link to 1. Load the SDK

Embed the loader in the <head> of the merchant's page. The loader fetches launcher.js asynchronously and resolves a promise when it's ready.

warning

Replace <your-rokt-account-id> with the account_id returned from the merchant's POST /v1/accounts/register/partnership response. Each merchant has its own account_id.

note

Google Tag Manager users: make sure the document.write field is checked on the custom HTML tag. Without it, the loader's script-injection step is blocked and the SDK never initializes.

<!DOCTYPE html>
<html lang="en">
<head>
  <!-- Meta tags -->

  <!-- Part #1 — Load the Rokt SDK -->
  <script type="module">
    window.RoktLauncherScriptPromise = new Promise((resolve, reject) => {
      const target = document.head || document.body;
      const script = document.createElement("script");
      script.type = "text/javascript";
      script.src = "https://apps.rokt.com/wsdk/integrations/launcher.js";
      script.fetchPriority = "high";
      script.crossOrigin = "anonymous";
      script.async = true;
      script.id = "rokt-launcher";

      script.addEventListener('load', () => resolve());
      script.addEventListener('error', (error) => reject(error));

      target.appendChild(script);
    });
  </script>

  <!-- Other scripts and meta tags -->
</head>
<body>
  <!-- Your HTML content here -->

  <!-- Part #2 — As soon as customer attributes are available, render the placement -->
  <script type="module">
    await window.RoktLauncherScriptPromise;

    const launcher = await window.Rokt.createLauncher({
      // Use the account_id returned from POST /v1/accounts/register/partnership
      accountId: "<your-rokt-account-id>",
      sandbox: true,
    });

    await launcher.selectPlacements({
      identifier: "confirmation_page",   // ← page_identifier from /register response, matched per surface
      attributes: {
        email: "",
        firstname: "",
        lastname: "",
        confirmationref: "",
        billingzipcode: "",
        amount: "",
        country: "",
        currency: "",
        mobile: "",
        // ... additional attributes
      },
    });
  </script>

  <!-- Your HTML content here -->
</body>
</html>

Load the SDK early (in <head>), then invoke selectPlacements as soon as the customer attributes (email, order total, etc.) are available. Earlier attribute availability gives the SDK more time to render the placement before the page is interactive.

2. Customer attributesDirect link to 2. Customer attributes

Pass as many of the following as the merchant's checkout collects. More attributes mean better relevance and higher fill rates.

Attribute	Description
`email`	Raw, unhashed email. Primary identity signal.
`firstname`, `lastname`	Customer name.
`confirmationref`	Order confirmation number.
`billingzipcode`	Billing ZIP / postcode.
`amount`	Order total.
`country`	ISO 3166-1 alpha-2 country code (`US`, `GB`, `AU`).
`currency`	ISO 4217 currency code (`USD`, `GBP`, `AUD`).
`mobile`	Phone number in E.164 format (`+13125551515`).
`age`, `gender`	Demographic signals.
`billingaddress1`, `billingaddress2`	Billing street address.
`language`	Page locale (ISO 639-1).
`cartItems`	Stringified JSON array of cart line items.

If only the hashed form of an identifier is available, use email_sha256 or mobile_sha256 in place of email / mobile.

3. Sandbox vs productionDirect link to 3. Sandbox vs production

While testing, set sandbox: true in the createLauncher call. When the merchant is ready to go live, set sandbox: false or remove the field entirely.

tip

Direct integration of the snippet is the recommended path, but deploying the SDK via a tag manager (Google Tag Manager, Tealium, Adobe Experience Platform) is also supported. Direct injection minimizes load-time overhead and avoids tag-manager-specific gotchas.

4. Embedded placementsDirect link to 4. Embedded placements

If the partnership preset creates an embedded placement, the merchant's page must include the target HTML element the placement anchors to (default: <div id="rokt-container"></div>). The exact selector is configured in the partnership preset.

5. Test the integrationDirect link to 5. Test the integration

Confirm in the merchant's browser console that:

window.Rokt is defined after launcher.js loads
createLauncher resolves without errors
selectPlacements is called with the customer attributes populated

If selectPlacements returns successfully but no placement renders, verify the identifier you're passing matches the page_identifier returned by /register for that surface. The full list of identifiers (confirmation_page, tracking_page, returns_page) is documented in Pages and Layouts.

tip

Slow page loads? If the placement consistently renders after the page is interactive and the merchant flags it as a load-speed issue, a preparative iframe can pre-warm the SDK before selectPlacements is called. Reach out to your Rokt contact if you want to explore this — it's a per-merchant optimization, not a default.

Single page applicationsDirect link to Single page applications

For SPAs (React, Vue, Angular, etc.), call selectPlacements whenever the route changes to a page that should show a Rokt placement. Do not call createLauncher more than once per session.