SDK Migration Guides

This page covers migration guidance for Rokt SDKs. For Web SDK upgrades, see the section below. For iOS (mParticle Apple SDK) 9.0 upgrades, see mParticle Apple SDK 9.0. For React Native upgrades, see React Native SDK+ 3.0 or React Native Legacy SDK 5.0. For Flutter upgrades, see Flutter SDK+ 2.0 or Flutter Legacy SDK 5.0.

mParticle Apple SDK 9.0 (iOS)Direct link to mParticle Apple SDK 9.0 (iOS)

If you are upgrading the mParticle Apple SDK (and Rokt kit) from 8.x to 9.x in your iOS app, several breaking changes apply.

Type system: MPRokt types → RoktContractsDirect link to Type system: MPRokt types → RoktContracts

The biggest change in 9.0 is that all MPRokt* wrapper types have been removed. The SDK now exposes types from the RoktContracts package directly. In Swift, a single import mParticle_Apple_SDK provides access to all RoktEvent types — no additional imports are needed. In Objective-C, add @import RoktContracts; alongside your mParticle import.

Old (8.x)	New (9.0)
`MPRoktEvent`	`RoktEvent`
`MPRoktConfig`	`RoktConfig` (uses Builder pattern)
`MPRoktEmbeddedView`	`RoktEmbeddedView`
`MPRoktEventCallback`	Removed — use `onEvent` closure
`MPColorModeLight` / `MPColorModeDark`	`RoktColorModeLight` / `RoktColorModeDark` (ObjC) or `.light` / `.dark` (Swift)
`MPRoktEvent.MPRoktPlacementReady`	`RoktEvent.PlacementReady`
`MPRoktEvent.MPRoktPlacementClosed`	`RoktEvent.PlacementClosed`
`MPRoktEvent.MPRoktEmbeddedSizeChanged`	`RoktEvent.EmbeddedSizeChanged`
`MPRoktEvent.MPRoktCartItemInstantPurchase`	`RoktEvent.CartItemInstantPurchase`
Event property: `placementId`	`identifier`

Callbacks → onEventDirect link to Callbacks → onEvent

The MPRoktEventCallback class and the callbacks: parameter on selectPlacements have been removed. Use the onEvent: closure instead.

Before (8.x):

import mParticle_Apple_SDK

let callbacks = MPRoktEventCallback()
callbacks.onLoad = { /* placement loaded */ }
callbacks.onUnLoad = { /* placement unloaded */ }
callbacks.onShouldShowLoadingIndicator = { /* show spinner */ }
callbacks.onShouldHideLoadingIndicator = { /* hide spinner */ }
callbacks.onEmbeddedSizeChange = { (placement, size) in /* resize */ }

MParticle.sharedInstance().rokt.selectPlacements("RoktExperience",
    attributes: attributes, embeddedViews: embeddedViews,
    config: roktConfig, callbacks: callbacks)

After (9.x):

import mParticle_Apple_SDK

MParticle.sharedInstance().rokt.selectPlacements("RoktExperience",
    attributes: attributes, embeddedViews: embeddedViews,
    config: roktConfig) { event in
    switch event {
    case is RoktEvent.ShowLoadingIndicator:
        // Show spinner
    case is RoktEvent.HideLoadingIndicator:
        // Hide spinner
    case is RoktEvent.PlacementReady:
        // Placement loaded
    case is RoktEvent.PlacementClosed:
        // Placement unloaded
    case let sizeEvent as RoktEvent.EmbeddedSizeChanged:
        // Resize: use sizeEvent.identifier and sizeEvent.updatedHeight
    default:
        break
    }
}

RoktConfig Builder patternDirect link to RoktConfig Builder pattern

MPRoktConfig with mutable properties is replaced by RoktConfig.Builder:

Before: let config = MPRoktConfig(); config.colorMode = .light

After: let config = RoktConfig.Builder().colorMode(.light).build()

Global eventsDirect link to Global events

A new globalEvents: method is available for subscribing to events from all placements, including InitComplete:

MParticle.sharedInstance().rokt.globalEvents { event in
    if let initEvent = event as? RoktEvent.InitComplete {
        print("SDK initialized: \(initEvent.success)")
    }
}

Shoppable Ads: PaymentKit → PaymentExtensionDirect link to Shoppable Ads: PaymentKit → PaymentExtension

