Web SDK+ Integration Guide

Platform

WebiOSAndroidFlutterReact NativeMAUICordova

For Rokt Ecommerce partners. This complete guide is for ecommerce businesses integrating Rokt into transaction experiences they own. It is not an advertiser implementation guide. Advertisers should use the Rokt Ads integration guides.

This page explains how to implement the Rokt Ecommerce Web SDK+. The SDK+ passes user and transaction data to Rokt on configured pages so Rokt can render relevant experiences, such as offers on confirmation pages.

1. Initialize the Rokt SDK+#

Include the SDK+ initialization script on every page of your site. Browser caching means the SDK+ loads from cache on subsequent pages rather than re-fetching.

For single-page apps: Insert the script into the head of your main index.html, or wherever your content is rendered.

For multi-page apps: Place the script in your primary shared layout file. If you don't use a template-based rendering system, add it to each HTML file.

First-Party Domain Configuration

Using a first-party domain when integrating the Web SDK+ into your site ensures that the SDK+ uses your own domain when making calls to Rokt's API, providing your customers with a seamless experience and minimizing the risk of blocked content. To learn how to configure a first-party domain for your SDK+ integration, see First Party Domain Integration.

Rokt Web SDK+ initialization

<script type="text/javascript">

// Enter your Rokt API key
const API_KEY = "YOUR_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' (preferred).
              email: 'j.smith@example.com',
              // If you're using a hashed email address, set it in 'email_sha256' instead of 'email'.
              email_sha256: 'sha256 hashed email goes here',
              // Customer phone number in E.164 format.
              mobile_number: '+13125551515',
              // If you're using a hashed mobile number, set it in 'mobile_sha256' instead of 'mobile_number'.
              mobile_sha256: 'sha256 hashed mobile goes here',
              // Partner's internal customer/account identifier (if the user is logged in).
              customerid: 'cust_10482'
          }
      },
      // 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');
          }
      }
  }
};

// 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.8; 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","hashSha256","setExtensionData","use","getVersion","terminate","onShoppableAdsReady"].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("&"); c.onerror = function() { var u = ["https://apps.","rokt","ecommerce",".com"].join(""); window.ROKT_DOMAIN = u; mParticle.config.domain = u.split("//")[1]; var d = document.createElement("script"); d.type = "text/javascript"; d.async = !0; d.src = u + "/js/v2/" + e + "/app.js" + n + "&" + s.join("&"); var f = document.getElementsByTagName("script")[0]; f.parentNode.insertBefore(d, f); }; var l = document.getElementsByTagName("script")[0]; l.parentNode.insertBefore(c, l); })(API_KEY);
</script>

When inserting the initialization script into your site, you will see customizable fields for:

1Entering your Rokt API key#

Set API_KEY to the Rokt API key provided by your Rokt account manager.

2Entering a custom first-party domain#

Follow the instructions in First-Party Domain Configuration, and set ROKT_DOMAIN to your custom subdomain. Routing the Rokt SDK+ through your own domain reduces the risk of ad blockers and browsers from blocking ads or data.

3Setting your data environment#

Set isDevelopmentMode to true while testing to route data to the Development environment, and false to send live customer activity to Production.

4Identifying your user and setting attributes#

In identifyRequest, pass the user's raw, un-hashed email in the email field. Include mobile_number and customerid when available — more signals improve identity resolution. Once identified, use the identityCallback to set additional user attributes. For a list of recommended attributes, see User attributes.

identityCallback

// The identityCallback determines if the identifyRequest was successful.
identityCallback: function(result) {
    if (result.getUser()) {
        // If the user was identified, set additional user attributes with setUserAttribute.
        result.getUser().setUserAttribute('attribute_key', 'attribute_value');
    }
}

note

Always include identifyRequest in the initialization script. If you don't have the user's email at initialization, set email to null — the SDK+ will still initialize, and you can identify the user later via Step 2.

2. Identify the User#

The SDK+ initialization script identifies the current user using the identifiers you provided in the script's identifyRequest object. After SDK initialization, you should keep the user's identity in sync whenever they log in, log out, or otherwise provide an identifier (for example, during checkout) using the appropriate method as described below.

Supported user identifiers

Show supported user identifiers

