Skip to main content

Web SDK Integration (Joint SDK)

This guide covers how to integrate the Rokt Joint Web SDK on your confirmation page to enable Shoppable Ads. The SDK is lightweight (under 30KB depending on your configuration) and distributed globally via a CDN. For the full SDK reference, including all available attributes and configuration options, see the ecommerce SDK integration guide.

IMPORTANT: These instructions require development resources. If you're already using the Rokt Web SDK on your confirmation page, some steps may already be complete. Contact your Rokt account manager for your JS Web API Key.

Check Your SDK Version

This guide applies to the new Joint Rokt Web SDK (versions after 2.5926.0), which uses the mParticle-based initialization pattern and authenticates with a JS Web API Key. If you are still on the legacy Rokt Web SDK (version 2.5926.0 or earlier), which uses the launcher.js initialization pattern and authenticates with a Rokt Account ID, see the Web SDK Integration (Legacy) guide instead. For migration instructions, see the Web SDK Migration Guide.

PrerequisitesDirect link to Prerequisites

  • A Rokt account with an active JS Web API Key (provided by your Rokt account manager).
  • Access to modify your confirmation/thank-you page HTML and JavaScript.
  • Familiarity with the Rokt Web SDK documentation.

Payment methodsDirect link to Payment methods

In addition to the below instructions, you will also need to integrate with at least one Payment Method to allow your customers to complete a purchase.

Step 1: Add the initialization scriptDirect link to Step 1: Add the initialization script

The following snippet should be included on every page of your web app. Ideally, it should be placed within the <head> tag or otherwise loaded as early as possible on each page.

When a user can be identified at SDK initialization, include their attributes in the initialization config via the identifyRequest field.

<script type="text/javascript">
    // Include Rokt Template elements JavaScript file
    const roktElements = document.createElement("script");
    roktElements.src = "https://apps.rokt.com/rokt-elements/rokt-element-thank-you.js";
    roktElements.fetchpriority = "high";
    roktElements.crossOrigin = "anonymous";
    roktElements.async = true;
    document.head.appendChild(roktElements);

    // Enter your Rokt API key - provided by your account manager
    const API_KEY = "<JS-Web-API-Key>";

    // Enter your custom subdomain if you are using a first-party domain configuration (optional)
    const ROKT_DOMAIN = "https://apps.rokt-api.com";

    window.mParticle = {
        config: {
            // Set the data environment:
            // Set isDevelopmentMode to true if you are still testing your integration.
            // Set isDevelopmentMode to false if your integration is ready for production data.
            isDevelopmentMode: true,

            // Identify the current user:
            // If you do not have the user's email address, you can pass in a null value
            identifyRequest: {
                userIdentities: {
                    // If you're using an un-hashed email address, set it in 'email'.
                    email: 'j.smith@example.com',
                }
            },

            // If the user is identified with their email address, set additional user attributes.
            identityCallback: function(result) {
                if (result.getUser()) {
                    result.getUser().setUserAttribute('attribute-key', 'attribute-value');
                    result.getUser().setUserAttribute('firstname', 'john');
                }
            }
        }
    };

    // Load the SDK
    (function(e) { window.mParticle = window.mParticle || {}; window.mParticle.EventType = { Unknown: 0, Navigation: 1, Location: 2, Search: 3, Transaction: 4, UserContent: 5, UserPreference: 6, Social: 7, Other: 8, Media: 9 }; window.mParticle.eCommerce = { Cart: {} }; window.mParticle.Identity = {}; window.mParticle.Rokt = {}; window.mParticle.config = window.mParticle.config || {}; window.mParticle.config.rq = []; window.mParticle.config.snippetVersion = 2.6; window.mParticle.ready = function(e) { window.mParticle.config.rq.push(e); }; ["endSession", "logError", "logBaseEvent", "logEvent", "logForm", "logLink", "logPageView", "setSessionAttribute", "setAppName", "setAppVersion", "setOptOut", "setPosition", "startNewSession", "startTrackingLocation", "stopTrackingLocation"].forEach(function(e) { window.mParticle[e] = function() { var t = Array.prototype.slice.call(arguments); t.unshift(e); window.mParticle.config.rq.push(t); }; }); ["setCurrencyCode", "logCheckout"].forEach(function(e) { window.mParticle.eCommerce[e] = function() { var t = Array.prototype.slice.call(arguments); t.unshift("eCommerce." + e); window.mParticle.config.rq.push(t); }; }); ["identify", "login", "logout", "modify"].forEach(function(e) { window.mParticle.Identity[e] = function() { var t = Array.prototype.slice.call(arguments); t.unshift("Identity." + e); window.mParticle.config.rq.push(t); }; }); ["selectPlacements","hashAttributes","setExtensionData"].forEach(function(e) { window.mParticle.Rokt[e] = function() { var t = Array.prototype.slice.call(arguments); t.unshift("Rokt." + e); window.mParticle.config.rq.push(t); }; }); var t = window.mParticle.config.isDevelopmentMode ? 1 : 0, n = "?env=" + t, a = window.mParticle.config.dataPlan; if (a) { var o = a.planId, r = a.planVersion; o && (r && (r < 1 || r > 1e3) && (r = null), n += "&plan_id=" + o + (r ? "&plan_version=" + r : "")); } var i = window.mParticle.config.versions, s = []; i && Object.keys(i).forEach(function(e) { s.push(e + "=" + i[e]); }); var c = document.createElement("script"); c.type = "text/javascript"; c.async = !0; window.ROKT_DOMAIN = ROKT_DOMAIN || 'https://apps.rokt-api.com'; mParticle.config.domain = ROKT_DOMAIN.split('//')[1]; c.src = ROKT_DOMAIN + "/js/v2/" + e + "/app.js" + n + "&" + s.join("&"); var l = document.getElementsByTagName("script")[0]; l.parentNode.insertBefore(c, l); })(API_KEY);