If you previously used Rokt_Payment_Kit for Apple Pay:

Old	New
Package: `Rokt_Payment_Kit`	Package: `RoktStripePaymentExtension`
`RoktPaymentKit(applePayMerchantId:)`	`RoktStripePaymentExtension(applePayMerchantId:)`
`Rokt.registerPaymentKit(kit)`	`Rokt.registerPaymentExtension(ext, config:)`
`Rokt.execute(...)` for shoppable placements	`Rokt.selectShoppableAds(...)`

See the Shoppable Ads iOS Integration guide for the updated API.

For the full official migration guide, see Migrating from versions < 9.0.0.

React Native SDK+ 3.0 (react-native-mparticle)Direct link to React Native SDK+ 3.0 (react-native-mparticle)

If you are upgrading react-native-mparticle from 2.x to 3.0 in your React Native app, the following changes apply.

New: Shoppable Ads supportDirect link to New: Shoppable Ads support

Version 3.0 introduces MParticle.Rokt.selectShoppableAds() for displaying Shoppable Ads placements. See the Shoppable Ads React Native Integration guide for full setup instructions.

note

Shoppable Ads in React Native are currently supported on iOS only.

iOS Podfile dependencyDirect link to iOS Podfile dependency

If using Shoppable Ads, add the Stripe payment extension to your ios/Podfile:

pod 'RoktStripePaymentExtension', '~> 1.0'

Payment extension registrationDirect link to Payment extension registration

A new registerPaymentExtension call is required in your native iOS code (AppDelegate) before calling selectShoppableAds. The Stripe publishable key is automatically provided from the mParticle dashboard configuration.

import mParticle_Apple_SDK
import RoktStripePaymentExtension

if let stripeExt = RoktStripePaymentExtension(applePayMerchantId: "merchant.com.yourapp.rokt") {
    MParticle.sharedInstance().rokt.registerPaymentExtension(stripeExt)
}

New Shoppable Ads eventsDirect link to New Shoppable Ads events

The following events are now available via the NativeEventEmitter RoktEvents channel:

Event	Description
`CartItemInstantPurchaseInitiated`	Purchase flow started — user tapped "Buy"
`CartItemInstantPurchase`	Purchase completed successfully
`CartItemInstantPurchaseFailure`	Purchase failed
`CartItemDevicePay`	Apple Pay / device payment triggered
`InstantPurchaseDismissal`	User dismissed the purchase overlay

No breaking changes to existing APIsDirect link to No breaking changes to existing APIs

MParticle.Rokt.selectPlacements() and all other existing APIs continue to work as before.

React Native Legacy SDK 5.0 (@rokt/react-native-sdk)Direct link to React Native Legacy SDK 5.0 (@rokt/react-native-sdk)

If you are upgrading @rokt/react-native-sdk from 4.x to 5.0, the following breaking changes apply.

Breaking: `execute()` renamed to `selectPlacements()`Direct link to breaking-execute-renamed-to-selectplacements

Old (4.x)	New (5.0)
`Rokt.execute(viewName, attributes, placeholders)`	`Rokt.selectPlacements(identifier, attributes, placeholders)`
`viewName` parameter	`identifier` parameter

New: `selectShoppableAds()`Direct link to new-selectshoppableads

Version 5.0 introduces Rokt.selectShoppableAds() for displaying Shoppable Ads placements. See the Shoppable Ads React Native Integration (Legacy) guide for full setup instructions.

note

Shoppable Ads in React Native are currently supported on iOS only.

iOS Podfile dependencyDirect link to iOS Podfile dependency

If using Shoppable Ads, add the Stripe payment extension to your ios/Podfile:

pod 'RoktStripePaymentExtension', '~> 1.0'

Payment extension registrationDirect link to Payment extension registration

A new registerPaymentExtension call is required in your native iOS code before calling selectShoppableAds. For the direct SDK path, you must provide your Stripe publishable key explicitly:

import Rokt_Widget
import RoktStripePaymentExtension

if let stripeExtension = RoktStripePaymentExtension(applePayMerchantId: "merchant.com.rokt.sample") {
    Rokt.registerPaymentExtension(stripeExtension, config: ["stripeKey": "pk_test_placeholder"])
}

New Shoppable Ads eventsDirect link to New Shoppable Ads events

