Data Subject Request API Version 1 and 2
Data Subject Request API Version 3
Platform API Overview
Accounts
Apps
Audiences
Calculated Attributes
Data Points
Feeds
Field Transformations
Services
Users
Workspaces
Warehouse Sync API Overview
Warehouse Sync API Tutorial
Warehouse Sync API Reference
Data Mapping
Warehouse Sync SQL Reference
Warehouse Sync Troubleshooting Guide
ComposeID
Warehouse Sync API v2 Migration
Custom Access Roles API
Bulk Profile Deletion API Reference
Data Planning API
Group Identity API Reference
Calculated Attributes Seeding API
Pixel Service
Profile API
Events API
mParticle JSON Schema Reference
IDSync
AMP SDK
Initialization
Configuration
Network Security Configuration
Event Tracking
User Attributes
IDSync
Screen Events
Commerce Events
Location Tracking
Media
Kits
Application State and Session Management
Data Privacy Controls
Error Tracking
Opt Out
Push Notifications
WebView Integration
Logger
Preventing Blocked HTTP Traffic with CNAME
Linting Data Plans
Troubleshooting the Android SDK
API Reference
Upgrade to Version 5
Cordova Plugin
Identity
Direct URL Routing FAQ
Web
Android
iOS
Initialization
Configuration
Event Tracking
User Attributes
IDSync
Screen Tracking
Commerce Events
Location Tracking
Media
Kits
Application State and Session Management
Data Privacy Controls
Error Tracking
Opt Out
Push Notifications
Webview Integration
Upload Frequency
App Extensions
Preventing Blocked HTTP Traffic with CNAME
Linting Data Plans
Troubleshooting iOS SDK
Social Networks
iOS 14 Guide
iOS 15 FAQ
iOS 16 FAQ
iOS 17 FAQ
iOS 18 FAQ
API Reference
Upgrade to Version 7
Getting Started
Identity
Upload Frequency
Getting Started
Opt Out
Initialize the SDK
Event Tracking
Commerce Tracking
Error Tracking
Screen Tracking
Identity
Location Tracking
Session Management
Initialization
Configuration
Content Security Policy
Event Tracking
User Attributes
IDSync
Page View Tracking
Commerce Events
Location Tracking
Media
Kits
Application State and Session Management
Data Privacy Controls
Error Tracking
Opt Out
Custom Logger
Persistence
Native Web Views
Self-Hosting
Multiple Instances
Web SDK via Google Tag Manager
Preventing Blocked HTTP Traffic with CNAME
Facebook Instant Articles
Troubleshooting the Web SDK
Browser Compatibility
Linting Data Plans
API Reference
Upgrade to Version 2 of the SDK
Getting Started
Identity
Web
Alexa
Overview
Step 1. Create an input
Step 2. Verify your input
Step 3. Set up your output
Step 4. Create a connection
Step 5. Verify your connection
Step 6. Track events
Step 7. Track user data
Step 8. Create a data plan
Step 9. Test your local app
Overview
Step 1. Create an input
Step 2. Verify your input
Step 3. Set up your output
Step 4. Create a connection
Step 5. Verify your connection
Step 6. Track events
Step 7. Track user data
Step 8. Create a data plan
Step 1. Create an input
Step 2. Create an output
Step 3. Verify output
Node SDK
Go SDK
Python SDK
Ruby SDK
Java SDK
Introduction
Outbound Integrations
Firehose Java SDK
Inbound Integrations
Compose ID
Data Hosting Locations
Glossary
Migrate from Segment to mParticle
Migrate from Segment to Client-side mParticle
Migrate from Segment to Server-side mParticle
Segment-to-mParticle Migration Reference
Rules Developer Guide
API Credential Management
The Developer's Guided Journey to mParticle
Create an Input
Start capturing data
Connect an Event Output
Create an Audience
Connect an Audience Output
Transform and Enhance Your Data
The new mParticle Experience
The Overview Map
Introduction
Data Retention
Connections
Activity
Live Stream
Data Filter
Rules
Tiered Events
mParticle Users and Roles
Analytics Free Trial
Troubleshooting mParticle
Usage metering for value-based pricing (VBP)
Introduction
Sync and Activate Analytics User Segments in mParticle
User Segment Activation
Welcome Page Announcements
Project Settings
Roles and Teammates
Organization Settings
Global Project Filters
Portfolio Analytics
Analytics Data Manager Overview
Events
Event Properties
User Properties
Revenue Mapping
Export Data
UTM Guide
Data Dictionary
Query Builder Overview
Modify Filters With And/Or Clauses
Query-time Sampling
Query Notes
Filter Where Clauses
Event vs. User Properties
Group By Clauses
Annotations
Cross-tool Compatibility
Apply All for Filter Where Clauses
Date Range and Time Settings Overview
Understanding the Screen View Event
Analyses Introduction
Getting Started
Visualization Options
For Clauses
Date Range and Time Settings
Calculator
Numerical Settings
Assisted Analysis
Properties Explorer
Frequency in Segmentation
Trends in Segmentation
Did [not] Perform Clauses
Cumulative vs. Non-Cumulative Analysis in Segmentation
Total Count of vs. Users Who Performed
Save Your Segmentation Analysis
Export Results in Segmentation
Explore Users from Segmentation
Getting Started with Funnels
Group By Settings
Conversion Window
Tracking Properties
Date Range and Time Settings
Visualization Options
Interpreting a Funnel Analysis
Group By
Filters
Conversion over Time
Conversion Order
Trends
Funnel Direction
Multi-path Funnels
Analyze as Cohort from Funnel
Save a Funnel Analysis
Explore Users from a Funnel
Export Results from a Funnel
Saved Analyses
Manage Analyses in Dashboards
Dashboards––Getting Started
Manage Dashboards
Dashboard Filters
Organize Dashboards
Scheduled Reports
Favorites
Time and Interval Settings in Dashboards
Query Notes in Dashboards
User Aliasing
The Demo Environment
Keyboard Shortcuts
Analytics for Marketers
Analytics for Product Managers
Compare Conversion Across Acquisition Sources
Analyze Product Feature Usage
Identify Points of User Friction
Time-based Subscription Analysis
Dashboard Tips and Tricks
Understand Product Stickiness
Optimize User Flow with A/B Testing
User Segments
IDSync Overview
Use Cases for IDSync
Components of IDSync
Store and Organize User Data
Identify Users
Default IDSync Configuration
Profile Conversion Strategy
Profile Link Strategy
Profile Isolation Strategy
Best Match Strategy
Aliasing
Overview
Create and Manage Group Definitions
Introduction
Catalog
Live Stream
Data Plans
Blocked Data Backfill Guide
Predictive Attributes Overview
Create Predictive Attributes
Assess and Troubleshoot Predictions
Use Predictive Attributes in Campaigns
Predictive Audiences Overview
Using Predictive Audiences
Introduction
Profiles
Warehouse Sync
Data Privacy Controls
Data Subject Requests
Default Service Limits
Feeds
Cross-Account Audience Sharing
Approved Sub-Processors
Import Data with CSV Files
CSV File Reference
Glossary
Video Index
Single Sign-On (SSO)
Setup Examples
Introduction
Introduction
Introduction
Rudderstack
Google Tag Manager
Segment
Advanced Data Warehouse Settings
AWS Kinesis (Snowplow)
AWS Redshift (Define Your Own Schema)
AWS S3 Integration (Define Your Own Schema)
AWS S3 (Snowplow Schema)
BigQuery (Snowplow Schema)
BigQuery Firebase Schema
BigQuery (Define Your Own Schema)
GCP BigQuery Export
Snowflake (Snowplow Schema)
Snowplow Schema Overview
Snowflake (Define Your Own Schema)
Aliasing
The React Native SDK surfaces a series of APIs allowing you to manage user-identity state. These client-side APIs work in tandem with mParticle’s Identity API and your configured Identity strategy. Identity management requirements vary by app, so it’s crucial that you use the APIs correctly per your requirements.
| Identity Type | Description |
|---|---|
customerid |
An internal customer ID in your app |
deviceapplicationstamp |
The ID for the user’s device generated by mParticle when the SDK initializes. Learn more in Device ID |
email |
The user’s email address |
facebook |
The user’s Facebook ID |
facebookcustomaudienceid |
The user’s Facebook Custom Audience ID |
google |
The user’s Google ID |
iosadvertiserid |
The user’s iOS advertiser ID |
iosvendorid |
The user’s iOS vendor ID |
microsoft |
The user’s Microsoft ID |
mobilenumber |
The user’s mobile phone number |
other |
The first of 10 possible custom identifiers that can help identify the user. Append a number from 2 to 10 for each identifier in addition to the first. For example, the second custom identifier would be other2. |
phonenumber2 |
The user’s second phone number |
phonenumber3 |
The user’s third phone number |
pushtoken |
An iOS APNS push token, Android FCM Instance ID, or Fire push token that can help identify the user |
twitter |
The user’s Twitter ID |
yahoo |
The user’s Yahoo ID |
The mParticle Identity APIs surface four key operations (identify, login, logout, and modify). identify is called automatically when the mParticle SDK is initialized. When using the React Native SDK, the initial request should be handled in your iOS or Android native code during SDK initialization. See our iOS and Android docs for more info on how to identify a user when the SDK initializes.
Once the SDK has initialized, you can use the login, logout and modify methods supported by the React Native SDK. Each method accepts an optional request object and a callback. Populating the request object correctly is crucial to managing the state of your users.
The IdentityRequest object is a holder for a set of identities that you would like to associate with the user. Populating the request object correctly is crucial to managing the state of your users. When you invoke any of the key Identity APIs with a request object, the identities it holds will be associated with the resulting user.
var request = new MParticle.IdentityRequest();
request.email = 'h.jekyll.md@example.com';The Identify API is treated specially in that it’s called automatically on SDK initialization by the mParticle SDK. The SDK requires this call to succeed in order to establish an identity to associate with all data.
Login and Logout should be invoked at the time of the user performing the matching or applicable actions in your application. These methods accept an Identity Request object and a callback, allowing you to handle errors, or do something with the returned User.
MParticle.Identity.login(request, (error, user) => {
if (error) {
console.debug(error);
} else {
console.debug(user.userAttributes);
}
});MParticle.Identity.logout(null, (error, user) => {
if (error) {
console.debug(error);
} else {
console.debug(user.userAttributes);
}
});Modify also has the identical signature, but note a crucial difference: modify actions will never result in a new user. Modify can only add, remove, or change the identities associated with an existing user. The mParticle SDK will compare the current user’s user identities with those that you supply within the IdentityApiRequest, in order to generate a delta and invoke the underlying Identity HTTP API.
In this example, the SDK will change the email of the current user, or add the email to the user’s profile if the user has no existing email on this device:
var request = new MParticle.IdentityRequest();
request.email = 'ed.hyde@example.com';
MParticle.Identity.modify(request, (error, apiResult) => {
if (error) {
console.debug(error);
} else {
console.debug(apiResult.user.userAttributes);
}
});Once the SDK has successfully called Identify for the first time, you will be able to access the current user via getCurrentUser():
MParticle.Identity.getCurrentUser((currentUser) => {
// Set user attribute
currentUser.setUserAttribute('Test key', 'Test value')
// Set reserved user attribute
currentUser.setUserAttribute(MParticle.UserAttributeType.FirstName, 'Test first name')
// Create an attribute list
currentUser.setUserAttributeArray('Test key', ['Test value 1', 'Test value 2'])
// Create a tag
currentUser.setUserTag('Test key')
// Remove an attribute
currentUser.removeUserAttribute('Test key')
});Always refer to your organization’s data plan when instrumenting user or event attributes. Each unique attribute key becomes a data point in the mParticle UI that can be filtered for each Output, used to drive the calculation of an Audience or become part of a Custom Mapping. This means that your choice of attribute keys can have a system-wide impact. For example, if you have a single attribute key per device that represents a unique User ID or a unique URL, and you have thousands of users, mParticle will see thousands of unique keys, even though you only create one per device.
Creating too many unique attribute keys can have several adverse effects:
You should avoid the following as attribute keys:
A gaming app has ten levels and you want to track which level each user has achieved.
Bad option: Create ten tags - reachedLevel1, reachedLevel2, reachedLevel3, etc.
Better option: Create a single attribute - reachedLevel = 4.
Capturing this data as a single attribute improves the performance of both your app and the mParticle dashboard by reducing the number of unique data points you need to manage. It’s also a much more useful data point. For example, you can easily create a single audience builder condition to target users within a range of levels reached.
An mParticle Workspace can combine data from multiple platforms, for example it can show data from the same app running in iOS and Android. For this reason, you may wish to choose attribute names that you can keep consistent across all platforms for easier management. For example, if you call an attribute levelReached in iOS, LevelReached on Android, and level_reached on web, mParticle will treat these as three separate attributes.
Was this page helpful?