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 SDK surfaces a series of APIs to manage user-identity state. These client-side APIs work in tandem with the mParticle IDSync HTTP API and your configured “identity strategy.” These APIs are designed generically but identity management requirements vary by site - so it’s crucial that you use the APIs correctly per your site’s unique requirements.
See the mParticle IDSync overview for a platform-agnostic overview of the key operations you can perform and read below for how the API is surfaced for the web SDK.
There are four key IDSync methods available in the web SDK:
identify
login
logout
modify
The following applies to each of these methods:
identify
or login
method on every page load. This is not necessary and will result in high network traffic. Note that the exception to this is the automatic “identify” API call made by the SDK on page load.Each IDSync identification request is populated with a userIdentities
object that contains the identities to associate with the user. When any of the IDSync methods (identify, login, logout, or modify) are called, the identities supplied in userIdentities
will be associated with the user profile returned by IDSync.
For example, consider the following login
method call:
var identityRequest = {
userIdentities: {
email: 'email@example.com',
customerid: '123456'
}
};
mParticle.Identity.login(identityRequest);
When you invoke any of the four key IDSync methods with a request object as shown above:
login
) with all the supplied identities, including the device_id
(which is automatically included).By default, mParticle submits an identify
request each time the SDK is initialized. The SDK requires this call to succeed in order to establish an mParticle ID to associate with all subsequent data.
There are several considerations to account for during SDK initialization:
identifyRequest
field of the mParticle.config
object. See the SDK initialization example below.identifyRequest
during SDK initialization, the SDK will use browser local storage and/or cookies to generate a request for you based off of the most recent user, including the most recent user identities.identityCallback
to the window.mParticle.config
object as shown in the configuration options documentation. The is executed once the initial IDSync request returns, or with cached results in the case of a reload during an active user session.Here’s an example of how you might initialize the SDK and set a user-attribute once the user object becomes available:
window.mParticle = {
config: {
identifyRequest: {
userIdentities: {
email: 'email@example.com',
customerid: '123456'
}
},
identityCallback: function(result) {
// You can check if there's a populated user object, otherwise there was an error
// You can also inspect the result.httpCode - see below for a description of the supported codes
if (result.getUser()) {
result.getUser().setUserAttribute('age', '25');
} else {
//the IDSync call failed - see below for more details on failed requests
}
}
}
};
Login and Logout should be invoked at the time of the user performing the matching or applicable actions on your site. These methods have identical signatures. They accept an identity request as above, as well as an optional callback function:
var identityRequest = {
userIdentities: {
email: 'email@example.com',
customerid: '123456'
}
};
var identityCallback = function(result) {
if (result.getUser()) {
//proceed with login
}
};
mParticle.Identity.login(identityRequest, identityCallback);
Logout is invoked similarly to login, and you can supply a request object if you have anonymous identifiers you would like to associate with the logged-out user state. More commonly, you can use an empty object to denote that the logged-out user should have no associated user identities:
var identityCallback = function(result) {
if (result.getUser()) {
//proceed with logout
}
};
mParticle.Identity.logout({}, identityCallback);
Modify also has the identical signature, but note a crucial difference: modify actions are always for a specific mParticle ID (MPID) - they will never result in a new user or MPID. Modify can only add, remove, or change the identities associated with an existing user. Please note that this should not be used to handle registration/login and logout scenarios. Modify is generally used when a user updates their profile on your site, such as updating their email.
For each modify request:
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 identityRequest = {
userIdentities: { email: 'updated-email@example.com' }
}
mParticle.Identity.modify(identityRequest, identityCallback);
In this example, the SDK will remove the email of the current user, or will do nothing if the user has no email on this device:
var identityRequest = {
userIdentities: { email: null }
}
mParticle.Identity.modify(identityRequest, identityCallback);
The mParticle IDSync API is intended to be central to your site’s state, and so is designed to be fast and highly-available. Similar to how your site may prevent users from logging in, logging out, or modifying their state without an internet connection - we intend you to treat these APIs as gating operations in order to maintain a consistent user state. The SDK will not retry API calls automatically, but provides a callback mechanism such that you can retry according to your requirements.
If you do not wish to handle errors, you may see data consistency issues at scale. It’s recommended to at least monitor for errors during your implementation.
The result object passed to your IDSync callback function includes the following:
result.httpCode
: (Number) Either a client-side generated negative value, or an HTTP status code if an HTTP request was made.result.body
: (String) Either a client-side generated error message, or the body of the IDSync HTTP response.result.getUser()
: (Function) Returns the updated user object returns null
in the case of an IDSync API failure. See the tables below.If the IDSync call succeeded or returned cached results (see table below), you will be able to access the updated user object via the getUser()
function of the result object.
function identityCallback(result) {
if (result.getUser()) {
//IDSync request succeeded, mutate attributes or query for the MPID as needed
var user = result.getUser();
console.log(user);
return;
}
var codes = window.mParticle.Identity.HTTPCodes;
switch(result.httpCode) {
case codes.noHttpCoverage:
// retry the IDSync request
break;
case codes.activeIdentityRequest:
case 429:
//inspect your implementation if this occurs frequency
//otherwise retry the IDSync request
break;
case codes.validationIssue:
case 400:
console.log(result.body);
// inspect result.body to determine why the request failed
// this typically means an implementation issue
break;
default:
console.log(result.body);
}
}
When an IDSync callback function in invoked, the result will always contain the httpCode
property. This property is meant to describe the result of the invocation of the respective web SDK IDSync API. Note that “http” is a misnomer as it may either contain a client-side generated value, or an actual HTTP status code.
The httpCode
property may contain the following client-side codes, available via the mParticle.Identity.HTTPCodes
object:
Property | Value | Description |
---|---|---|
HTTPCodes.noHttpCoverage |
-1 | The IDSync HTTP request failed due to no network coverage. |
HTTPCodes.activeIdentityRequest |
-2 | The IDSync HTTP request was not performed as there is already an IDSync HTTP request in progress |
HTTPCodes.activeSession |
-3 | The IDSync HTTP request was not performed as there is an active session. This is only used when invoking the identityCallback property of mParticle.config on page load. In this case, the result object will contain a valid user object via result.getUser() |
HTTPCodes.validationIssue |
-4 | The IDSync HTTP request was not performed as there were invalid identity keys or the request was otherwise invalid. Inspect the result.body string message for more information. |
HTTPCodes.nativeIdentityRequest |
-5 | The IDSync HTTP request was delegated to the mParticle iOS or Android SDK - this will only occur while the web SDK has been bound to the mParticle iOS or Android SDK in a mobile Webview. |
The httpCode
property may also contain the following HTTP status codes:
Value | Description |
---|---|
200 | The IDSync HTTP call was successful. |
400 | The IDSync HTTP call failed due to an invalid request body. Inspect the result.body string message for more information. |
401 | The IDSync HTTP call failed due to an authentication error. Verify that your workspace is provisioned for IDSync and that your API key is correct. |
403 Forbidden | Aliasing is not provisioned for your mParticle workspace. Contact your mParticle account representative to have aliasing provisioned. |
429 | The IDSync HTTP call was throttled and should be retried. This may indicate a user “hotkey” or an incorrect implementation resulting in a higher than expected volume of IDSync requests. Learn more about API throttling in Default Service Limits. |
5xx | The IDSync HTTP call failed due to an mParticle server-side issue. This should never happen under typical circumstances. Check the mParticle status page if this is occuring. |
As mentioned in the overview above, the IDSync API is meant to transition the SDK’s “current user.” The SDK maintains values in persistence that are associated with each user, such as user attributes. On completion of a successful login, you can copy user data from the previous user to the new user.
If your organization uses Profile Link or Profile Conversion strategies, you can also create a request to alias the previous user to the current user. See our main documentation on aliasing for more information.
Note that mParticle does not prevent aliasing a known user to another known user, as there may be use cases for this depending on your business. If you don’t want to alias known users to each other, ensure that the previous user is anonymous before aliasing to a known user. This can be checked by determining that there are no identities on the user.
// Basic - Call alias as the result of a successful login
var identityCallback = function(result) {
// Copy attributes from previous user to current user
result.getUser().setUserAttributes(result.getPreviousUser().getAllUserAttributes());
var previousUser = result.getPreviousUser();
// If the user is anonymous, create and send the alias request
if (previousUser && Object.keys(previousUser.getUserIdentities().userIdentities).length === 0) {
var aliasRequest = mParticle.Identity.createAliasRequest(result.getPreviousUser(), result.getUser());
mParticle.Identity.aliasUsers(aliasRequest);
}
};
mParticle.Identity.login(identityRequest, identityCallback);
// Call alias at any time
mParticle.Identity.aliasUsers({
destinationMpid: '123',
sourceMpid: '456',
startTime: 10001230123,
endTime: 10001231123
});
Sometimes web sites log a user out if they have not returned for a period of time. To keep mParticle’s user state in sync with the state of your website, be sure to call logout
appropriately to avoid associating anonymous events with the wrong user. You can then perform a login
with an alias request in the callback if necessary.
See the table below for the supported user identity types strings:
IdentityType | Description |
---|---|
customerid |
If you have an internal ID for your customer |
email |
The user’s email address |
other |
Any other identifier that can contribute to user identification |
other2 |
Any other identifier that can contribute to user identification |
other3 |
Any other identifier that can contribute to user identification |
other4 |
Any other identifier that can contribute to user identification |
other5 |
Any other identifier that can contribute to user identification |
other6 |
Any other identifier that can contribute to user identification |
other7 |
Any other identifier that can contribute to user identification |
other8 |
Any other identifier that can contribute to user identification |
other9 |
Any other identifier that can contribute to user identification |
other10 |
Any other identifier that can contribute to user identification |
mobile_number |
The user’s mobile number |
phone_number_2 |
Any other phone number for the user |
phone_number_3 |
Any other phone number for the user |
facebook |
The user’s Facebook ID |
facebookcustomaudienceid |
The user’s Facebook App User ID that can be retrieved through the Facebook SDK |
google |
The user’s Google ID |
twitter |
The user’s Twitter ID |
microsoft |
The user’s Microsoft ID |
yahoo |
The user’s Yahoo ID |
Was this page helpful?