The following events are now available via the NativeEventEmitter RoktEvents channel:

Event	Description
`CartItemInstantPurchaseInitiated`	Purchase flow started — user tapped "Buy"
`CartItemInstantPurchase`	Purchase completed successfully
`CartItemInstantPurchaseFailure`	Purchase failed
`CartItemDevicePay`	Apple Pay / device payment triggered
`InstantPurchaseDismissal`	User dismissed the purchase overlay

Flutter Legacy SDK 5.0 (rokt_sdk)Direct link to Flutter Legacy SDK 5.0 (rokt_sdk)

If you are upgrading rokt_sdk from 4.x to 5.0, the following breaking changes apply.

Breaking: `execute()` renamed to `selectPlacements()`Direct link to breaking-execute-renamed-to-selectplacements-1

Old (4.x)	New (5.0)
`RoktSdk.execute(viewName, attributes, onLoad, ...)`	`RoktSdk.selectPlacements(viewName: viewName, attributes: attributes)`

Removed: callbacks and `setLoggingEnabled()`Direct link to removed-callbacks-and-setloggingenabled

The following callback parameters on execute have been removed:

onLoad
onUnLoad
onShouldShowLoadingIndicator
onShouldHideLoadingIndicator

RoktSdk.setLoggingEnabled() has also been removed.

All lifecycle events are now delivered through the RoktEvents EventChannel:

const EventChannel roktEventChannel = EventChannel('RoktEvents');

roktEventChannel.receiveBroadcastStream().listen((dynamic event) {
  switch (event["event"]) {
    case "InitComplete":
      // SDK initialized
      break;
    case "PlacementReady":
      // Replaces onLoad
      break;
    case "PlacementClosed":
      // Replaces onUnLoad
      break;
    case "ShowLoadingIndicator":
      // Replaces onShouldShowLoadingIndicator
      break;
    case "HideLoadingIndicator":
      // Replaces onShouldHideLoadingIndicator
      break;
    default:
      break;
  }
});

Event property rename: `placementId` → `identifier`Direct link to event-property-rename-placementid--identifier

All event objects now use identifier instead of placementId.

New: `selectShoppableAds()` (iOS only)Direct link to new-selectshoppableads-ios-only

Version 5.0 introduces RoktSdk.selectShoppableAds() for displaying Shoppable Ads placements. See the Flutter Shoppable Ads Integration (Legacy) guide for full setup instructions.

note

Shoppable Ads in Flutter are currently supported on iOS only.

iOS Podfile dependencyDirect link to iOS Podfile dependency

If using Shoppable Ads, add the Stripe payment extension to your ios/Podfile:

pod 'RoktStripePaymentExtension', '~> 0.1'

Payment extension registrationDirect link to Payment extension registration

A new registerPaymentExtension call is required from Dart before calling selectShoppableAds. The host app must also set a payment extension factory in native iOS code (AppDelegate.swift):

import RoktStripePaymentExtension
import rokt_sdk

SwiftRoktSdkPlugin.paymentExtensionFactory = { type, config in
    switch type {
    case "stripe":
        guard let merchantId = config["applePayMerchantId"] else { return nil }
        return RoktStripePaymentExtension(
            applePayMerchantId: merchantId,
            countryCode: config["countryCode"] ?? "US"
        )
    default:
        return nil
    }
}

RoktSdk.registerPaymentExtension(
  extensionType: 'stripe',
  config: {
    'stripeKey': 'YOUR_STRIPE_PUBLISHABLE_KEY',
    'applePayMerchantId': 'merchant.com.yourapp.rokt',
  },
);

New Shoppable Ads eventsDirect link to New Shoppable Ads events

The following events are now available via the RoktEvents EventChannel:

Event	Description
`CartItemInstantPurchaseInitiated`	Purchase flow started — user tapped "Buy"
`CartItemInstantPurchase`	Purchase completed successfully
`CartItemInstantPurchaseFailure`	Purchase failed
`CartItemDevicePay`	Apple Pay / device payment triggered
`InstantPurchaseDismissal`	User dismissed the purchase overlay

Platform availabilityDirect link to Platform availability

Feature	iOS	Android
`selectPlacements`	5.0.0	5.0.0
`selectShoppableAds`	5.0.0	Not yet supported
`registerPaymentExtension`	5.0.0	Not yet supported
`purchaseFinalized`	5.0.0	5.0.0