Field	Type	Description
email	string	Raw, unhashed email address.
email_sha256	string	SHA-256 hashed email. Use instead of email when only the hashed form is available.
mobile_sha256	string	SHA-256 hashed mobile number. Use instead of mobile_number when only the hashed form is available.
mobile_number	string	Phone number in E.164 format (e.g. +13125551515).
customerid	string	Internal customer/account identifier. Send on every page for logged-in users.

To identify the user:

1Create an identifyRequest object#

Create an identifyRequest object to contain the user's identifiers. You should integrate the user's raw, unhashed email address into the email field.

2Create an identityCallback#

To set additional user attributes, create an identityCallback. If the identifyRequest succeeds, then any user attributes you set inside the callback are assigned to the identified user.

3Send the request using the method that matches the user's action#

Pass the identifyRequest (and optional identityCallback) to the method that matches the user's action:

• mParticle.Identity.login: call when the user logs in or creates an account.
• mParticle.Identity.identify: call when you obtain the user's email mid-session without a login transition (for example, a guest enters their email at checkout).
• mParticle.Identity.logout: call when the user logs out.

Calling these methods transitions the SDK's record of the current user's state. The login and logout methods also automatically log a corresponding event to improve Rokt's attribution.

For example, to identify a user named Jane Smith with the email address j.smith@example.com, mobile number +13125551515, and customer ID cust_10482:

Example user identification

// 1. Create the identifyRequest object
const identifyRequest = {
  userIdentities: {
      email: 'j.smith@example.com',
      // If you are passing a hashed email address, set it inside the 'email_sha256' field instead of 'email'.
      email_sha256: 'SHA-256 hashed email address',
      mobile_number: '+13125551515',
      // If you are passing a hashed mobile number, set it inside the 'mobile_sha256' field instead of 'mobile_number'.
      mobile_sha256: 'SHA-256 hashed mobile number',
      customerid: 'cust_10482'
  }
};
// 2. User attributes are set using identityCallback
const identityCallback = function(result) {
  if (result.getUser()) {
      result.getUser().setUserAttribute('firstname', 'Jane');
      result.getUser().setUserAttribute('lastname', 'Smith');
  }
};
// 3. Call one of the following methods that best matches the user's action:
mParticle.Identity.login(identifyRequest, identityCallback); // Call when the user logs in or creates an account
mParticle.Identity.identify(identifyRequest, identityCallback); // Call when you obtain the user's email mid-session, but not during a login
mParticle.Identity.logout({}); // Call when the user logs out

3. Set User Attributes#

Set user attributes progressively throughout the complete customer journey, not just at checkout. The more attributes you set, the better Rokt can resolve the customer's identity and deliver relevant offers.

Set attributes as early as possible

Set new user attributes as they become available. Earlier attribute collection gives Rokt more signals with which to improve the speed and relevance of placements rendered on the confirmation page.

Set User Attributes

// To retrieve the current user, call getCurrentUser.
const currentUser = mParticle.Identity.getCurrentUser();

// Once you have successfully set the current user to a const called `currentUser`, you can set user attributes with:
currentUser.setUserAttribute("firstname", "Jane");
currentUser.setUserAttribute("lastname", "Smith");
currentUser.setUserAttribute("mobile_number", "+13125551515");
currentUser.setUserAttribute("birthyear", 1990);
currentUser.setUserAttribute("gender", "F");

// Address attributes (collect the billing address at checkout)
currentUser.setUserAttribute("billingaddress1", "123 Main St");
currentUser.setUserAttribute("billingaddress2", "Apt 4B");
currentUser.setUserAttribute("billingcity", "Brooklyn");
currentUser.setUserAttribute("billingstate", "NY");
currentUser.setUserAttribute("billingzipcode", "11201");
currentUser.setUserAttribute("country", "US");

// Lifecycle and loyalty attributes
currentUser.setUserAttribute("customertype", "logged_in");
currentUser.setUserAttribute("newcustomer", false);
currentUser.setUserAttribute("loyaltytier", "gold");
currentUser.setUserAttribute("loyaltyid", "LOY-7781");
currentUser.setUserAttribute("customersegment", "vip");

// Marketing attribution
currentUser.setUserAttribute("utmsource", "google");
currentUser.setUserAttribute("utmmedium", "cpc");
currentUser.setUserAttribute("utmcampaign", "spring_sale");

// To set a list attribute, set the value of the attribute to an array of strings. For example:
currentUser.setUserAttribute("favorite_genres", ["documentary", "comedy", "romance", "drama"]);

