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

警告

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.

注記

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 attributes2. 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 production3. 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.

ヒント

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 placements4. 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 integration5. 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.

ヒント

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