Flutter SDK+ 2.0 (mparticle_flutter_sdk)Direct link to Flutter SDK+ 2.0 (mparticle_flutter_sdk)

If you are upgrading mparticle_flutter_sdk from 1.x to 2.0 in your Flutter app, the following changes apply.

iOS deployment target raised to 15.6Direct link to iOS deployment target raised to 15.6

The plugin now requires iOS 15.6+. Update the following in your app:

ios/Podfile:
```
platform :ios, '15.6'
```
ios/Flutter/AppFrameworkInfo.plist — set MinimumOSVersion to 15.6.
In Xcode, raise the Runner target's iOS Deployment Target to 15.6.

After updating, run:

cd ios
pod deintegrate
pod install
cd ..

Updated CocoaPods dependenciesDirect link to Updated CocoaPods dependencies

The plugin now depends on mParticle Apple SDK 9. The subspec suffix is no longer valid:

Before (1.x)	After (2.0.0)
`mParticle-Apple-SDK/mParticle ~> 8.5`	`mParticle-Apple-SDK ~> 9.0`

If your app's Podfile pins a subspec (for example pod 'mParticle-Apple-SDK/mParticle', ...), update it to the new form above.

Rokt event channel — new event typesDirect link to Rokt event channel — new event types

Consumers of the EventChannel('MPRoktEvents') stream will receive additional event values. The string values for previously existing event types are unchanged, so existing listeners continue to work.

New event types and their payload keys:

`event`	Additional keys
`CartItemInstantPurchaseInitiated`	`cartItemId`, `catalogItemId`
`CartItemInstantPurchaseFailure`	`cartItemId`, `catalogItemId`, `error`
`InstantPurchaseDismissal`	—
`CartItemDevicePay`	`cartItemId`, `catalogItemId`, `paymentProvider`

New: `selectShoppableAds` (iOS only)Direct link to new-selectshoppableads-ios-only-1

await MparticleFlutterSdk.getInstance().then((mp) => mp?.rokt.selectShoppableAds(
      identifier: 'shoppable-ads-placement',
      attributes: {'email': 'user@example.com'},
    ));

iOS: proxies to MParticle.sharedInstance().rokt.selectShoppableAds(...).
Android: the method is exposed for API parity but is a no-op (logs a warning).
Web: not implemented — calls will throw MissingPluginException.

Events for a shoppable ads placement are delivered on the existing MPRoktEvents EventChannel.

See the Flutter SDK+ Shoppable Ads Integration guide for the full setup.

Payment extension — native-only registrationDirect link to Payment extension — native-only registration

The Rokt Apple Pay payment extension (for example RoktStripePaymentExtension) is not proxied through Dart. Integrators must register it directly from native Swift in the host app (for example ios/Runner/AppDelegate.swift), after MParticle.sharedInstance().start(with:):

import mParticle_Apple_SDK
import RoktStripePaymentExtension

if let stripeExt = RoktStripePaymentExtension(applePayMerchantId: "merchant.com.yourapp.rokt") {
    MParticle.sharedInstance().rokt.registerPaymentExtension(stripeExt)
}

Web SDK Migration GuideDirect link to Web SDK Migration Guide

This guide explains how to migrate from older versions of the Rokt Web SDK (version 2.5926.0 or earlier) to the latest version. It’s relevant to both Rokt Ecommerce and Rokt Ads implementations, and walks you through breaking changes—like the updated initialization script—and how to coordinate with your Rokt account team to complete the migration smoothly.

Initializing the Web SDKDirect link to Initializing the Web SDK

The biggest change introduced in the new SDK is how it's initialized within your website. Prior to the current version, Rokt allowed you to initialize, or load, the SDK by calling either the launcher.js or snippet.js scripts from the <head> tags of each page in your site.

Both of these options have been replaced with a single initialization script.

Remove the deprecated `launcher.js` scriptDirect link to remove-the-deprecated-launcherjs-script

Search your site's code and remove any instances of the launcher.js script.

It should resemble:

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

Remove the deprecated `snippet.js` auto launcherDirect link to remove-the-deprecated-snippetjs-auto-launcher

If you used the auto launcher snippet, search your site's code and remove any instance of the script.

It should resemble:

