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 allowing you to manage user-identity state. These client-side APIs work in tandem with the mParticle Identity HTTP API and your configured Identity “strategy.” These APIs are designed generically but identity management requirements vary by app - so it’s crucial that you use the APIs correctly per your requirements.
The mParticle Identity APIs surface four key operations (identify, login, logout, and modify), which each accept an identical request object. Populating this object correctly is crucial to managing the state of your users.
An identity request object should be populated with a userIdentities associative array containing the identities that you would like to associate with the user. When you invoke any of the four key Identity APIs, the identities you supply will be associated with the resulting user. Reference mparticleConstants().IDENTITY_TYPE within mParticleCore.brs for all of the available identity types.
identityApiRequest = {userIdentities:{}}
identityApiRequest.userIdentities[mparticleConstants().IDENTITY_TYPE.EMAIL] = "user@example.com"The Identity API lets you transition the SDK and data from one user to a new or different user. If while transitioning you’d like to copy the user attributes from the current user to the new user, each identity request supports a copyUserAttributes attribute. This field defaults to false, and in the case where an identity API request does not yield a new or different user, this setting has no effect.
identityApiRequest = {userIdentities:{}}
identityApiRequest.userIdentities[mparticleConstants().IDENTITY_TYPE.EMAIL] = "user@example.com"
identityApiRequest.copyUserAttributes = truemParticleTask will continually update an object representing the current user, and assign that object to its mParticleConstants().SCENEGRAPH_NODES.CURRENT_USER_NODE interface node. This object includes the user’s MPID, identities, and attributes. Observe changes to this node, or access it directly at any time:
'Scene init
sub init()
m.mParticleTask = createObject("roSGNode","mParticleTask")
m.mparticle = mParticleSGBridge(m.mParticleTask)
m.mParticleTask.ObserveField(mParticleConstants().SCENEGRAPH_NODES.CURRENT_USER_NODE, "onCurrentUserChanged")
end sub
function onCurrentUserChanged() as void
currentUser = m.mParticleTask[mParticleConstants().SCENEGRAPH_NODES.CURRENT_USER_NODE]
print currentUser.mpid
print formatjson(currentUser.userAttributes)
print formatjson(currentUser.userIdentities)
end functionmParticleTask will also assign an object representing the latest result from the Identity API to the mParticleConstants().SCENEGRAPH_NODES.IDENTITY_RESULT_NODE interface node. This object includes the HTTP response code and MPID if the API call was successful.
'Scene init
sub init()
m.mParticleTask = createObject("roSGNode","mParticleTask")
m.mparticle = mParticleSGBridge(m.mParticleTask)
m.mParticleTask.ObserveField(mParticleConstants().SCENEGRAPH_NODES.IDENTITY_RESULT_NODE, "onIdentityResult")
end sub
function onIdentityResult() as void
identityApiResult = m.mParticleTask[mParticleConstants().SCENEGRAPH_NODES.IDENTITY_RESULT_NODE]
print "IdentityResult: " + formatjson(identityApiResult)
if (identityApiResult.httpCode = 200) then
'Note that calls to modify will not have a body, as MPID cannot change from a modify()
if (identityApiResult.body.DoesExist("mpid")) then
print "New user MPID is: " + identityApiResult.body.mpid
end if
end if
end functionSee below for more about responding to these callbacks and handling errors.
The Identify API is treated specially in that it’s called automatically on SDK initialization. The SDK requires this call to succeed in order to establish an identity to associate with all data.
Some considerations to account for during SDK initialization:
identifyRequest field of the mParticleOptions object. See the SDK initialization example above.identifyRequest during SDK initialization, the SDK will use the Roku registry to generate a request for you based off of the most recent user, including the most recent user identities.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, both accepting an identity request:
mpConstants = mparticleConstants()
identityApiRequest = {}
identityApiRequest.userIdentities = {}
identityApiRequest.userIdentities[mpConstants.IDENTITY_TYPE.EMAIL] = "foo@example.com"
m.mparticle.identity.login(identityApiRequest)'It's common to pass an empty object to logout
m.mparticle.identity.logout({})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 identity request, 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:
mpConstants = mparticleConstants()
identityApiRequest = {}
identityApiRequest.userIdentities = {}
identityApiRequest.userIdentities[mpConstants.IDENTITY_TYPE.EMAIL] = "foo-2@example.com"
m.mparticle.identity.modify(identityApiRequest)In this example, the SDK will remove the email of the current user, or will be a no-op if the user has no email on this device:
mpConstants = mparticleConstants()
identityApiRequest = {}
identityApiRequest.userIdentities = {}
'Use an empty string to represent removal
identityApiRequest.userIdentities[mpConstants.IDENTITY_TYPE.EMAIL] = ""
m.mparticle.identity.modify(identityApiRequest)The mParticle Identity API is intended to be central to your channel’s state, and so is designed to be fast and highly-available. Similar to how your Roku channel may gate 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, but provides a callback mechanism such that you can do so according to your business logic.
The SDK will always return the HTTP status and HTTP body of the underlying request:
function onIdentityResult() as void
identityApiResult = m.mParticleTask[mParticleConstants().SCENEGRAPH_NODES.IDENTITY_RESULT_NODE]
print "IdentityResult: " + formatjson(identityApiResult)
if (identityApiResult.httpCode = 200) then
'Note that calls to modify will not have a body, as MPID cannot change from a modify()
print "New user MPID is: " + identityApiResult.body.mpid
else if (identityApiResult.httpCode = 401) then
'Authentication error - check that your App key and secret are correctly configured
else if (identityApiResult.httpCode = 400) then
`Bad request - check the contents of your identity API call and inspect the message in the body
print identityApiResult.body.message
else if (identityApiResult.httpCode = 429) then
'retry the request
end if
end functionIf you receive an HTTP 200, the call was successful. Otherwise the call may need to be amended or retried. In addition to the set of HTTP codes defined by the Identity API here, you can expect to receive the same standard set of roUrlEvent codes defined here.
Was this page helpful?