// To remove a user attribute, call removeUserAttribute and pass in the attribute name. All user attributes share the same key space.
currentUser.removeUserAttribute("attribute_to_remove");

User attributes

Set as many of the following attributes as you can collect.

Show all user attributes

Field	Type	Description
firstname	string	Customer's first name. Used for personalization.
lastname	string	Customer's last name. Used for personalization.
mobile_number	string	Phone number formatted as 1112345678 or +1 (222) 345-6789. Used for identity resolution and relevance.
birthyear	integer	Customer's birth year (e.g. 1990). Preferred date-of-birth field. Alternates: dob (yyyymmdd), age. Used for eligibility and relevance.
dob	string	Date of birth, yyyymmdd. Alternate to birthyear. Used for eligibility and relevance.
age	integer	Customer's age. Alternate to birthyear. Used for eligibility and relevance.
gender	string	Customer's gender. For example, M, F, Male, or Female. Used for relevance.
title	string	Honorific. For example, Mr, Mrs, Ms. Used for personalization.
language	string	ISO 639-1 language code associated with the purchase. Used for relevance.
billingaddress1	string	Street address (e.g. 123 Main St). Used for identity resolution and relevance.
billingaddress2	string	Apartment/unit (e.g. Apt 4B). Used for identity resolution.
billingcity	string	Billing city. Used for relevance.
billingstate	string	Billing state / province / region. Used for relevance and eligibility.
billingzipcode	string	Full ZIP or postcode (US preference is ZIP+4). Used for identity resolution and relevance.
country	string	ISO 3166-1 alpha-2 country code (e.g. US, GB, AU). Used for eligibility and relevance.
newcustomer	boolean	Whether this is a first-time buyer (true / false). Used for relevance.
customertype	string	Whether the user is authenticated (guest / logged_in). Used for relevance.
loyaltytier	string	Partner loyalty program tier. Used for relevance and eligibility.
loyaltyid	string	Loyalty program member ID. Used for identity resolution.
predictedltv	decimal	Predicted total lifetime value, typically produced by a partner machine-learning model. Used for relevance.
subscriptionstatus	string	Subscription state if applicable (active, trial, churned, paused, none). Used for relevance and eligibility.
customersegment	string	Partner internal segmentation (e.g. vip, at_risk, new, reactivated). Used for relevance.
acquisitionchannel	string	How the customer was originally acquired. Used for relevance.
utmsource	string	Marketing attribution source. Used for relevance.
utmmedium	string	Marketing attribution medium. Used for relevance.
utmcampaign	string	Marketing attribution campaign. Used for relevance.
utmcontent	string	Marketing attribution content variant. Used for relevance.
utmterm	string	Marketing attribution term / keyword. Used for relevance.
referrer	string	Referring URL — intent signal. Used for relevance.

note

All user attributes (including list attributes and tags) must have distinct names.

4. Log Events#

Log page views, commerce events, and custom events so Rokt can understand where each customer is in their journey.

Event category

Page views tell Rokt which page the customer is on. Wrap each call in mParticle.ready() so it fires after the SDK+ initializes. On transactional pages (PLP, PDP, cart, checkout, confirmation), also fire the matching commerce event from Commerce events to send product- and order-level details.

Page type

Log this when the customer lands on your site's home page, including empty-path roots like /.

Field	Type	Description
screenname	string	Last segment of the URL path (e.g. /products/shoes → shoes). Defaults to home if the path is empty.
pagetype	string	Type of page being viewed: home, PLP, PDP, cart, checkout, confirmation.
url	string	Full URL of the current page.
title	string	Page title (from document.title).
sitesection	string	Top-level site section (e.g. mens, womens, support).
referringpage	string	Referring URL captured from document.referrer.

Example home page view

window.mParticle.ready(function() {
mParticle.logPageView("page_view", {
  screenname: "home",
  pagetype: "home",
  url: window.location.toString(),
  title: document.title,
  sitesection: "root",
  referringpage: document.referrer
});
});

5. Show a Placement#

On every payment and confirmation page where you want Rokt to render content, call selectPlacements with one of the supported page identifiers and the customer + transaction attributes. Rokt uses these signals to choose and render the most relevant offer.

Attributes passed in selectPlacements override any earlier values set via setUserAttribute. Always supply the most recent value.

Page identifiers

• stg.rokt.conf: A confirmation page in a staging (or testing) environment.
• prod.rokt.conf: A confirmation page in a production environment.
• stg.rokt.payments: A payments page in a staging (or testing) environment.
• prod.rokt.payments: A payments page in a production environment.