(function (r, o, k, t, n, e, w, a, _) {
  r._ROKT_ = n;
  r[n] = r[n] || {
    id: t,
    h: w,
    lc: [],
    it: new Date(),
    onLoaded: function (c) {
      r[n].lc.push(c);
    },
  };
  a = o.createElement("script");
  a.type = "text/javascript";
  a.async = !0;
  a.src = k;
  if (e) {
    a.integrity = e;
    a.crossOrigin = "anonymous";
  }
  _ = o.getElementsByTagName("script")[0];
  _.parentNode.insertBefore(a, _);
})(
  window,
  document,
  "https://apps.rokt.com/wsdk/integrations/snippet.js",
  "roktAccountid",
  "rokt"
);

Insert the new SDK initialization snippetDirect link to Insert the new SDK initialization snippet

After removing any instance of the old SDK snippets, insert the new SDK initialization snippet into the <head> tag of each page of your site. If your site is a multi-page application that uses templates, make sure to update your templates so that this new snippet is executed as early as possible on each page load.

New Rokt Web SDK initialization snippetDirect link to New Rokt Web SDK initialization snippet

<script type="text/javascript">

// Enter your Rokt API key
const API_KEY = "YOUR_API_KEY";

// If you configured a first-party domain, set it as the value of DOMAIN instead of the default apps.rokt-api domain
const ROKT_DOMAIN = "https://apps.rokt-api.com";

// Set your SDK configuration settings
window.mParticle = {
    config: {
        // Specify the data environment with isDevelopmentMode:
        // 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 have the user's email address, include it in an object called `userIdentities` within `identifyRequest` as shown below.  
        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'
            },
        }
    },
};

// 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"].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>

The new snippet introduces several new configuration options:

Rokt API keyDirect link to Rokt API key

Previously, you needed to enter your Rokt Account ID into your SDK snippet. This requirement has been replaced by the Rokt API Key.

note

Your Rokt account representative will provide you your Rokt API Key.

First-party domainDirect link to First-party domain

The new Web SDK allows you to route requests to Rokt through your own subdomain. This is referred to as a "first-party domain integration" and can help prevent content from being blocked.

To use a custom subdomain with your integration, follow the instructions in First Party Domain Integration, then replace the value of DOMAIN in your initialization snippet with your own subdomain:

const DOMAIN = "your-new-subdomain-goes-here";

Development modeDirect link to Development mode

Previously, you could set sandbox: true in your SDK snippet to test your integration.

Now, the Rokt SDK includes a configuration option called isDevelopmentMode. By setting this to true, the Rokt SDK will collect and forward data as "development" (aka testing) data. When you're done testing your integration, change isDevelopmentMode to false.

User identification on initializationDirect link to User identification on initialization

During initialization, the SDK submits an identifyRequest to Rokt using either the user's raw or hashed email address (whichever you can provide) to identify the current user. You can supply either the raw or hashed email address within identifyRequest inside your initialization scripts config settings with:

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'
  },
}

Identify the userDirect link to Identify the user

If you can't provide the user's email address when the SDK is initialized, you should identify the user as soon as they provide their email address by calling the identify method after the SDK has initialized.

If you are providing an un-hashed email address, use:

const identityRequest = { 
    userIdentities: { 
        email: 'j.smith@example.com' 
    }
}; 
mParticle.Identity.identify(identityRequest);

If you are providing a hashed email address, use:

const identityRequest = { 
    userIdentities: { 
        other: 'sha256 hashed email goes here' 
    }
}; 
mParticle.Identity.identify(identityRequest);

Setting user attributesDirect link to Setting user attributes

Once you have identified the the current user, you can set descriptive user attributes that will be included with any ad placements or logged events. You can also set user attributes directly when inserting a placement.

To set user attributes, run the following after the SDK has initilaized and you have identified the user:

// To retrieve the current user, call getCurrentUser. This will only succeed if you have identified the user during SDK initialization or by calling the identify method.
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("user-attribute-name", "user-attribute-value");
// Note: all user attributes (including list attributes and tags) must have distinct names.

