Getting Started

With React Native, use a single code base to deploy features to multiple platforms. The mParticle React Native library helps you leverage a single API to deploy your data to hundreds of integrations from your iOS and Android apps.

Android and iOS support methods for custom events, page views, identity, commerce events, and consent.

Requirements: This guide covers mParticle React Native SDK 4.x, which requires React Native 0.76 or later and supports the New Architecture. The iOS deployment target is 15.6 or later. Native SDK versions are defined by your installed wrapper release.

Upgrading an existing app? Follow Upgrade to Version 4 for the iOS dependency changes and the Rokt placeholder API migration.

Installation

Install the library from npm:

$ npm install react-native-mparticle --save

For clients using the react-native-tvos library you must add the force flag to the install code as shown below. This tells the installer to ignore using the core React Native repository and instead use the tvOS-specific library instead.

$ npm install react-native-mparticle --save --force

If any tvOS target in your Podfile uses react-native-mparticle, use the CocoaPods fallback for the entire Podfile. The default Swift Package Manager integration supports iOS only. The minimum tvOS deployment target is 15.6.

Next, copy the key and secret provided for your configured platform input in Data Platform > Setup > Inputs and then follow the OS-specific instructions for the platform you are using below.

Expo

If your app uses Expo, install the package and expo-build-properties:

npx expo install react-native-mparticle expo-build-properties

Configure the bundled config plugin in your app.json. Set the iOS deployment target with expo-build-properties; the mParticle plugin does not set it:

{
  "expo": {
    "plugins": [
      [
        "react-native-mparticle",
        {
          "iosApiKey": "<<<iOS App Key>>>",
          "iosApiSecret": "<<<iOS App Secret>>>",
          "androidApiKey": "<<<Android App Key>>>",
          "androidApiSecret": "<<<Android App Secret>>>"
        }
      ],
      [
        "expo-build-properties",
        {
          "ios": {
            "deploymentTarget": "15.6"
          }
        }
      ]
    ]
  }
}

Then run npx expo prebuild --clean followed by npx expo run:ios or npx expo run:android. The plugin generates the native initialization described below, so bare React Native apps should follow the iOS and Android steps instead.

The plugin uses Swift Package Manager for the iOS mParticle SDK and kits by default. Add these optional settings to the react-native-mparticle plugin options:

For example, add "iosKits": ["mParticle-Rokt"] for standard Rokt placements. See Rokt setup for Shoppable Ads and Android kits.

When Expo regenerates the native projects, a previously generated Package.resolved is lost. With the same wrapper release and configuration, the plugin uses that release’s exact default again. Set iosSdkVersion only when you intentionally want to override it; kits without an explicit version use the core version. The default SPM setup always links the core Swift package, including in apps without kits, so import mParticle_Apple_SDK resolves.

Run npx expo prebuild --clean whenever you change iosDependencyManager in either direction to remove the previous mode’s Podfile settings and package links. With "iosDependencyManager": "cocoapods", also follow the Swift umbrella-pod guidance if you have no iOS kits.

iOS

React Native and react-native-mparticle install with CocoaPods. From version 4.0, pod install links the mParticle core SDK and its kits into your app target as Swift packages by default.

Swift Package Manager (default)

Set your iOS deployment target to 15.6 or later in ios/Podfile, and update any app target or extension pinned to a lower version:

platform :ios, '15.6'

The core SDK is linked automatically. If you use kits, list them by name before the first target block:

# Optional kits, before the first target block
$RNMParticleSPMKits = ['mParticle-Rokt']

By default, Swift Package Manager installs the exact Apple SDK version selected and tested for your installed react-native-mparticle release. Kits without an explicit version use the core SDK version. Leave $RNMParticleSPMCoreVersion unset to use this default; set it before the first target block only when you intentionally want to override it with another compatible exact version.

To check the default for your installed release, read DEFAULT_CORE_VERSION in node_modules/react-native-mparticle/ios/mparticle_spm.rb (source).

Use names from the maintained kit catalog. For a kit outside that catalog, add a hash to $RNMParticleSPMKits with url:, product:, and optionally version::