Placement position

Pass the same set of attributes regardless of placement position. The full attribute reference is below.

Show all placement attributes

Field	Type	Description
email	string	Customer email address (unhashed). Used for identity resolution and Shoppable Ads order confirmation.
firstname	string	Customer first name. Used for personalization and Shoppable Ads order fulfillment.
lastname	string	Customer last name. Used for personalization and Shoppable Ads order fulfillment.
mobile_number	string	Customer mobile number (E.164 format, e.g. +13125551515). Used for identity resolution and Shoppable Ads.
confirmationref	string	Order / confirmation reference number. Used for relevance, deduplication, and Shoppable Ads order reconciliation.
currency	string	Transaction currency (ISO 4217, e.g. USD, GBP, AUD, JPY). Used for relevance and Shoppable Ads.
country	string	ISO 3166-1 alpha-2 country code. Used for eligibility and relevance.
language	string	Customer's preferred language (ISO 639-1, e.g. en, de, fr). Used for relevance.
totalprice	decimal	Total cart value including tax and shipping. Used for relevance.
amount	decimal	Cart subtotal before tax and shipping. Distinct from totalprice. Required for Pay+ on the payments page; also used by Shoppable Ads.
cartItems	array	Structured array of cart-line objects. See Cart items reference under Commerce Events. Used for relevance.
couponcode	string	Promo code applied, if any. Used for relevance.
newcustomer	boolean	Whether this is a first-time buyer. Used for relevance.
customertype	string	Whether the user is authenticated (guest / logged_in). Used for relevance.
value	decimal	Customer cumulative purchase value. Used for relevance.
subscriptionstatus	string	Subscription state if applicable (active, trial, churned, paused, none). Used for relevance and eligibility.
customersegment	string	Partner internal segmentation (vip, at_risk, new, reactivated). Used for relevance.
paymenttype	string	Payment method selected (credit_card, paypal, apple_pay, gift_card). Used for Pay+ eligibility and Shoppable Ads payment method prioritization.
paymentServiceProvider	string	Comma-separated list of payment methods accepted on the page (e.g. "cardpayment,paypal"). Accepted values: applepay, googlepay, paypal, venmo, affirm, afterpay, klarna, alipay, amazonpay, cardpayment, rakutenpay. Must be camelCase. Used for Pay+ eligibility.
ccbin	string	Credit card BIN (6-8 digits). Used for relevance.
billingaddress1	string	Billing street address. Used for identity resolution and relevance.
billingaddress2	string	Billing apartment/unit. Used for identity resolution.
billingcity	string	Billing city. Used for relevance.
billingstate	string	Billing state / region. Used for relevance.
billingzipcode	string	Billing ZIP / postcode. Used for identity resolution, relevance, and Shoppable Ads.
billingname	string	Full cardholder name on the billing address. Used for identity resolution and payment validation.
shippingmethod	string	Shipping method selected (standard, express, next_day). Used for relevance.
shippingname	string	Full recipient name on the shipping address. Used for Shoppable Ads order fulfillment.
shippingaddress1	string	Shipping street address. Used for relevance and Shoppable Ads order fulfillment.
shippingcity	string	Shipping city. Used for relevance and Shoppable Ads order fulfillment.
shippingstate	string	Shipping state / region. Used for relevance and Shoppable Ads order fulfillment.
shippingzipcode	string	Shipping ZIP / postcode. Used for relevance and Shoppable Ads order fulfillment.
shippingcountry	string	Shipping country (ISO 3166-1 alpha-2). Used for relevance and Shoppable Ads order fulfillment.
partnerpaymentreference	string	Non-guessable identifier used to look up the customer's vaulted payment method. Required for Shoppable Ads card forwarding; if absent, card forwarding is unavailable.
last4digits	string	Last 4 digits of the card used on the primary transaction. Displayed to the customer for confirmation during Shoppable Ads.
plcc	string	"yes" or "no" — whether the customer has a private-label credit card with the partner. Used for Pay+ relevance.
discountamount	decimal	Order-level discount applied (e.g. 10.00). Used for Pay+ relevance.
prescreen	string	"yes" or "no" — whether the customer has pre-qualified for a credit offer. Used for Pay+ relevance.

note

