SDK Migration Guides
This page explains how to update existing Rokt SDK and SDK+ integrations across the version transitions, package changes, and API replacements listed below.
- mParticle Apple SDK 9.0 (iOS)
- React Native SDK+ 4.0
- React Native SDK+ 3.0
- React Native Legacy SDK 5.0
- Flutter SDK+ 2.3
- Flutter SDK+ 2.0
- Flutter Legacy SDK 5.0
- Cordova SDK+ 5.0
- Web SDK Migration Guide
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)")
}
}
Other breaking changesDirect link to Other breaking changes
- AppDelegate proxy: The SDK no longer automatically intercepts
UIApplicationDelegatemessages. You must now explicitly forward push notification and URL/user-activity events to the SDK. - URL and user activity: Prefer the
UIScenelifecycle and the SDK'shandleURLContext:andhandleUserActivity:methods. - Direct routing: API requests now use regional endpoints by default based on your API key prefix; ensure App Transport Security allows
*.mparticle.com. - Database migration: Upgrading from SDK versions before 8.27.0 to 9.x starts with a fresh local database; pending events are not migrated.
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: RoktPaymentExtension |
RoktPaymentKit(applePayMerchantId:) | RoktPaymentExtension(applePayMerchantId:urlScheme:) |
Rokt.registerPaymentKit(kit) | Rokt.registerPaymentExtension(ext, config:) |
Rokt.execute(...) for shoppable placements | Rokt.selectShoppableAds(...) |
| Stripe key in kit only | Direct SDK: stripeKey in config dict. SDK+: stripePublishableKey in mParticle Rokt kit settings |
See the Shoppable Ads iOS Integration guide for the updated API.
RoktStripePaymentExtension → RoktPaymentExtensionDirect link to RoktStripePaymentExtension → RoktPaymentExtension
If you integrated against the interim RoktStripePaymentExtension package, update as follows:
| Old | New |
|---|---|
Package URL: https://github.com/ROKT/rokt-stripe-payment-extension-ios | https://github.com/ROKT/rokt-payment-extension-ios (old URL redirects) |
Pod: RoktStripePaymentExtension | RoktPaymentExtension '~> 2.0' |
import RoktStripePaymentExtension | import RoktPaymentExtension |
RoktStripePaymentExtension(...) | RoktPaymentExtension(...) |
RoktPaymentExtension 2.0 breaking changesDirect link to RoktPaymentExtension 2.0 breaking changes
returnURLremoved — pass a bareurlSchemeinstead (for example"myapp"). The extension builds the full Afterpay / Clearpay return URL internally. Register the same scheme underCFBundleURLTypesinInfo.plist.handleURLCallbackrequired — forward redirect URLs from yourSceneDelegate/AppDelegatetoMParticle.sharedInstance().rokt.handleURLCallback(with:)(SDK+) orRokt.handleURLCallback(with:)(Direct SDK). Required for Afterpay / Clearpay and built-in PayPal on iOS.
Shoppable Ads minimum versions (iOS)Direct link to Shoppable Ads minimum versions (iOS)
| Capability | SDK+ (RoktSDKPlus) | Direct (Rokt-Widget) |
|---|---|---|
| Shoppable Ads (base) | 9.0+ | 5.0+ |
| Afterpay / Clearpay | 9.1+ | 5.1+ |
| PayPal, card forwarding (built-in) | 9.2+ | 5.2+ |
Also requires RoktPaymentExtension '~> 2.0' and RoktContracts '~> 2.0' when pinned directly in your Podfile.
For mParticle 9.0.x → 9.1.0 Rokt dependency bumps (Afterpay, handleURLCallback, package rename), see Migrating from 9.0.x to 9.1.0.
For the full official migration guide, see Migrating from versions < 9.0.0.
React Native SDK+ 4.0 (react-native-mparticle)Direct link to React Native SDK+ 4.0 (react-native-mparticle)
If you are upgrading react-native-mparticle from 3.x to 4.0 in your React Native app, the following changes apply. Both are breaking. See the React Native Integration Guide for the full setup.
Embedded placeholders: names onlyDirect link to Embedded placeholders: names only
MParticle.Rokt.selectPlacements now accepts only an array of RoktLayoutView placeholder names. The map of placeholder names to findNodeHandle node handles has been removed. TypeScript reports a map at build time. A map passed from plain JavaScript logs an error, and the placement is requested without embedded views. Version 3.4.0 and later 3.x releases accept both forms, so you can switch to names before you upgrade.
Before (3.x):
import { findNodeHandle } from 'react-native';
const placeholderRef = useRef(null);
const onPlaceholderLayout = () => {
MParticle.Rokt.selectPlacements('RoktExperience', attributes, {
RoktEmbedded1: findNodeHandle(placeholderRef.current),
});
};
return (
<View onLayout={onPlaceholderLayout}>
<RoktLayoutView ref={placeholderRef} placeholderName="RoktEmbedded1" />
</View>
);
After (3.4.0 and later, required from 4.0):
useEffect(() => {
MParticle.Rokt.selectPlacements('RoktExperience', attributes, ['RoktEmbedded1']);
}, []);
return <RoktLayoutView placeholderName="RoktEmbedded1" />;
To migrate:
- Remove the
ref, thefindNodeHandleimport, and anyonLayouthandler or timer used to delay the call. - Pass an array of placeholder names. Each name must match the
placeholderNameof aRoktLayoutView. - For overlay placements, pass
undefinedinstead of an empty object ({}) as theplaceholdersargument.
Check these behaviors after you migrate:
- An unmounted placeholder delays the request by up to 2 seconds. The SDK+ waits for each named view, then calls Rokt with the views it has. A misspelled or never-rendered name delays the request by 2 seconds and logs
Cannot resolve placeholder. - A waiting call can end in
PlacementFailure. IfMParticle.Rokt.close()runs, or a newer call with the same identifier replaces it, before its placeholders mount, the waiting call emits aPlacementFailureevent.
iOS: SDKs from Swift Package ManagerDirect link to iOS: SDKs from Swift Package Manager
React Native and react-native-mparticle still install with CocoaPods, but pod install now takes the mParticle SDK and its kits, including the Rokt SDK+, from Swift Package Manager and links them into your app target. An app that still declares mParticle or Rokt pods fails pod install until it moves them.
To migrate a bare React Native app:
- In
ios/Podfile, remove every mParticle and Rokt pod you declared, such aspod 'RoktSDKPlus',pod 'mParticle-Rokt',pod 'mParticle-Apple-SDK', orpod 'Rokt-Widget'. - Remove the mParticle, Rokt,
RoktContracts,RoktUXHelper, andDcuiSchemanames from anypre_installhook that builds them as dynamic frameworks. If the hook lists nothing else, delete it. - If you added mParticle or Rokt Swift packages to your app target by hand, remove them in Xcode.
pod installadds them back, pinned to exact versions. - Above the first
targetblock inios/Podfile, list the Rokt SDK+:$RNMParticleSPMKits = ['RoktSDKPlus']. - Run
bundle exec pod install. It prints each Swift package it links, and fails with a list of pods to remove if any would add a second copy of the SDK. - Build the app, and commit the
.xcodeprojchange andPackage.resolved.
A Swift AppDelegate needs no change: import mParticle_Apple_SDK resolves from the Swift package.
Expo apps take the SDKs from Swift Package Manager by default. Run npx expo prebuild --clean after you upgrade.
To stay on CocoaPods for now, add $RNMParticleDisableSPM = true at the top of ios/Podfile, before any target block, and keep your pods (Expo: "iosDependencyManager": "cocoapods"). This option is deprecated, and CocoaPods trunk becomes read-only on December 2, 2026. A Podfile with a tvOS target that uses react-native-mparticle must use it.
AndroidDirect link to Android
No code changes are required on Android. Declare com.mparticle:android-core and com.mparticle:android-rokt-kit in your app at the same version, at or above the version react-native-mparticle builds against, listed in its android/build.gradle.
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.
Shoppable Ads in React Native are currently supported on iOS only.
iOS Podfile dependencyDirect link to iOS Podfile dependency
If using Shoppable Ads, add Rokt SDK+ to your ios/Podfile (includes RoktPaymentExtension):
pod 'RoktSDKPlus', '~> 9.2'
Payment extension registrationDirect link to Payment extension registration
A new registerPaymentExtension call is required in your native iOS code (AppDelegate) before calling selectShoppableAds. Configure stripePublishableKey in your mParticle Rokt kit settings — the kit forwards it to Rokt automatically. In code, provide only the Apple Pay merchant ID:
import mParticle_Apple_SDK
import RoktPaymentExtension
if let paymentExt = RoktPaymentExtension(applePayMerchantId: "merchant.com.yourapp.rokt") {
MParticle.sharedInstance().rokt.registerPaymentExtension(paymentExt)
}
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.
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 payment extension to your ios/Podfile. Pair with Rokt-Widget '~> 5.2' (transitive via @rokt/react-native-sdk):
pod 'RoktPaymentExtension', '~> 2.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 RoktPaymentExtension
if let paymentExtension = RoktPaymentExtension(applePayMerchantId: "merchant.com.rokt.sample") {
Rokt.registerPaymentExtension(paymentExtension, 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:
onLoadonUnLoadonShouldShowLoadingIndicatoronShouldHideLoadingIndicator
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 → identifierDirect 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.
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 'RoktPaymentExtension', '~> 2.0'
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 RoktPaymentExtension
import rokt_sdk
SwiftRoktSdkPlugin.paymentExtensionFactory = { type, config in
switch type {
case "stripe":
guard let merchantId = config["applePayMerchantId"] else { return nil }
return RoktPaymentExtension(
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.3 (mparticle_flutter_sdk)Direct link to Flutter SDK+ 2.3 (mparticle_flutter_sdk)
From Flutter 3.44, Flutter adds iOS plugins with Swift Package Manager by default, and mparticle_flutter_sdk brings in the mParticle SDK that way. If your app still declares mParticle or Rokt pods, it links a second copy of the SDK. The app still builds, but the Rokt kit registers with the wrong copy. Version 2.3 doesn't change the Dart API; upgrade to it before you move, so the plugin warns you if a second copy remains. See the Flutter Integration Guide for the full setup.
iOS: move the Rokt SDK+ to Swift Package ManagerDirect link to iOS: move the Rokt SDK+ to Swift Package Manager
- Use Flutter 3.44 or later, or Flutter 3.41 or later with
flutter config --enable-swift-package-manager. - In
ios/Podfile, remove every mParticle and Rokt pod you declared, such aspod 'RoktSDKPlus',pod 'mParticle-Rokt', orpod 'mParticle-Apple-SDK'. If nothing else is left in the Podfile, runpod deintegratein theiosdirectory, deletePodfileandPodfile.lock, and remove thePods-Runnerincludes fromios/Flutter/Debug.xcconfigandios/Flutter/Release.xcconfig. Otherwise, runpod install. - In Xcode, add the
RoktSDKPlusproduct fromhttps://github.com/ROKT/rokt-sdk-plus-iosto the Runner target, as described in the Flutter Integration Guide. - Run a debug build once and check the console. If
[mParticle] The mParticle SDK is loaded more than onceappears, a pod still brings in the SDK. - Commit the Xcode project change and
ios/Runner.xcworkspace/xcshareddata/swiftpm/Package.resolved.
A Swift AppDelegate needs no change: import mParticle_Apple_SDK resolves from the Swift package.
To stay on CocoaPods for now, add enable-swift-package-manager: false under flutter: config: in your app's pubspec.yaml and keep your pods. Also replace the post_install block in ios/Podfile with the one in the Flutter Integration Guide, which raises pod deployment targets below 15.6. This option is deprecated: CocoaPods trunk becomes read-only on December 2, 2026, and Flutter plans to remove the option to turn off Swift Package Manager.
iOS: Rokt calls without the Rokt kitDirect link to iOS: Rokt calls without the Rokt kit
From 2.3, Rokt calls on iOS return an error (PlatformException with Rokt is unavailable) when the Rokt kit isn't in the app, as they already did on Android. Before 2.3 they reported success and did nothing.
AndroidDirect link to Android
No code changes are required on Android. Declare com.mparticle:android-core and com.mparticle:android-rokt-kit in your app at the same version, at or above the version mparticle_flutter_sdk builds against, listed in its android/build.gradle.
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— setMinimumOSVersionto15.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 payment extension (RoktPaymentExtension) 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:). Configure stripePublishableKey in your mParticle Rokt kit settings — the kit forwards it to Rokt automatically:
import mParticle_Apple_SDK
import RoktPaymentExtension
if let paymentExt = RoktPaymentExtension(applePayMerchantId: "merchant.com.yourapp.rokt") {
MParticle.sharedInstance().rokt.registerPaymentExtension(paymentExt)
}
Cordova SDK+ 5.0 (cordova-plugin-mparticle)Direct link to Cordova SDK+ 5.0 (cordova-plugin-mparticle)
If you are upgrading the mParticle Cordova plugins (@mparticle/cordova-sdk, @mparticle/cordova-rokt-kit, and @mparticle/cordova-rokt-payment-extension) from 4.x to 5.0, the following changes apply. The breaking changes are on iOS. See the Cordova Integration Guide for the full setup.
iOS: SDKs from Swift Package ManagerDirect link to iOS: SDKs from Swift Package Manager
The three plugins are now Swift packages. The mParticle Apple SDK, the Rokt kit, and the Rokt payment extension come from Swift Package Manager instead of CocoaPods, and no Podfile is generated. The native version ranges are the same as the 4.x pods:
| Plugin | 4.x CocoaPod | 5.0 Swift package |
|---|---|---|
@mparticle/cordova-sdk | mParticle-Apple-SDK ~> 9.3 | mparticle-apple-sdk, 9.3.0 up to 10.0.0 |
@mparticle/cordova-rokt-kit | mParticle-Rokt ~> 9.3 | mp-apple-integration-rokt, 9.3.0 up to 10.0.0 |
@mparticle/cordova-rokt-payment-extension | RoktPaymentExtension ~> 2.0 | rokt-payment-extension-ios, 2.0.0 up to 3.0.0 |
To migrate:
-
Move to Cordova CLI 12 or later and cordova-ios 8. cordova-ios 8 needs Node.js 20.17 or later in the 20.x line, or 22.9 or later, and Xcode 15 or later.
-
In
config.xml, set the iOS deployment target to 15.0 or later. Set it before you add the platform in step 4.<platform name="ios">
<preference name="deployment-target" value="15.0" />
</platform> -
Upgrade all three plugins to 5.x together, and remove any mParticle or Rokt pods you added yourself, for example in a custom plugin's
<podspec>. A leftover pod adds a second copy of the mParticle SDK: the app builds, then fails at runtime. -
Re-create the iOS platform. cordova-ios 8 names the Xcode project and target
App(platforms/ios/App.xcodeproj) instead of your app's name, so update any hooks or scripts that find them by name.cordova platform rm ios
cordova platform add ios@8 -
Move the SDK+ initialization into the Swift
AppDelegate.swiftthat cordova-ios 8 generates, and import the SDK withimport mParticle_Apple_SDK. See Initialize the Rokt SDK+ for the code. Keep your copy outsideplatforms/and copy it in with anafter_preparehook. -
If you use the payment extension, delete the Swift shim (
RoktPaymentSetup.swiftin the 4.x example app) and its bridging header, and register the extension directly inAppDelegate.swift, after starting the SDK+:import RoktPaymentExtension
if let paymentExtension = RoktPaymentExtension(
applePayMerchantId: "merchant.com.yourapp.rokt", // omit if not offering Apple Pay
urlScheme: "myapp" // omit if not offering Afterpay / Clearpay
) {
MParticle.sharedInstance().rokt.registerPaymentExtension(paymentExtension)
}If you pass
urlScheme, register it underCFBundleURLSchemesin your app'sInfo.plist, or the initializer returnsnil. -
If you forward payment redirect URLs to Rokt in
application:openURL:options:, move that code to aSceneDelegateoverride. cordova-ios 8 apps use scenes, so the app delegate no longer receives URLs. See Handle redirect-based payment callbacks in the plugin README. -
Build and run once.
platforms/iosshould contain noPodfile, and with verbose logging the log showsIncluded kits: {Rokt}.
cordova-ios 8 links only the Swift packages that plugins declare, so a kit pod you added another way is no longer installed. To keep another mParticle kit, wrap its Swift package in a small local plugin, as described in Other mParticle kits.
Capacitor reads a Cordova plugin's Package.swift from Capacitor 8.3.2, in apps that use Swift Package Manager. Capacitor apps that use CocoaPods get no iOS code from 5.0 and should stay on 4.x.
To stay on CocoaPods for now, keep cordova-ios 7 and pin the 4.x plugins, for example cordova plugin add @mparticle/cordova-sdk@4. CocoaPods trunk becomes read-only on December 2, 2026, so 4.x stays on the last mParticle SDK released to CocoaPods.
AndroidDirect link to Android
No code changes are required on Android, but 5.0 requires Cordova CLI 12 or later on every platform.
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.
For the maintained initialization instructions and configuration options, see Initialize the Rokt SDK+.
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";
// 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(i){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=3;window.mParticle.ready=function(e){window.mParticle.config.rq.push(e)};var e=["endSession","logError","logBaseEvent","logEvent","logForm","logLink","logPageView","setSessionAttribute","setAppName","setAppVersion","setOptOut","setPosition","startNewSession","startTrackingLocation","stopTrackingLocation"];var t=["setCurrencyCode"];var n=["identify","login","logout","modify","search"];var o=["selectPlacements","hashAttributes","hashSha256","setExtensionData","use","getVersion","terminate","onShoppableAdsReady"];e.forEach(function(e){window.mParticle[e]=r(e)});t.forEach(function(e){window.mParticle.eCommerce[e]=r(e,"eCommerce")});n.forEach(function(e){window.mParticle.Identity[e]=r(e,"Identity")});o.forEach(function(e){window.mParticle.Rokt[e]=r(e,"Rokt")});function r(t,n){return function(){if(n){t=n+"."+t}var e=Array.prototype.slice.call(arguments);e.unshift(t);window.mParticle.config.rq.push(e)}}var a=window.mParticle.config,c=a.isDevelopmentMode?1:0,s="?env="+c,w=a.dataPlan;if(w){var l=w.planId,m=w.planVersion;if(l){if(m&&(m<1||m>1e3)){m=null}s+="&plan_id="+l+(m?"&plan_version="+m:"")}}var d=a.versions;var p=[];if(d){Object.keys(d).forEach(function(e){p.push(e+"="+d[e])})}var f=document.createElement("script");f.type="text/javascript";f.async=true;window.ROKT_DOMAIN=ROKT_DOMAIN||"https://apps.rokt-api.com";window.mParticle.config.domain=window.ROKT_DOMAIN.split("//")[1];f.src=window.ROKT_DOMAIN+"/js/v3/"+i+"/app.js"+s+"&"+p.join("&");f.onerror=function(){var e=["https://apps.","rokt","ecommerce",".com"].join("");window.ROKT_DOMAIN=e;window.mParticle.config.domain=e.split("//")[1];var t=document.createElement("script");t.type="text/javascript";t.async=true;t.src=e+"/js/v3/"+i+"/app.js"+s+"&"+p.join("&");var n=document.getElementsByTagName("script")[0];n.parentNode.insertBefore(t,n)};var u=document.getElementsByTagName("script")[0];u.parentNode.insertBefore(f,u)})(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.
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 ROKT_DOMAIN in your initialization snippet with your own subdomain:
const ROKT_DOMAIN = "https://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 'email_sha256' instead of `email`.
email_sha256: '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: {
email_sha256: 'sha256 hashed email goes here'
}
};
mParticle.Identity.identify(identityRequest);
Setting user attributesDirect link to Setting user attributes
Once you have identified 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 initialized 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. For maintained examples covering each placement position, see Show a Placement.
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",
// Pass cart items as a real array so the fields remain typed.
cartItems: [
{
cartitemid: "SKU-001",
productsku: "SKU-001",
productname: "Trail Runner v3",
itemprice: 129.95,
quantity: 1
}
]
}
});
});
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;
connect-src 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.