// Rokt recommends setting as many of the following user attributes as possible:
currentUser.setUserAttribute("firstname", "John"); 
currentUser.setUserAttribute("lastname", "Doe");
// Phone numbers can be formatted either as '1234567890', or '+1 (234) 567-8901'
currentUser.setUserAttribute("mobile", "3125551515");
currentUser.setUserAttribute("age", "33");
currentUser.setUserAttribute("gender", "M");
currentUser.setUserAttribute("city", "Brooklyn");
currentUser.setUserAttribute("state", "NY");
currentUser.setUserAttribute("zip", "123456");
currentUser.setUserAttribute("dob", "yyyymmdd");
currentUser.setUserAttribute("title", "Mr");
currentUser.setUserAttribute("language", "en");
currentUser.setUserAttribute("value", "52.25");
currentUser.setUserAttribute("predictedltv", "136.23"); 

// 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");

Inserting placementsDirect link to Inserting placements

The script used to insert a placement in your site has also been replaced in the new SDK.

Deprecated selectPlacements method:

Previously, to insert a placement you would call selectPlacements after the Rokt SDK launcher script completed:

<script type="module">
  await window.RoktLauncherScriptPromise;

  const launcher = await window.Rokt.createLauncher({
      accountId: "rokt-account-id",
      sandbox: true,
  });

  await launcher.selectPlacements({
      attributes: {
          email: "",
          firstname: "",
          lastname: "",
          confirmationref: "",
          billingzipcode: "",
          amount: "",
          paymenttype: "",
          ccbin: "",
          mobile: "",
          country: "",
          language: "",
          currency: "",
          billingaddress1: "",
          billingaddress2: "",
          age: "",
          gender: "",
          cartItems: JSON.stringify(cartItems),
      },
  });
</script>

This has been replaced with the mParticle.Rokt.selectPlacements method:

New selectPlacements method:

To insert a placement, call the new mParticle.Rokt.selectPlacements after you've initialized the SDK. Similar to the previous section, you can supply a list of attributes to improve the relevance of the content shown to your customer.

const selection = await window.mParticle.Rokt.selectPlacements({
    attributes: {
        "email": "j.smith@example.com", // Customer email address used at checkout
        "firstname": "Jenny",           // Customer first name
        "lastname": "Smith",            // Customer last name
        "confirmationref": "54321",     // Order / confirmation reference number
        "billingzipcode": "90210",      // Billing zip or postcode of customer
        "amount": "",                   // Decimal transaction amount e.g. 300.5
        "paymenttype": "",              // E.g. Gift card | Chase, Visa
        "ccbin": "",                    // Credit card bin e.g. 372888
        "mobile": "",                   // Customer mobile / cell number
        "country": "",                  // ISO Alpha-2 Country Code
        "language": "",                 // ISO 639-1 2 letter lanugage code
        "currency": "",                 // Transaction currency e.g. USD
        "billingaddress1": "",          // Customer address line 1
        "billingaddress2": "",          // Customer address line 2
        "age": "",                      // Customer age
        "gender": "",                   // Customer gender m / f
        "cartItems": JSON.stringify(["item 1", "item 2", "item 3"]), // Stringified cart contents
    
        // You can also pass extra attributes relevant to the transaction here
        // See link below for a full list of attributes
        shippingtype: "Priority Express"
    }
});

Update your Content Security Policy (CSP)Direct link to Update your Content Security Policy (CSP)

If your site uses a Content Security Policy, you need to update your CSP directives to allow the new SDK domains. The new SDK loads resources from apps.rokt-api.com in addition to apps.rokt.com.

Update your CSP to include the following directives:

script-src https://apps.rokt.com https://apps.rokt-api.com https://apps.roktecommerce.com https://sourcemaps-wsdk.roktinternal.com;
frame-src https://apps.rokt.com https://apps.rokt-api.com https://apps.roktecommerce.com;

For more details on Rokt's CSP requirements, see Web Security.

Implement event trackingDirect link to Implement event tracking

The new Rokt SDK makes it easy to collect event and user attributes. To learn how to implement these new tracking methods into your site, see the new Getting Started for Ecommerce or Getting Started for Advertisers guides.

mParticle Apple SDK 9.0 (iOS)Direct link to mParticle Apple SDK 9.0 (iOS)

Type system: MPRokt types → RoktContractsDirect link to Type system: MPRokt types → RoktContracts

Callbacks → onEventDirect link to Callbacks → onEvent

RoktConfig Builder patternDirect link to RoktConfig Builder pattern

Global eventsDirect link to Global events

Other breaking changesDirect link to Other breaking changes

Shoppable Ads: PaymentKit → PaymentExtensionDirect link to Shoppable Ads: PaymentKit → PaymentExtension