</script>

Step 2: Identify the userDirect link to Step 2: Identify the user

If a user can't be identified when the SDK initializes, you can defer identification until later — for example, when a guest begins checkout. As user data becomes available, update attributes using the snippet below.

Optionally, provide a callback when issuing the identifyRequest to set additional attributes at the moment of identification. If the identifyRequest succeeds, any attributes you set within the identityCallback are applied to the user.

const identifyRequest = {
    userIdentities: {
        // If you're using an un-hashed email address, set it in 'email'.
        email: 'j.smith@example.com',
        // If you're using a hashed email address, set it in 'other' instead of 'email'.
        other: 'sha256 hashed email goes here'
    }
};

const identityCallback = function(result) {
    if (result.getUser()) {
        result.getUser().setUserAttribute('firstname', 'John');
        result.getUser().setUserAttribute('lastname', 'Smith');
    }
};

window.mParticle.ready(function() {
    window.mParticle.Identity.identify(identifyRequest, identityCallback);
});

NOTE: User attributes can also be supplied via the selectPlacements call. Attributes set at that step override attributes provided earlier in the flow.

Step 3: Track page viewsDirect link to Step 3: Track page views

To log a page view, use the logPageView() method after the SDK has been initialized. In the example below, the event includes a screen_name derived from the last segment of the URL path (with a fallback to "home"), the full url of the current page, and the referring-page captured from document.referrer.

// Wait for the SDK to be fully loaded before logging the event
window.mParticle.ready(function() {
    mParticle.logPageView(
        // Event name: "page view" identifies the type of event being logged
        "page view",
        {
            // Capture the last segment of the URL path as the screen name,
            // e.g., "/products/shoes" → "shoes". Defaults to "home" if the path is empty.
            "screen_name": location.pathname.split("/").filter(Boolean).pop() || "home",

            // Record the full URL of the current page (including protocol, path, query, and hash)
            "url": window.location.toString(),

            // Capture the URL of the page that referred the user to this one,
            // if available. This helps track user navigation between pages or sites.
            "referring-page": document.referrer
        }
    );
});

Step 4: Select a placementDirect link to Step 4: Select a placement

When selecting a placement, include the relevant user attributes in the selectPlacements call. Attributes provided in this invocation override those set earlier during the identifyRequest interaction.