$RNMParticleSPMKits = [
  { url: 'PACKAGE_REPOSITORY_URL', product: 'PACKAGE_PRODUCT', version: 'EXACT_VERSION' }
]

Replace the placeholders with your kit’s repository URL, exported product name, and exact version. Omit version: to use the core SDK version.

Run this command from ios/:

bundle exec pod install

Installation updates your app’s .xcodeproj, linking the core SDK and configured kits at exact versions. Commit the project change and ios/<App>.xcworkspace/xcshareddata/swiftpm/Package.resolved after resolving packages in Xcode. Running pod install again with the same configuration makes no further changes.

Static libraries (the React Native default), use_frameworks! :linkage => :static, and use_frameworks! :linkage => :dynamic are all supported. No mParticle pre_install hook is needed with SPM.

Do not declare mParticle or Rokt pods alongside this setup. If a pod would install a second copy of the SDK, pod install stops and lists the conflicting pods. Use the upgrade guide to migrate existing dependencies.

On each installation, kits from the catalog that are absent from $RNMParticleSPMKits are unlinked, including kits added manually. Packages from other URLs, including custom kits, must be removed manually in Xcode when no longer needed.

Troubleshooting:

For advanced integrations, the wrapper also supports React Native’s experimental SPM mode. That separate mode installs React Native itself through SPM and is not intended for production use.

CocoaPods (deprecated)

To install the native mParticle SDKs through CocoaPods, set $RNMParticleDisableSPM = true at the top of ios/Podfile, before any target block. This setting applies to the whole Podfile and is required if any tvOS target uses this wrapper:

$RNMParticleDisableSPM = true

This fallback is deprecated. CocoaPods trunk is scheduled to stop accepting new pods and versions on December 2, 2026; existing published versions remain available. A future wrapper release will remove the fallback.

Remove any mParticle or Rokt Swift packages still linked to your app target before building with CocoaPods. pod install warns about leftover packages, which would cause the SDK to be included twice.

For React Native’s default static-library setup, build the Apple SDK and Rokt pods as dynamic frameworks with this hook. Keep any entries needed by your other dependencies:

pre_install do |installer|
  installer.pod_targets.each do |pod|
    if ['mParticle-Apple-SDK', 'mParticle-Apple-SDK-ObjC',
        'mParticle-Apple-SDK-Swift', 'mParticle-Rokt', 'Rokt-Widget',
        'RoktContracts', 'RoktUXHelper', 'DcuiSchema'].include?(pod.name)
      def pod.build_type
        Pod::BuildType.new(:linkage => :dynamic, :packaging => :framework)
      end
    end
  end
end

For standard Rokt placements, declare the kit inside your app target:

pod 'mParticle-Rokt', 'COMPATIBLE_KIT_VERSION'

Replace COMPATIBLE_KIT_VERSION with an exact kit version compatible with your installed wrapper release. Follow the CocoaPods requirements in that release’s README (source). Do not add Rokt-Widget separately. SPM-only kits, including RoktSDKPlus, cannot use this fallback.

Swift apps without kits: This wrapper depends on mParticle-Apple-SDK-ObjC. To use import mParticle_Apple_SDK, add the Swift umbrella pod inside your app target:

pod 'mParticle-Apple-SDK', 'COMPATIBLE_CORE_VERSION'

Replace COMPATIBLE_CORE_VERSION with an exact Apple SDK version satisfying the mParticle-Apple-SDK-ObjC dependency in your installed wrapper’s react-native-mparticle.podspec (source). If the core SDK is already installed, use its resolved version from ios/Podfile.lock.

This also applies to Expo apps with a Swift AppDelegate and no iOS kits. With the CocoaPods fallback, the plugin does not add the umbrella pod; reapply the declaration after every clean prebuild. Objective-C apps can use the ObjC module directly.

Run bundle exec pod install from ios/. If your app uses frameworks, skip the pre_install hook and use either static or dynamic frameworks. To select linkage with an environment variable, your Podfile must read it:

linkage = ENV['USE_FRAMEWORKS']
if linkage != nil
  use_frameworks! :linkage => linkage.to_sym
end