Do not send cart items as comma-separated strings or as a stringified JSON blob. Send a real JSON array so the fields stay typed. For the full cart-item field reference, see the Cart items section under Commerce Events.

Overlay placements render on top of your confirmation page in a Rokt-managed container, requiring no changes to your page's DOM. Used for standard Thanks Ads and Shoppable Ads.

To insert an overlay placement, call selectPlacements once the confirmation page loads:

Example overlay selectPlacements call

window.mParticle.ready(async function () {
const selection = await window.mParticle.Rokt.selectPlacements({
  identifier: "prod.rokt.conf",
  attributes: {
    // Identity
    email: "j.smith@example.com",
    firstname: "Jenny",
    lastname: "Smith",
    mobile_number: "+13125551515",

    // Transaction
    confirmationref: "ORDER-10482",
    currency: "USD",
    country: "US",
    language: "en",
    totalprice: 149.99,
    couponcode: "SUMMER20",

    // Customer context
    newcustomer: false,
    customertype: "logged_in",
    value: 2340.00,
    subscriptionstatus: "active",
    customersegment: "vip",

    // Payment (include paymenttype + paymentServiceProvider for Pay+)
    paymenttype: "credit_card",
    paymentServiceProvider: "cardpayment",
    ccbin: "411112",

    // Cart contents — see the Placement Attributes reference for the full
    // attribute set and the Cart items reference for the per-line shape.
    cartItems: [
      { cartitemid: "SKU-001", productsku: "SKU-001", productname: "Trail Runner v3", itemprice: 129.95, quantity: 1 }
    ]
  }
});
});

6. Subscribe to Placement Events#

The SDK+ emits events throughout the placement lifecycle. Subscribe to these events to run custom logic when a placement is ready, when a customer engages with a placement, or when an interstitial placement wrapper transitions between states.

Lifecycle event source

By subscribing to a placement event you can receive notifications that are triggered when a placement is ready or when a customer engages with an offer.

Subscribe to Placement Events

window.mParticle.ready(async function () {
const selection = await window.mParticle.Rokt.selectPlacements({
  // add attributes
});

// Listen for when the placement becomes interactive/ready to display
selection.on('PLACEMENT_INTERACTIVE').subscribe(() => {
  // Logic to run after Placement has become interactive
});

// Listen for when user engages positively or negatively with an offer
selection.on('OFFER_ENGAGEMENT').subscribe(function () {
  // Logic to run after offer is engaged with
});
});

7. Appendix#

Reference for closing placements in single-page apps, enabling extensions for advanced features, and configuring optional launcher behavior.

Close a placement

In single-page apps, call .close() on the placement object after the user navigates away so the placement doesn't linger on back-navigation.

Close a placement

// Closes the placement called 'selection'
selection.close();

Pay+

If you are using Pay+, you must close your placement after the user navigates away.

Additional functionality via extensions

Some features require extensions. Enable them by calling mParticle.Rokt.use() before selectPlacements(). For example, to display upsell placements on a Thank You page, enable the ThankYouPageJourney extension first:

Enable the ThankYouPageJourney extension

window.mParticle.ready(async function() {
// Enable the necessary extension prior to selecting placements
await window.mParticle.Rokt.use("ThankYouPageJourney");

const selection = await mParticle.Rokt.selectPlacements({
  identifier: "yourPageIdentifier",
  attributes: {
    "email": "j.smith@example.com"
    // Any additional user attributes you want to pass to Rokt
  },
});
})

Passing additional integration launcher options

Configure optional behavior by setting window.mParticle.config.launcherOptions in the initialization script:

launcherOptions config

// Include this as part of the initialization script in step 1 above
window.mParticle.config.launcherOptions = {
  noFunctional: true,
  noTargeting: true,
  // See all optional launcher options that can be set below
};

Manage customer cookie preferences

Use these options to respect customer opt-out preferences by disabling functional or targeting cookies.

Parameter	Type	Default	Description
noFunctional	boolean	false	Set to true to prevent Rokt from using first-party tracking IDs when the customer has opted out of functional cookies. Functional cookies power first-party personalization and advanced checkout features like Upsells.
noTargeting	boolean	false	Set to true to prevent Rokt from using cross-site tracking IDs for the session when the customer has opted out of targeting cookies. Functional identifiers remain active unless noFunctional is also set to true.

For a more detailed discussion, see Cookie Consent Flags.

Measure page load performance in single-page apps