React Native SDK+ 3.0 (react-native-mparticle)Direct link to React Native SDK+ 3.0 (react-native-mparticle)

New: Shoppable Ads supportDirect link to New: Shoppable Ads support

iOS Podfile dependencyDirect link to iOS Podfile dependency

Payment extension registrationDirect link to Payment extension registration

New Shoppable Ads eventsDirect link to New Shoppable Ads events

No breaking changes to existing APIsDirect link to No breaking changes to existing APIs

React Native Legacy SDK 5.0 (@rokt/react-native-sdk)Direct link to React Native Legacy SDK 5.0 (@rokt/react-native-sdk)

Breaking: execute() renamed to selectPlacements()Direct link to breaking-execute-renamed-to-selectplacements

New: selectShoppableAds()Direct link to new-selectshoppableads

iOS Podfile dependencyDirect link to iOS Podfile dependency

Payment extension registrationDirect link to Payment extension registration

New Shoppable Ads eventsDirect link to New Shoppable Ads events

Flutter Legacy SDK 5.0 (rokt_sdk)Direct link to Flutter Legacy SDK 5.0 (rokt_sdk)

Breaking: execute() renamed to selectPlacements()Direct link to breaking-execute-renamed-to-selectplacements-1

Removed: callbacks and setLoggingEnabled()Direct link to removed-callbacks-and-setloggingenabled

Event property rename: placementId → identifierDirect link to event-property-rename-placementid--identifier

New: selectShoppableAds() (iOS only)Direct link to new-selectshoppableads-ios-only

iOS Podfile dependencyDirect link to iOS Podfile dependency

Payment extension registrationDirect link to Payment extension registration

New Shoppable Ads eventsDirect link to New Shoppable Ads events

Platform availabilityDirect link to Platform availability

Flutter SDK+ 2.0 (mparticle_flutter_sdk)Direct link to Flutter SDK+ 2.0 (mparticle_flutter_sdk)

iOS deployment target raised to 15.6Direct link to iOS deployment target raised to 15.6

Updated CocoaPods dependenciesDirect link to Updated CocoaPods dependencies

Rokt event channel — new event typesDirect link to Rokt event channel — new event types

New: selectShoppableAds (iOS only)Direct link to new-selectshoppableads-ios-only-1

Payment extension — native-only registrationDirect link to Payment extension — native-only registration

Web SDK Migration GuideDirect link to Web SDK Migration Guide

Initializing the Web SDKDirect link to Initializing the Web SDK

Remove the deprecated launcher.js scriptDirect link to remove-the-deprecated-launcherjs-script

Remove the deprecated snippet.js auto launcherDirect link to remove-the-deprecated-snippetjs-auto-launcher

Insert the new SDK initialization snippetDirect link to Insert the new SDK initialization snippet

New Rokt Web SDK initialization snippetDirect link to New Rokt Web SDK initialization snippet

Rokt API keyDirect link to Rokt API key

First-party domainDirect link to First-party domain

Development modeDirect link to Development mode

User identification on initializationDirect link to User identification on initialization

Identify the userDirect link to Identify the user

Setting user attributesDirect link to Setting user attributes

Inserting placementsDirect link to Inserting placements

Update your Content Security Policy (CSP)Direct link to Update your Content Security Policy (CSP)

Implement event trackingDirect link to Implement event tracking

Breaking: `execute()` renamed to `selectPlacements()`Direct link to breaking-execute-renamed-to-selectplacements

New: `selectShoppableAds()`Direct link to new-selectshoppableads

Breaking: `execute()` renamed to `selectPlacements()`Direct link to breaking-execute-renamed-to-selectplacements-1

Removed: callbacks and `setLoggingEnabled()`Direct link to removed-callbacks-and-setloggingenabled

Event property rename: `placementId` → `identifier`Direct link to event-property-rename-placementid--identifier

New: `selectShoppableAds()` (iOS only)Direct link to new-selectshoppableads-ios-only

New: `selectShoppableAds` (iOS only)Direct link to new-selectshoppableads-ios-only-1

Remove the deprecated `launcher.js` scriptDirect link to remove-the-deprecated-launcherjs-script

Remove the deprecated `snippet.js` auto launcherDirect link to remove-the-deprecated-snippetjs-auto-launcher