USE_FRAMEWORKS=static bundle exec pod install
# or
USE_FRAMEWORKS=dynamic bundle exec pod install

Initialize the SDK

Initialize the mParticle SDK by calling the startWithOptions method within the application:didFinishLaunchingWithOptions: delegate call. Preferably the location of the initialization method call should be one of the last statements in the application:didFinishLaunchingWithOptions:. The startWithOptions method requires an options argument containing your key and secret and an initial Identity request.

The SDK must be initialized in the application:didFinishLaunchingWithOptions: method. Other parts of the SDK rely on the UIApplicationDidBecomeActiveNotification notification to function properly. Failing to start the SDK as indicated results in errors. Also, don’t use GCD’s dispatch_async to start the SDK.

Import and start the mParticle Apple SDK into Swift or Objective-C.

On React Native 0.77+ with the New Architecture, configure RCTAppDependencyProvider on your React Native delegate before starting mParticle. For an Objective-C AppDelegate, import <ReactAppDependencyProvider/RCTAppDependencyProvider.h> and set self.dependencyProvider = [RCTAppDependencyProvider new];. Swift templates set delegate.dependencyProvider = RCTAppDependencyProvider() after importing ReactAppDependencyProvider. Without it, third-party Fabric components such as RoktLayoutView cannot register. This step does not apply to React Native 0.76.

Swift example

import mParticle_Apple_SDK

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    let mParticleOptions = MParticleOptions(key: "<<<App Key Here>>>", secret: "<<<App Secret Here>>>")

    // Optional - see the Identity page for more information on building this object
    let request = MPIdentityApiRequest.withEmptyUser()
    request.email = "email@example.com"
    mParticleOptions.identifyRequest = request
    mParticleOptions.onIdentifyComplete = { (apiResult, error) in
        print("Identify complete. userId = \(apiResult?.user.userId.stringValue ?? "Null User ID") error = \(error?.localizedDescription ?? "No Error Available")")
    }

    // Optional
    mParticleOptions.onAttributionComplete = { (attributionResult, error) in
        print("Attribution complete. attributionResults = \(String(describing: attributionResult?.linkInfo))")
    }

    // Start the SDK
    MParticle.sharedInstance().start(with: mParticleOptions)

    return true
}

Objective-C example

// Apple SDK 9 ships the Objective-C headers in the mParticle_Apple_SDK_ObjC module.
#if defined(__has_include) && __has_include(<mParticle_Apple_SDK_ObjC/mParticle.h>)
    #import <mParticle_Apple_SDK_ObjC/mParticle.h>
#else
    #import "mParticle.h"
#endif

Then, start the SDK:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    MParticleOptions *mParticleOptions = [MParticleOptions optionsWithKey:@"REPLACE ME" secret:@"REPLACE ME"];

    /* Optional - Please see the Identity page for more information on building this object
    MPIdentityApiRequest *request = [MPIdentityApiRequest requestWithEmptyUser];
    request.email = @"email@example.com";
    mParticleOptions.identifyRequest = request;
    mParticleOptions.onIdentifyComplete = ^(MPIdentityApiResult * _Nullable apiResult, NSError * _Nullable error) {
        NSLog(@"Identify complete. userId = %@ error = %@", apiResult.user.userId, error);
    };
    */

    [[MParticle sharedInstance] startWithOptions:mParticleOptions];

    return YES;
}

See Identity for more information about supplying an MPIdentityApiRequest object during SDK initialization.

Remember to start Metro with:

$ npm start

and build your workspace from Xcode.

Rokt setup

For standard Rokt placements on iOS, set $RNMParticleSPMKits = ['mParticle-Rokt'], or use "iosKits": ["mParticle-Rokt"] in the Expo plugin options.

For Shoppable Ads on iOS, use $RNMParticleSPMKits = ['RoktSDKPlus'], or "iosKits": ["RoktSDKPlus"] with Expo. RoktSDKPlus includes mParticle-Rokt and RoktPaymentExtension, so list only RoktSDKPlus. It is supported only through SPM.

