react-native-mparticle
React Native allows developers to use a single code base to deploy features to multiple platforms. With the mParticle React Native library, you can leverage a single API to deploy your data to hundreds of integrations from your iOS and Android apps.
Supported Features
Method | Android | iOS |
---|---|---|
Custom Events | ||
Page Views | ||
Identity | ||
eCommerce | ||
Consent |
Installation
- Download and install the mParticle React Native library from npm:
$ npm install react-native-mparticle --save
- Install the native dependencies. You can use
rnpm
(now part ofreact-native
core vialink
) to add native dependencies automatically:
$ react-native link
iOS
- Copy your mParticle key and secret from your app's dashboard.
- Install the SDK using CocoaPods:
$ # Update your Podfile to depend on 'mParticle-Apple-SDK' version 7.2.0 or later
$ pod install
The mParticle SDK is initialized 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.
Note that you must initialize the SDK in the
application:didFinishLaunchingWithOptions:
method. Other parts of the SDK rely on theUIApplicationDidBecomeActiveNotification
notification to function properly. Failing to start the SDK as indicated will impair it. Also, please do not use GCD'sdispatch_async
to start the SDK.
For more help, see the iOS set up docs.
- Import and start the mParticle Apple SDK into Swift or Objective-C.
Swift Example
import mParticle_Apple_SDK
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
//override point for customization after application launch.
let mParticleOptions = MParticleOptions(key: "<<<App Key Here>>>", secret: "<<<App Secret Here>>>")
//optional- Please see the Identity page for more information on building this object
let request = MPIdentityApiRequest()
request.email = "email@example.com"
mParticleOptions.identifyRequest = request
//optional
mParticleOptions.onIdentifyComplete = { (apiResult, error) in
NSLog("Identify complete. userId = %@ error = %@", apiResult?.user.userId.stringValue ?? "Null User ID", error?.localizedDescription ?? "No Error Available")
}
//optional
mParticleOptions.onAttributionComplete = { (attributionResult, error) in
NSLog(@"Attribution Complete. attributionResults = %@", attributionResult.linkInfo)
}
MParticle.sharedInstance().start(with: mParticleOptions)
return true
}
Objective-C Example
With recent changes in Swift support for static libraries and React Native's preference for the traditional CocoaPods and static libraries delivery mechanism, we reccomend against setting use_frameworks!
in your Podfile.
Your import statement can be either of these:
#import <mParticle-Apple-SDK/mParticle.h>
#import "mParticle.h"
Next, you'll need to 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;
//optional
mParticleOptions.onIdentifyComplete = ^(MPIdentityApiResult * _Nullable apiResult, NSError * _Nullable error) {
NSLog(@"Identify complete. userId = %@ error = %@", apiResult.user.userId, error);
};
//optional
mParticleOptions.onAttributionComplete(MPAttributionResult * _Nullable attributionResult, NSError * _Nullable error) {
NSLog(@"Attribution Complete. attributionResults = %@", attributionResult.linkInfo)
}
[[MParticle sharedInstance] startWithOptions:mParticleOptions];
return YES;
}
See Identity for more information on supplying an MPIdentityApiRequest
object during SDK initialization.
Android
-
Copy your mParticle key and secret from your workspace's dashboard and construct an
MParticleOptions
object. -
Call
start
from theonCreate
method of your app'sApplication
class. It's crucial that the SDK be started here for proper session management. If you don't already have anApplication
class, create it and then specify its fully-qualified name in the<application>
tag of your app'sAndroidManifest.xml
.
For more help, see the Android set up docs.
package com.example.myapp;
import android.app.Application;
import com.mparticle.MParticle;
class MyApplication : Application() {
fun onCreate() {
super.onCreate()
val options: MParticleOptions = MParticleOptions.builder(this)
.credentials("REPLACE ME WITH KEY", "REPLACE ME WITH SECRET")
//optional
.logLevel(MParticle.LogLevel.VERBOSE)
//optional
.identify(identifyRequest)
//optional
.identifyTask(
BaseIdentityTask()
.addFailureListener { errorResponse -> }
.addSuccessListener{ result -> }
)
//optional
.attributionListener(this)
.build()
MParticle.start(options)
}
}
Warning: Don't log events in your
Application.onCreate()
. Android may instantiate yourApplication
class in the background without your knowledge, including when the user isn't using their device, and lead to unexpected results.
Usage
Import the mParticle Module
import MParticle from 'react-native-mparticle'
Logging Events
To log basic events:
MParticle.logEvent('Test event', MParticle.EventType.Other, { 'Test key': 'Test value' })
To 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)
To log screen events:
MParticle.logScreenEvent('Test screen', { 'Test key': 'Test value' })
User
To set, remove, and get user details, call the User
or Identity
methods as follows:
MParticle.User.setUserAttribute('User ID', 'Test key', 'Test value')
MParticle.User.setUserAttribute('User ID', MParticle.UserAttributeType.FirstName, 'Test first name')
MParticle.User.setUserAttributeArray('User ID', 'Test key', ['Test value 1', 'Test value 2'])
MParticle.User.setUserTag('User ID', 'Test value')
MParticle.User.removeUserAttribute('User ID', 'Test key')
MParticle.Identity.getUserIdentities((userIdentities) => {
console.debug(userIdentities);
});
IdentityRequest
var request = new MParticle.IdentityRequest()
Setting user identities:
var request = new MParticle.IdentityRequest();
request.setUserIdentity('example@example.com', MParticle.UserIdentityType.Email);
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
var attributions = MParticle.getAttributions();
In order to listen for Attributions asynchronously, you need to set the proper field in MParticleOptions
as shown in the Android or the iOS SDK start examples.
Kits
Check if a kit is active
var isKitActive = MParticle.isKitActive(kitId);
Check and set the SDK's opt out status
var isOptedOut = MParticle.getOptOut();
MParticle.setOptOut(!isOptedOut);
Push Registration
The method MParticle.logPushRegistration()
accepts 2 parameters. For Android, provide both the 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, null);
GDPR Consent
Add a GDPRConsent
var gdprConsent = 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 a GDPRConsent
MParticle.removeGDPRConsentStateWithPurpose("the purpose");
CCPA Consent
Add a CCPAConsent
var ccpaConsent = 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.addCCPAConsentState(ccpaConsent);
Remove CCPAConsent
MParticle.removeCCPAConsentState();
License
Apache 2.0