Upgrade to Version 4

Version 4 of react-native-mparticle introduces two breaking changes: the native iOS mParticle SDK and kits come from Swift Package Manager (SPM) by default, and MParticle.Rokt.selectPlacements accepts only an array of placeholder names for embedded placements.

This guide covers upgrades from 3.x. For a new integration, follow Getting Started. If you are upgrading from 2.x or earlier, also follow Migrating from versions below 3.0.0 for the underlying native SDK changes.

Update the wrapper package, then follow the platform steps below before building:

npm install react-native-mparticle@^4.0.0

With Expo, use npx expo install react-native-mparticle@^4.0.0 instead.

iOS dependencies

React Native and the wrapper still install through CocoaPods. Running pod install now links the mParticle core SDK and configured kits into your app target as Swift packages pinned to exact versions. The default Apple SDK version is selected and tested for your installed wrapper release. Kits without an explicit version use the core SDK version.

An app without kits or manually declared native SDK dependencies needs no dependency configuration change. For apps with kit pods or manually linked packages:

1. Remove every explicit mParticle and Rokt pod declaration from ios/Podfile, including mParticle-Apple-SDK, its split ObjC/Swift pods, mParticle-Rokt, Rokt-Widget, RoktSDKPlus, and any directly declared RoktContracts, RoktUXHelper, DcuiSchema, or RoktPaymentExtension pods.
2. Remove those names from any pre_install hook that builds them as dynamic frameworks. Delete the hook if it has no other entries; keep configuration needed by other dependencies.
3. Remove mParticle or Rokt Swift packages you added by hand from your app target’s Frameworks, Libraries, and Embedded Content and the project’s Package Dependencies in Xcode. Installation adds the configured packages back.

4. Set platform :ios, '15.6' or later, and list your kits before the first target block. For standard Rokt placements:

   platform :ios, '15.6'
   $RNMParticleSPMKits = ['mParticle-Rokt']

   For iOS Shoppable Ads, use ['RoktSDKPlus'] instead. It includes mParticle-Rokt and RoktPaymentExtension; do not list both kits. For other kits and optional exact version overrides, see SPM configuration.

5. Run bundle exec pod install from ios/. If a pod would install a second copy of the SDK, installation stops and lists the pods to remove.
6. Resolve packages in Xcode, build and launch a Debug build to check for duplicate-SDK errors, and commit the .xcodeproj change and ios/<App>.xcworkspace/xcshareddata/swiftpm/Package.resolved.

The default static-library setup and both use_frameworks! linkages are supported without a mParticle pre_install hook. Swift initialization continues using import mParticle_Apple_SDK.

On each pod install, kits from the maintained catalog that are absent from $RNMParticleSPMKits are unlinked. Remove packages from custom URLs manually in Xcode when you stop using them.

Expo

Keep your iosKits configuration: the plugin maps recognized names to Swift packages by default. Use iosSpmKits for kits outside the maintained catalog.

Set the iOS deployment target to 15.6 or later through expo-build-properties; the mParticle plugin does not set it. Clean prebuilds regenerate the native project and its package lockfile, but the same wrapper release and configuration select the same exact core SDK version. Set iosSdkVersion only for an intentional override. Kits without an explicit version use the core version. See the Expo setup for the configuration example.

Run npx expo prebuild --clean, then npx expo run:ios. Also run a clean prebuild whenever you switch iosDependencyManager between "spm" and "cocoapods".

For Shoppable Ads, use "iosKits": ["RoktSDKPlus"]. After prebuild, add native payment-extension registration following the Rokt setup instructions, and reapply it after regenerating native projects.

CocoaPods fallback and tvOS

To retain native CocoaPods dependencies temporarily, set $RNMParticleDisableSPM = true before the first Podfile target block and retain your kit pods. In Expo, set "iosDependencyManager": "cocoapods".

If any tvOS target in the Podfile uses this wrapper, the whole Podfile must use this fallback. The minimum tvOS deployment target is 15.6. The default SPM integration supports iOS only.