Shoppable Ads also requires native payment-extension registration after mParticle starts and before calling selectShoppableAds. The Expo plugin installs the package but does not generate this registration; reapply it after a clean prebuild. Follow Rokt’s initialization and payment-extension instructions and placement guide.

On Android, apps using MParticle.Rokt.* or RoktLayoutView must add the Rokt kit themselves:

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). The wrapper supplies android-core automatically. With Expo, use "androidKits": ["android-rokt-kit"] instead; the plugin adds the kit dependency.

The Android Rokt kit requires compileSdk 35+ and Android Gradle Plugin 8.6+. Shoppable Ads is supported only on iOS in this release.

Android

1. Use the mParticle key and secret you copied and construct an MParticleOptions object.
2. Call start from the onCreate method of your app’s Application class. It’s crucial that the SDK be started here for proper session management. If you don’t already have an Application class, create it and then specify its fully-qualified name in the <application> tag of your app’s AndroidManifest.xml.

package com.example.myapp;

import android.app.Application;
import com.mparticle.MParticle;
import com.mparticle.MParticleOptions;
import com.mparticle.identity.IdentityApiRequest;

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        // Optional - see the Identity page for more information on building this object
        IdentityApiRequest identifyRequest = IdentityApiRequest.withEmptyUser().build();

        MParticleOptions options = MParticleOptions.builder(this)
            .credentials("REPLACE ME WITH KEY", "REPLACE ME WITH SECRET")
            .logLevel(MParticle.LogLevel.VERBOSE)
            .identify(identifyRequest)
            .build();

        MParticle.start(options);
    }
}

Warning: It’s generally not a good idea to log events in Application.onCreate(). Android may instantiate your Application class for a lot of reasons, in the background, while the user isn’t even using their device.

Usage

After you install and initialize the SDK, you can log events. You can also set, remove, or get user details with User or Identity methods.

Import the mParticle module

Import the module:

import MParticle from 'react-native-mparticle'

Events

Log events:

MParticle.logEvent('Test event', MParticle.EventType.Other, { 'Test key': 'Test value' })

Log commerce events:

const product = new MParticle.Product('Test product for cart', '1234', 19.99)
const transactionAttributes = new MParticle.TransactionAttributes('Test transaction id')
const event = MParticle.CommerceEvent.createProductActionEvent(MParticle.ProductActionType.AddToCart, [product], transactionAttributes)

MParticle.logCommerceEvent(event)

const promotion = new MParticle.Promotion('Test promotion id', 'Test promotion name', 'Test creative', 'Test position')
const event = MParticle.CommerceEvent.createPromotionEvent(MParticle.PromotionActionType.View, [promotion])

MParticle.logCommerceEvent(event)

const product = new MParticle.Product('Test product that was viewed', '5678', 29.99)
const impression = new MParticle.Impression('Test impression list name', [product])
const event = MParticle.CommerceEvent.createImpressionEvent([impression])

MParticle.logCommerceEvent(event)

Log screen events:

MParticle.logScreenEvent('Test screen', { 'Test key': 'Test value' })

Exclude App and Commerce Events from mParticle Server Upload

If you have a high-volume event that you would like to forward to kits but exclude from uploading to mParticle, set a boolean flag per event.

By default, all events upload to the mParticle server unless explicitly set not to.

// Events
var event = new MParticle.Event()
    .setName('Test event')
    .setType(MParticle.EventType.Other)
    .setInfo({ 'Test key': 'Test value' })
    .setShouldUploadEvent(false) // Set false to prevent uploading, true or omit to upload
MParticle.logMPEvent(event)

// Commerce Events
const product = new MParticle.Product('Test product for cart', '1234', 19.99)
const transactionAttributes = new MParticle.TransactionAttributes('Test transaction id')
var commerceEvent = MParticle.CommerceEvent.createProductActionEvent(MParticle.ProductActionType.AddToCart, [product], transactionAttributes)
commerceEvent.setShouldUploadEvent(false) // Set false to prevent uploading, true or omit to upload
const customFlags = {
  'GA4.CommerceEventType': 'add_shipping_info',
  'GA4.ShippingTier': 'overnight'
}
commerceEvent.customFlags = customFlags
MParticle.logCommerceEvent(commerceEvent)