window.mParticle.ready(async function() {
    // Activate the Shoppable Ad support
    await window.mParticle.Rokt.use('ThankYouPageJourney');
    const selection = await window.mParticle.Rokt.selectPlacements({
        identifier: "stg.rokt.conf",
        // "stg.rokt.conf" is the page identifier for lower environments.
        // Update to "prod.rokt.conf" for production environments.
        Attributes: {
            // New attributes necessary for Shoppable Ads
            last4digits: "",
            partnerpaymentreference: "",
            shippingaddress1: "",
            shippingaddress2: "",
            shippingcity: "",
            shippingstate: "",
            shippingzipcode: "",
            shippingcountry: "",

            // Existing attributes necessary for Shoppable Ads
            paymenttype: "",
            email: "",
            firstname: "",
            lastname: "",

            // Existing attributes already used for Rokt Thanks
            amount: "",
            ccbin: "",
            currency: "",
            language: "",
            cartItems: JSON.stringify([{
                // items purchased
            }]),

            // ... other attributes
        },
    });
});

NOTE: For the full list of supported attributes, see the Web SDK integration guide. The identifier value will be provided by your Rokt account manager (stg.rokt.conf for lower environments, prod.rokt.conf for production). The partnerpaymentreference must be a non-guessable identifier used to look up the customer's payment method for forwarding. If missing or blank, Rokt will assume credit card details cannot be forwarded and the Shoppable Ads placement will not render an offer.

Step 5: Add the Thank You containerDirect link to Step 5: Add the Thank You container

Wrap your confirmation page content with the <rokt-thank-you> element. This enables the Rokt SDK to inject a full-screen overlay placement (the "Thank You Placement") before the native confirmation content becomes visible. If no eligible offer from the Rokt Catalog is available, the container behaves normally and your confirmation content is shown as usual.

<body>
    Your Header ...
    <rokt-thank-you loader="./assets/loader.gif" id="rokt-thank-you">
        Your Confirmation Content ...
    </rokt-thank-you>
    Your Footer ...
</body>

NOTE: The loader attribute accepts a URL to a loading indicator/spinner GIF to be displayed while the Shoppable Ads experience loads. Please provide your own loading asset URL.

The following attributes are required or recommended for Shoppable Ads to function correctly. For the full attribute reference, see the Web SDK docs.

AttributeExample ValueDescription
emailj.smith@example.comCustomer's email address. Must be raw (unhashed) to allow the brand to send order confirmation.
firstnameJaneCustomer's first name. Used for order fulfillment.
lastnameSmithCustomer's last name. Used for order fulfillment.
partnerpaymentreferenceORD-8829-XK2Non-guessable identifier used to look up the customer's vaulted payment method. If missing, card forwarding will not be available.
last4digits4242Last 4 digits of the card used for the primary transaction. Displayed to the customer for confirmation.
paymenttypevisaPayment method used for the primary transaction (e.g., visa, mastercard, amex, paypal). Used to determine which payment options to display.
shippingaddress1123 Main StCustomer's shipping/delivery address line 1.
shippingaddress2Apt 4BCustomer's shipping/delivery address line 2.
shippingcityBrooklynCustomer's shipping/delivery city.
shippingstateNYCustomer's shipping/delivery state.
shippingzipcode11201Customer's shipping/delivery zip code.
shippingcountryUSCustomer's shipping/delivery country code.
amount52.25Transaction amount.
currencyUSDTransaction currency code.
confirmationrefTXN-20250217-001Order confirmation reference.
billingzipcode11201Customer's billing zip code.
mobile3125551515Customer's mobile phone number.
countryUSCustomer's country code.
languageenLanguage associated with the purchase.

NOTE: If your platform does not have shipping address details available (e.g., ticket or digital goods purchases), ensure that billing address details are passed instead. Rokt will provide a UI for the customer to confirm or edit their address before completing the purchase.

Additional optionsDirect link to Additional options

The Rokt Web SDK supports additional configuration such as cookie consent controls, SPA lifecycle management, and event subscriptions. For details, see the full SDK documentation.

Was this article helpful?
Last updated Mar 2, 2026