Remove leftover mParticle/Rokt Swift packages in Xcode when switching to CocoaPods. Keep the required framework-linking configuration and, for Swift apps without kits, the umbrella-pod declaration described in CocoaPods setup.

This fallback is deprecated. CocoaPods trunk is scheduled to stop accepting new pods and versions on December 2, 2026; existing published versions remain available. SPM-only kits such as RoktSDKPlus cannot use the fallback.

Rokt embedded placeholders

MParticle.Rokt.selectPlacements now accepts placeholders?: string[]. Each entry must match the placeholderName of a RoktLayoutView. The previous map of placeholder names to findNodeHandle node handles has been removed on both iOS and Android. Version 3.4.0 supports both forms, so you can migrate to names before upgrading to 4.x.

Before, with a node-handle map:

import React, { useRef } from 'react';
import { findNodeHandle, View } from 'react-native';
import MParticle from 'react-native-mparticle';

function EmbeddedPlacement({ email, firstname }) {
  const placeholderRef = useRef(null);

  const onPlaceholderLayout = () => {
    const attributes = { email, firstname };
    MParticle.Rokt.selectPlacements('RoktExperience', attributes, {
      Location1: findNodeHandle(placeholderRef.current),
    });
  };

  return (
    <View onLayout={onPlaceholderLayout}>
      <MParticle.RoktLayoutView ref={placeholderRef} placeholderName="Location1" />
    </View>
  );
}

After, with placeholder names:

import React, { useEffect } from 'react';
import MParticle from 'react-native-mparticle';

function EmbeddedPlacement({ email, firstname }) {
  useEffect(() => {
    const attributes = { email, firstname };
    MParticle.Rokt.selectPlacements('RoktExperience', attributes, ['Location1']);
  }, [email, firstname]);

  return <MParticle.RoktLayoutView placeholderName="Location1" />;
}

This example selects placements on mount and when the email or firstname string changes. Build the attributes object inside the effect and include each value it uses in the dependency list. If you instead depend on an attributes object passed by a parent, keep that object referentially stable (for example, with useMemo) so unrelated renders do not send another placement request.

Remove the ref, findNodeHandle import, and any onLayout handler or timer used to wait for the view to mount. The named view can mount after the request starts.

For overlays, omit the placeholders argument. If you pass a configuration as the fourth argument, use undefined for placeholders:

MParticle.Rokt.selectPlacements('RoktOverlay', attributes);

const config = MParticle.Rokt.createRoktConfig('system');
MParticle.Rokt.selectPlacements('RoktOverlay', attributes, undefined, config);

TypeScript rejects the old map. If plain JavaScript passes a map, the SDK logs an error and sends the request without embedded views. An empty object ({}) is also a map; use an omitted argument or undefined for overlays.

Check these behaviors after migration:

• A placeholder that has not mounted delays the request by up to 2 seconds. A misspelled or never-rendered name logs Cannot resolve placeholder; the request proceeds with the views available when the wait ends.
• If MParticle.Rokt.close() runs, or a newer call with the same identifier supersedes a pending request before its placeholders mount, the waiting call emits PlacementFailure.

Follow the Rokt placement guide for complete placement and event-handling examples.

Android

Native Android initialization continues as before. The wrapper supplies its required android-core dependency automatically. Apps using MParticle.Rokt.* or RoktLayoutView must also declare the matching Rokt kit, which is not bundled by the wrapper:

implementation 'com.mparticle:android-rokt-kit:COMPATIBLE_VERSION_OR_RANGE'

Replace COMPATIBLE_VERSION_OR_RANGE with the android-rokt-kit version or range declared in node_modules/react-native-mparticle/android/build.gradle for your installed wrapper release (source). With Expo, use "androidKits": ["android-rokt-kit"] in the plugin options; the plugin adds the kit dependency.

The Rokt kit requires compileSdk 35+ and Android Gradle Plugin 8.6+. Apply the placeholder migration on Android as well. Shoppable Ads remains iOS only.