Provide the timestamp of when a virtual page loads so Rokt can accurately measure performance in SPAs and detect anomalies that could impact the customer experience.

Parameter	Type	Default
pageInitTimestamp	Date	PerformanceNavigationTiming.responseStart

When the launcher initializes on a virtual page in an SPA, pass the timestamp of when that page was initialized so Rokt can measure load performance relative to the page that triggered it.

Link customer activity with a Rokt session ID

Pass a previously generated Rokt session ID to ensure activity across different parts of the experience is tied together correctly.

Parameter	Type	Default
sessionId	string	—

If you've generated a Rokt session ID from a prior backend interaction, pass it here so Rokt can pair it with front-end activity.

Customize how links open in your experience

Enable this option when you want full control over how Rokt and advertiser links open (for example, inside a WebView instead of a browser).

Parameter	Type	Default
overrideLinkNavigation	boolean	false

When set to true, Rokt stops handling link openings directly and instead emits a LINK_NAVIGATION_REQUEST partner event. To distinguish Rokt and advertiser links from your own, check whether the URL contains "rokt.com".

Subscribe to the event on the selection returned by selectPlacements. Each event carries a single url string — the link the customer activated. Open it immediately, in whichever context you need (a browser tab, a WebView, and so on), to avoid degrading the customer experience.

Handle LINK_NAVIGATION_REQUEST

const selection = await window.mParticle.Rokt.selectPlacements({
  // identifier and attributes as in the examples above
});

selection.on("LINK_NAVIGATION_REQUEST").subscribe((event) => {
  // event.url is the link the customer activated — open it immediately
  window.open(event.url);
});

If a LINK_NAVIGATION_REQUEST event is not consumed within 3 seconds, an error is raised — make sure an active subscription exists to process the event.

8. Test Your Integration#

To confirm the SDK+ initializes, identifies the user, logs events, and requests offers correctly:

1Open a new browser window#

Open a new browser window so you start with a clean state.

2Open developer tools#

Open your browser's developer tools panel. For most browsers, you can do this by right-clicking on your screen and clicking Inspect.

Enable the option that keeps network requests across page loads (Preserve log in Chrome, Edge, and Safari, or Persist Logs in Firefox).

3Filter network requests#

From the developer tools panel, go to the Network tab and filter for rokt-api.com. If you use a custom first-party domain, filter for your custom subdomain instead.

To find a specific request, you can also filter by its endpoint name: /identity, /events, /experiences, or /offers.

4Run the test journey#

With the Network tab recording, complete a test journey through the pages where you integrated the SDK+.

note

Open the developer tools panel before navigating to your site so the browser records all SDK+ requests.

5Verify the identity request#

Filter for /identity, then select the request that matches the identity action you performed, such as identify or login. Confirm that it has a successful status, then check the Payload or Request tab for the test identifiers you expected to send.

6Verify page-view and commerce events#

Filter for /events, then select the request generated during your test journey. Confirm that it has a successful status. Check the Payload or Request tab to verify that the request contains the page-view or commerce event and the attributes you expected to send.

Event requests can contain multiple events, so inspect the complete request payload when checking for a specific action.

7Verify the selection request#

Filter for /experiences, then for /offers. Depending on your SDK+ routing, a successful selection uses one of these endpoints:

• /v1/experiences
• /v2/sessions/offers

You only need to see one of these requests. Select the request with a 200 status, then check the Payload or Request tab to verify the data being shared with Rokt.

note

During testing, you might also see a /v1/experiences request with a 204 status. Use the request with a 200 status when checking the payload.

Troubleshooting

If your integration isn't working, check the Console tab in your browser's developer tools for Rokt SDK+ errors. Common issues include:

Initialization errors

• Make sure the SDK+ initialization script has been placed on the correct page.
• If you integrated using a tag manager, make sure you configured your tag triggers so that initialization loads on the right pages, and that your selectPlacements and conversion logging tags are firing after the SDK+ has initialized.

Syntax errors

Make sure you are not missing any commas in your integration code.

To check for syntax errors:

1Open the Console tab#

Go to your browser's developer tools panel and select the Console tab.

2Find the error#

If the file where you placed the Web SDK+ has an error, it should be logged in the console. Click the file to see the code and reported error.

3Verify commas#

Any error is indicated in the file. In particular, check that all attributes are separated by commas as shown below.

Missing comma (incorrect)

email: ''
mobile_number: '',

Correct

email: '',
mobile_number: '',