User

User attributes and tags are set on the current User, which you obtain from MParticle.Identity.getCurrentUser:

MParticle.Identity.getCurrentUser((currentUser) => {
    // Set a user attribute
    currentUser.setUserAttribute('Test key', 'Test value')

    // Set a reserved user attribute
    currentUser.setUserAttribute(MParticle.UserAttributeType.FirstName, 'Test first name')

    // Set an attribute list
    currentUser.setUserAttributeArray('Test key', ['Test value 1', 'Test value 2'])

    // Set a tag
    currentUser.setUserTag('Test key')

    // Remove an attribute
    currentUser.removeUserAttribute('Test key')
})

IdentityRequest

var request = new MParticle.IdentityRequest()

Set a user identity:

var request = new MParticle.IdentityRequest();
request.setUserIdentity('example@example.com', MParticle.UserIdentityType.Email);

To copy data from a previous user to a new user, build an AliasRequest and pass it to MParticle.Identity.aliasUsers after the identity change completes:

var aliasRequest = new MParticle.AliasRequest()
    .sourceMpid(previousMpid)
    .destinationMpid(newMpid);

MParticle.Identity.aliasUsers(aliasRequest, (success) => {
    console.debug(success);
});

Identity

MParticle.Identity.getCurrentUser((currentUser) => {
    console.debug(currentUser.userId);
});

var request = new MParticle.IdentityRequest();

MParticle.Identity.identify(request, (error, userId) => {
    if (error) {
        console.debug(error); //error is an MParticleError
    } else {
        console.debug(userId);
    }
});

var request = new MParticle.IdentityRequest();
request.email = 'test email';

MParticle.Identity.login(request, (error, userId) => {
    if (error) {
        console.debug(error); //error is an MParticleError
    } else {
        console.debug(userId);
    }
});

var request = new MParticle.IdentityRequest();

MParticle.Identity.logout(request, (error, userId) => {
    if (error) {
        console.debug(error);
    } else {
        console.debug(userId);
    }
});

var request = new MParticle.IdentityRequest();
request.email = 'test email 2';

MParticle.Identity.modify(request, (error, userId) => {
    if (error) {
        console.debug(error); //error is an MParticleError
    } else {
        console.debug(userId);
    }
});

Attribution

MParticle.getAttributions((attributions) => {
    console.debug(attributions);
});

In order to listen for attributions asynchronously, set the proper field in MParticleOptions as shown in the previous Android or the iOS SDK installation examples.

Kits

Check if a kit is active:

MParticle.isKitActive(kitId, (isKitActive) => {
    console.debug(isKitActive);
});

Check and set the SDK opt-out status:

MParticle.getOptOut((isOptedOut) => {
    MParticle.setOptOut(!isOptedOut);
});

Push registration

The method MParticle.logPushRegistration() accepts two parameters. For Android, provide both pushToken and senderId. For iOS, provide the push token in the first parameter, and simply pass null for the second parameter.

Android

MParticle.logPushRegistration(pushToken, senderId);

iOS

MParticle.logPushRegistration(pushToken, '');

GDPR consent

Add GDPR consent:

var gdprConsent = new MParticle.GDPRConsent()
    .setConsented(true)
    .setDocument("the document")
    .setTimestamp(new Date().getTime())  // optional, native SDK will automatically set current timestamp if omitted
    .setLocation("the location")
    .setHardwareId("the hardwareId");

MParticle.addGDPRConsentState(gdprConsent, "the purpose");

Remove GDPR consent:

MParticle.removeGDPRConsentStateWithPurpose("the purpose");

CCPA consent

Add CCPA consent:

var ccpaConsent = new MParticle.CCPAConsent()
    .setConsented(true)
    .setDocument("the document")
    .setTimestamp(new Date().getTime())  // optional, native SDK will automatically set current timestamp if omitted
    .setLocation("the location")
    .setHardwareId("the hardwareId");

MParticle.setCCPAConsentState(ccpaConsent);

Remove CCPA consent:

MParticle.removeCCPAConsentState();

License

Apache 2.0