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
Bulk Profile Deletion API Reference
Calculated Attributes Seeding API
Custom Access Roles API
Data Planning API
Group Identity API Reference
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
Getting Started
Identity
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
Upload Frequency
Getting Started
Opt Out
Initialize the SDK
Event Tracking
Commerce Tracking
Error Tracking
Screen Tracking
Identity
Location Tracking
Session Management
Initialization
Content Security Policy
Configuration
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
Node SDK
Go SDK
Python SDK
Ruby SDK
Java SDK
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
Introduction
Outbound Integrations
Firehose Java SDK
Inbound Integrations
Data Hosting Locations
Compose ID
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
Organize Dashboards
Dashboard Filters
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
mParticle aims to allow our customers to send their data wherever they want it to go, and we integrate with many services across the mobile-app ecosystem in order to achieve that. mParticle Firehose is an API that lets anybody become one of our integration partners. We support two basic types of Firehose integration:
The Firehose Java SDK can be used for either integration type.
Releases of this library are compiled using JDK 1.8 - any project using this library must also be compiled using JDK 1.8.
mParticle deploys the Java SDK to Maven Central as the com.mparticle:java-sdk
artifact:
dependencies {
compile (
'com.amazonaws:aws-lambda-java-core:1.1.0',
'com.amazonaws:aws-lambda-java-events:1.1.0',
'com.mparticle:java-sdk:3.0.+'
)
}
Rather than using Maven Central, you can also publish the library to your local Maven server by cloning this repo and invoking the following:
./gradlew publishToMavenLocal
You can clone this project and build the jar manually to include in your project’s classpath:
./gradlew assemble
We also make the latest jar binaries available in the releases section of this repository.
In order to create a Lambda function compatible with mParticle Firehose you’ll be creating a Lambda function just like any other, and then using the Java library in this repository to parse and facilitate communication in between mParticle and your function.
mParticle has created a sample project to get you started quicker, but it may also be useful to read an overview on AWS Lambda here: http://docs.aws.amazon.com/lambda/latest/dg/java-gs.html
In order to get started quicker, you can clone the sample project located here:
https://github.com/mParticle/firehose-sample
The sample project takes care of the basics of creating a lambda function for you. Most importantly it includes a class that implements the RequestStreamHandler
interface of the Amazon AWS lambda SDK. When data is received by the RequestStreamHandler
, it’s deserialized by the mParticle Java SDK into POJOs to be used by you, as in the following snippet:
/**
* Sample AWS Lambda Endpoint
*/
public class SampleLambdaEndpoint implements RequestStreamHandler {
MessageSerializer serializer = new MessageSerializer(); //mParticle class for deserialization
@Override
public void handleRequest(InputStream input, OutputStream output, Context context) throws IOException {
SampleExtension processor = new SampleExtension(); //you will implement this class in a later step
Message request = serializer.deserialize(input, Message.class);
Message response = processor.processMessage(request); //request is processed by you here
serializer.serialize(output, response);
}
}
MessageProcessor
In the example above, incoming data is deserialized to a Message
object, and passed in to SampleExtension
. SampleExtension
is any class that extends the mParticle Java SDK’s MessageProcessor
- which you will implement. This will serve as the entry point to all of your logic and ultimately, the 3rd-party service to which you’re integrating.
The base MessageProcessor
implementation is responsible for parsing incoming Message
objects. MessageProcessor
contains several abstract and empty method implementations responsible for processing Message
objects which you will override and implement. Currently, the types of messages are:
To get started creating your MessageProcessor
, if you’re using the sample project, open and edit SampleExtension.java
. Otherwise, create a class that extends com.mparticle.sdk.MessageProcessor
.
All response messages must contain an id
element, which contains a guid, and can be the same id sent in the request.
To process the module registration message, override the processRegistrationRequest
method in your MessageProcessor
. From this method you must return a ModuleRegistrationResponse
describing what your integration can do and what it requires to contact your service, such as an API key.
The details of the registration response are outlined below. For a full example of a response object, see the registration response example.
ModuleRegistrationResponse
and Describing your ServicemParticle users will see the result of your module registration response in our Integrations directory. You should set a human-readable title for your service (such as your company’s name), as well as a short description of your company including a link to your company’s website with optional tracking parameters. Your description must be less than 230 characters.
This information will be also shown on the mParticle documentation and marketing sites.
Override the processRegistrationRequest
method in your MessageProcessor
and add the following code, customized for your service:
ModuleRegistrationResponse response = new ModuleRegistrationResponse("My Company Name", "1.0");
response.setDescription("<a href=\"http://www.mycompany.com?utm_source=mparticle\" target=\"_blank\">My Company</a> empowers brands to meaningfully engage their customers by leveraging data insights. With My Company's help, brands can personalize and cultivate their customer experience.\"");
All users and data in the mParticle platform are associated with a set of device IDs (such as an Apple IDFA), a set of user IDs (such as Email), and a set of partner-specific IDs. Event data and audience data received by your integration will always be associated with a user, but your integration must register for permission to receive each ID.
If you mark any of these IDs as required
, only users and their associated data that contain at least 1 of these IDs will be sent to your integration.
You can also easily configure that mParticle hash each of these identities in the outgoing payload, using the encoding
field. Supported encoding types: RAW
, MD5
, SHA1
, and SHA256
, and all hashed values are lowercased before hashing.
Partner IDs are unique identifiers associated with a user, but specific to a partner system. They can be ingested by mParticle via Partner Feed or S2S, and can be sent to downstream connections associated with the given partner (including a Firehose integration). In order for this to occur, the Partner’s unique identity type name
needs to be pre-registered with mParticle, which can be accomplished by simply adding a permission for it.
Currently, only a single Partner ID permission can be registered. Similarly, the name cannot be changed or removed once registered.
The naming convention for these identities is as follows: PartnerName_IdentityName
.
An example for mParticle could be: mParticle_mpid
Cookie Sync IDs are special Partner IDs that pertain to individual users, and are associated with mParticle Cookie Sync Integrations. If your organization has both a Cookie Sync and Firehose integration with mParticle, you can also configure your Firehose integration’s incoming traffic to include this ID — just as you would for a general Partner ID.
In order to register a Cookie Sync ID, add a Partner ID permission with "type": "$cookie_sync_id"
Device Application Stamp is a UUIDv4-formatted string generated by mParticle for each device.
permissions.setAllowAccessDeviceApplicationStamp(true);
The mParticle ID is a unique identifier for a user profile in mParticle.
permissions.setAllowAccessMpid(true);
All mParticle event data can also be associated with location information, and your Firehose integration requires special permissions to access it. Depending on the app and how it has used the mParticle SDK, location information may originate from the device sensors or may be determined, to varying degrees of accuracy, by using reverse IP lookup. If your service needs access to location, you must request access by setting the following:
permissions.setAllowAccessLocation(true);
Data can be sent into the mParticle platform via one of our native or web SDKs, as well as our Events APIs, and will have an associated IP address and HTTP user agent header of the originating client. If your service needs access to the IP address, you must request access by setting the following:
permissions.setAllowAccessIpAddress(true);
permissions.setAllowAccessHttpUserAgent(true);
See the example below or the javadocs for more information on populating the Permissions
object in your ModuleRegistrationResponse
response.
mParticle data can contain information about the device being used, including device name, OS Version, and carrier information. By default, this information will not be forwarded to your integration. You can request access to device information with the following:
permissions.setAllowDeviceInformation(true);
For a full list of possible device information, see our JSON reference. Note that even if you don’t set this permission, the Device Identities you registered for above will still be forwarded.
mParticle data can include a dictionary of custom user attributes containing information about the user. By default, this information will not be forwarded to your integration. You can request access to user attributes with the following:
permissions.setAllowUserAttributes(true);
This permission is also required to receive User Attribute Change events.
mParticle can include user attributes with audience membership change messages as well as event data. You can request access to audience user attributes with the following:
permissions.setAllowAudienceUserAttributeSharing(true);
mParticle allows clients to record consent for data collection from their users. By default, this information will not be forwarded to your integration. You can request access to the user’s consent state by setting:
permissions.setAllowConsentState(true);
If enabled, the current consent state will be forwarded for users at the time of the event.
To learn more about the consent state object, reference the following:
mParticle allows batches that do not contain any events or system notifications. By default, these batches will not be forwarded to your integration. You can request access to these eventless batches by setting:
permissions.setAllowEventlessBatches(true);
mParticle data can include information about the platform that generated the events with each EventProcessingRequest.
By default, the above platform fields will not be forwarded to your integration. You can request access to them by setting:
permissions.setAllowPlatformFields(true);
You need to select which platforms you want your integration to receive data from. mParticle’s Firehose forwarder allows you to receive data from the following platforms:
ALEXA
ANDROID
FIRETV
IOS
MOBILEWEB
ROKU
SMARTTV
TVOS
UNKNOWN
XBOX
See the example below or the javadocs for more information on populating the Permissions
object in your ModuleRegistrationResponse
response.
There are two fields in IosRuntimeEnvironment and TVOSRuntimeEnvironment to support App Tracking Transparency policy. Learn more about Apple’s App Tracking Transparency in our iOS 14 Guide.:
Field | Type | Description |
---|---|---|
AttAuthorizationStatus |
Enum: AttAuthorizationStatus | Contains the assigned ATT Authorization status value. |
AttTimestampUnixtimeMs |
long |
Contains the timestamp of when the authorization status was given. |
Once we enable your Firehose integration, all mParticle customers will have access to enable it for their account. To allow your integration to correctly identify which customer your data belongs to, and how it should be processed, mParticle enables you to create custom settings for the customer to provide when they set up the account. For example, if your service uses an API Key
for authentication:
ModuleRegistrationResponse
.When customers configure your integration through mParticle, they will see the API Key setting in a dialogue, and will need to enter their API Key in order to enable the integration.
Settings need to be registered individually for Event, Audience and DSR-based integrations. Each setting will appear in the mParticle UI (unless marked as not-visible), and must contain the following:
4
above to extract the setting value.See the following code snippet, the full example below, or the Javadocs for more on the various types of settings and properties of settings.
List<Setting> eventSettings = new ArrayList<>();
Setting apiKey = new TextSetting("apiKey", "API Key")
.setIsRequired(true)
.setIsConfidential(true)
.setDescription("Your API Key issued by <insert company here>.");
eventSettings.add(apiKey);
eventProcessingRegistration.setAccountSettings(eventSettings);
List<Setting> audienceSettings = new ArrayList<>();
audienceSettings.add(apiKey);
audienceProcessingRegistration.setAccountSettings(audienceSettings);
List<Setting> dsrSettings = new ArrayList<>();
dsrSettings.add(apiKey);
dsrProcessingRegistration.setAccountSettings(dsrSettings);
Authentication can be set for your Event Registration and/or Audience Registration. DSR Registration does not currently support authentication setup. These settings allow customers to add authentication when configuring your integration in mParticle. Currently, we support OAuth2 authentication, which gets the Access Token and forwards it in requests to your integration. While OAuth2 is a standard protocol, its implementation can differ by identity provider so some parameters may be optional. Depending on the OAuth2 provider, you must include the relevant parameters.
Field Name | Required | Description |
---|---|---|
Type | Required | The authentication type (only OAuth 2.0 is supported). The allowed values are:
|
Authorization URL | Required | The Authorization URL initiates the authorization process, authenticating the user with the identity provider. |
Refresh URL | Optional | If the access token has an expiration time the Refresh URL will be used to get a new token. |
Token URL | Required | The Token URL will be used to get the access token after the identity provider returns the Auth Code. |
Grant Type | Optional | The Grant Type specifies the way mParticle gets an access token. The allowed values are:
|
Default Expires In | Optional | If the access token expires, this indicates the lifetime (in seconds) of the Access Token. |
Client ID | Required | The Client ID is the public identifier for your application in the identity provider. |
Access Token Type | Optional | The allowed values are:
|
Custom Header Name | Optional | If Access Token Type is set to CUSTOM_HEADER you need to specify the name of the Custom Header in which the identity provider can expect the Access Token. |
Param Client ID Name | Optional | The OAuth2 Standard protocol refers to Client ID as client_id . If your identity provider uses a different name for communications you need to specify that name. |
Param Secret Name | Optional | The OAuth2 Standard protocol refers to Client Secret as client_secret . If your identity provider uses a different name for communications you need to specify that name. |
Scopes | Optional | The list of scopes in which your application may access a user’s account. Name: Name of the scope Description: Description of the scope |
If you’re writing an integration that can handle event and analytics data, you’ll specify that your service supports certain types of events in your ModuleRegistrationResponse
. This means you will only receive data when those events occur. The possible event types are:
Note that to receive User Attribute Change events, you must also register the Allow User Attributes permission. Similarly, for User Identity Change events, you will only receive events for the identities you have set permissions to receive.
See here for brief descriptions of each event type.
System Notifications are used to communicate changes to a user. Currently, the available System Notifications are:
Note that System Notifications related to Consent States describe changes to the consent state. As such, they each contain both the old
and the new
consent states.
These notifications are different from the actual Consent State object.
This setting lets mParticle know if historical events can be sent to your integration. The default is 24
hours, however if your platform can receive and process older data, you can set this to a higher value, or to -1
to process all data.
EventProcessingRegistration eventProcessingRegistration = new EventProcessingRegistration();
eventProcessingRegistration.setMaxDataAgeHours(24)
If you have registered for Push Message Receipt events, you must provide the Provider ID key used in the payload of your platform’s Push messages. This ensures that you only receive events related to Push messages from your platform. Work with mParticle to ensure you are providing the correct Provider ID.
eventProcessingRegistration.setPushMessagingProviderId("your-push-messaging-provider-id");
Audience Registration will allow your integration to receive Audience Subscription and Membership messages. During registration, your integration needs to specify the settings required to map and send audience data from mParticle to your service:
Audience Subscription Settings can be included in your module registration response as shown here.
More information about AudienceProcessingRegistration
These settings allow you to enable bulk forwarding, which is supported by audience integrations. The following are the two settings that you can configure:
It is important to note that these settings are not dependent on each other, so you can set one or the other, or both. If one of the settings is not set, mParticle will use a default value for that specific setting. For Bulk Forward Wait For Messages, the default and minimum value is 2000 messages. For Bulk Forward Wait In Minutes, the default value is 12 hours (720 minutes) and the minimum value is 30 minutes.
More information about BulkConfiguration
DSR Registration will allow the integration to receive Data Subject Request (DSR) erasure requests. In order for Firehose partners to opt-in to DSR support, a DSR Processing Registration
should be specified with the following information:
Domain
should be defined in DsrRegistration
, It is used to make Callback requests. For more information on Callbacks, go here.DSR Processing Request Type
is required. Currently, the only supported request type is Erasure
.Refer to the sample project or the simple example below, which shows how to subscribe for Event Processing, Audience and DSR Processing:
@Override
public ModuleRegistrationResponse processRegistrationRequest(ModuleRegistrationRequest request) {
// Set the permissions, including the identities that this service can have access to
Permissions permissions = new Permissions();
permissions
.setAllowAccessLocation(false)
.setAllowAccessIpAddress(false)
.setAllowAccessMpid(true)
.setAllowAccessDeviceApplicationStamp(false)
.setAllowConsentState(true)
.setDeviceIdentities(Arrays.asList(
new DeviceIdentityPermission(DeviceIdentity.Type.IOS_ADVERTISING_ID, Identity.Encoding.RAW, true),
new DeviceIdentityPermission(DeviceIdentity.Type.GOOGLE_ADVERTISING_ID, Identity.Encoding.RAW, true)
))
.setUserIdentities(Arrays.asList(
new UserIdentityPermission(UserIdentity.Type.EMAIL, Identity.Encoding.RAW),
new UserIdentityPermission(UserIdentity.Type.CUSTOMER, Identity.Encoding.RAW)
))
.setPartnerIdentities(Collections.singletonList(
new PartnerIdentityPermission("[partner name]_[id name]", Identity.Encoding.RAW, false)
));
// The extension needs to define the settings it needs in order to connect to its respective service(s).
// You can use different settings for Event Processing, Audience Processing or DSR Processing, but in this case
// we'll just use the same object, specifying that only an API key is required for each.
List<Setting> settings = Arrays.asList(
new TextSetting("apiKey", "API Key")
.setIsRequired(true)
.setIsConfidential(true)
.setDescription("Your API key issued by <insert company here>.")
);
// Specify the supported event types. You should override the parent MessageProcessor methods
// that correlate to each of these event types.
List<Event.Type> supportedEventTypes = Arrays.asList(
Event.Type.CUSTOM_EVENT,
Event.Type.PROMOTION_ACTION,
Event.Type.PRODUCT_ACTION);
// This extension only supports event data coming from Android and iOS devices
List<RuntimeEnvironment.Type> environments = Arrays.asList(
RuntimeEnvironment.Type.ANDROID,
RuntimeEnvironment.Type.IOS);
// Set the Event Registration by using all of the above
EventProcessingRegistration eventRegistration = new EventProcessingRegistration();
OAuth2Authentication eventAuthentication = new OAuth2Authentication();
eventAuthentication
.setAuthorizationUrl("Authorization URL")
.setRefreshUrl("Refresh URL")
.setTokenUrl("Token URL")
.setGrantType(OAuth2Authentication.GrantType.AUTHORIZATION_CODE)
.setDefaultExpiresIn(2000)
.setClientId("Client ID")
.setAccessTokenType(OAuth2Authentication.AccessTokenType.CUSTOM_HEADER)
.setCustomHeaderName("Custom Header Name")
.setParamClientIdName("Param Client ID Name")
.setParamSecretName("Param Secret Name")
.setScopes(new ScopeDetail[]{new ScopeDetail()
.setName("Scope Name")
.setDescription("Scope Description")
});
eventRegistration
.setMaxDataAgeHours(24)
.setSupportedRuntimeEnvironments(environments)
.setSupportedEventTypes(supportedEventTypes)
.setAccountSettings(settings)
.setAuthentication(eventAuthentication);
// Set the audience subscription settings
List<Setting> subscriptionSettings = Arrays.asList(
new IntegerSetting(SETTING_MAILING_LIST_ID, "Mailing List ID"),
new IntegerSetting(SETTING_INTERNAL_LIST_ID, "Internal ID")
.setIsVisible(false)
);
// Set up Audience Registration.
AudienceProcessingRegistration audienceRegistration = new AudienceProcessingRegistration();
OAuth2Authentication audienceAuthentication = new OAuth2Authentication();
audienceAuthentication
.setAuthorizationUrl("Authorization URL")
.setRefreshUrl("Refresh URL")
.setTokenUrl("Token URL")
.setGrantType(OAuth2Authentication.GrantType.AUTHORIZATION_CODE)
.setDefaultExpiresIn(2000)
.setClientId("Client ID")
.setAccessTokenType(OAuth2Authentication.AccessTokenType.CUSTOM_HEADER)
.setCustomHeaderName("Custom Header Name")
.setParamClientIdName("Param Client ID Name")
.setParamSecretName("Param Secret Name")
.setScopes(new ScopeDetail[]{new ScopeDetail()
.setName("Scope Name")
.setDescription("Scope Description")
});
// Segmentation/Audience registration and processing is treated separately from Event processing.
// Audience integrations are configured separately in the mParticle UI.
// Customers can configure a different set of account-level settings (such as API key here), and
// Segment-level settings (Mailing List ID here).
audienceRegistration
.setAudienceConnectionSettings(subscriptionSettings)
.setAccountSettings(settings)
.setAuthentication(audienceAuthentication);
// Specify the supported DSR request types.
List<DsrProcessingRequest.Type> supportedDsrTypes = Arrays.asList(DsrProcessingRequest.Type.Erasure);
// Set up DSR Registration
DsrProcessingRegistration dsrRegistration = new DsrProcessingRegistration();
dsrRegistration
.setAccountSettings(settings)
.setDomain("yourdomain.com")
.setSupportedDsrTypes(supportedDsrTypes);
// Set the response
ModuleRegistrationResponse response = new ModuleRegistrationResponse("Your Company Name", "1.0");
response
.setDescription("A description of your <a href=''>company</a> and services. Inline HTML markup is permitted.")
.setEventProcessingRegistration(eventRegistration)
.setAudienceProcessingRegistration(audienceRegistration)
.setDsrProcessingRegistration(dsrRegistration)
.setPermissions(permissions);
return response;
}
Once you have completed the implementation of your registration, you must send the result to mParticle for verification. See testing for more information.
mParticle customers send batches of events to the mParticle platform via the mParticle SDKs (iOS, Android, Javascript, etc), direct Events data or feeds. mParticle can forward these event batches to your integration. The base MessageProcessor
implementation is designed to handle these incoming batches of events, and appropriately iterate over each different event, providing you with convenient hooks in which to handle each distinct event type.
In order to process these events, you’ll override (in your MessageProcessor
subclass) the appropriate method given the event types that you registered for during module registration.
Each event hook method is given an object that contains the event itself as well as information about the user, device, and application that fired the event.
See here for more on the Event
object from which all other events inherit.
The following table shows the correlation between each type and overridable method:
Event Type | Method |
---|---|
APPLICATION_STATE_TRANSITION |
MessageProcessor#processApplicationStateTransitionEvent |
ATTRIBUTION |
MessageProcessor#processAttributionEvent |
CUSTOM_EVENT |
MessageProcessor#processCustomEvent |
ERROR |
MessageProcessor#processErrorEvent |
IMPRESSION |
MessageProcessor#processImpressionEvent |
PRIVACY_SETTING_CHANGE |
MessageProcessor#processPrivacySettingChangeEvent |
PRODUCT_ACTION |
MessageProcessor#processProductActionEvent |
PROMOTION_ACTION |
MessageProcessor#processPromotionActionEvent |
PUSH_MESSAGE_RECEIPT |
MessageProcessor#processPushMessageReceiptEvent |
PUSH_SUBSCRIPTION |
MessageProcessor#processPushSubscriptionEvent |
SCREEN_VIEW |
MessageProcessor#processScreenViewEvent |
SESSION_END |
MessageProcessor#processSessionEndEvent |
SESSION_START |
MessageProcessor#processSessionStartEvent |
USER_ATTRIBUTE_CHANGE |
MessageProcessor#processUserAttributeChangeEvent |
USER_IDENTITY_CHANGE |
MessageProcessor#processUserIdentityChangeEvent |
To ensure a continuous connection with your integration, mParticle will periodically send event processing requests, even if there are no new events to send. Your integration must be able to accept an empty events array and return a standard event processing response.
Custom flags will be sent to your integration when available for supported event types when the custom flag key prefix matches your integration’s module name. For more information, see the Custom Flags JSON reference.
The audience subscription event tells your integration when a new audience has been created, removed, and/or updated in the mParticle platform. The response allows you to set additional subscription settings that will be stored together with the subscription and sent back with audience membership changes. All subscription settings must be declared during module registration.
See here for more info on the AudienceSubscriptionRequest
object that you’ll be given to parse the event.
The audience membership change event tells your integration whenever users are added or removed from a given audience. If you have set permissions.setAllowAudienceUserAttributeSharing(true)
, each audience will also include any user attributes the customer has shared.
See here for more info on the AudienceMembershipChangeRequest
object that you’ll be given to parse the event.
To ensure a continuous connection with your integration, mParticle will periodically send audience membership change requests, even if there are no new changes in audience membership. Your integration must be able to accept an empty audience membership change request (a request with no “user_profiles” fields, as shown below) and return a standard audience membership change response. If a user’s configuration should be faulted due to a non-transient error (an expired API token, for example), you can set suspend_subscription
to true
in the response. This will stop mParticle from sending requests until the user resumes the configuration.
{
"type":"audience_membership_change_request",
"id":"61414618-9724-40ef-b03c-f646c95552a8",
"timestamp_ms":1583958296525,
"firehose_version":"2.1.1",
"account":{
"account_id": 123456,
"account_settings":{
"Example String Setting" : "Example Setting Value"
}
}
}
mParticle supports the forwarding of Data Subject Requests (DSRs) for deletion of user data downstream, complying with both the General Data Protection Regulation (GDPR) and the California Consumer Privacy Act (CCPA). Note, once a request is forwarded downstream, mParticle is not liable for data deletion for any configured partners. Results will be explicitly indicated in our UI. To learn more about mParticle’s DSR support, go here. To process the DSR request, at least one supported identity type must be present in the request.
See here for more info on the DsrProcessingRequest
that the integration will receive.
mParticle’s DSR implementation currently only handles the Erasure
request type.
The identity types supported for DSR integrations are:
Identity Type | Description |
---|---|
CONTROLLER_CUSTOMER_ID |
Controller Customer Id |
ANDROID_ADVERTISING_ID |
The user’s Android Advertising Id |
ANDROID_ID |
The user’s Android Id |
EMAIL |
The user’s Email Address |
FIRE_ADVERTISING_ID |
The user’s Fire Advertising Id |
IOS_ADVERTISING_ID |
The user’s iOS Advertising Id |
IOS_VENDOR_ID |
The user’s iOS Vendor Id |
MICROSOFT_ADVERTISING_ID |
The user’s Microsoft Advertising Id |
MICROSOFT_PUBLISHER_ID |
The user’s Microsoft Publisher Id |
ROKU_PUBLISHER_ID |
The user’s Roku Publisher Id |
ROKU_ADVERTISING_ID |
The user’s Roku Advertising Id |
Prior to deployment, please send mParticle the JSON result of your registration response. There are several ways to easily acquire the JSON:
The latest Firehose Sample integration includes a unit test which will output the result of your registration function. See the Sample Firehose Integration README for more information. This is the quickest way to verify the contents of your module registration.
If you’re unable to run the unit tests, you may also deploy your function to AWS and then use this sample JSON (also available here) as a test event within the AWS console:
{
"type":"module_registration_request",
"id":"76e558fa-f456-437c-bb81-e658f75a7bd9",
"timestamp_ms":1446250094767
}
In order to ensure that your lambda function works correctly, we recommend unit testing prior to deployment. Unit testing is quicker and easier than manually sending in JSON to your lambda function via AWS.
You can send JSON messages manually into your lambda function via the AWS-lambda console.
See here for sample JSON that you can use.
Once you’ve completed development and feel you’ve sufficiently tested your integration, the next step is to register and add it to the mParticle platform. This is a multistep process:
You will need to grant mParticle permissions to call your lambda function. Using the Amazon CLI tool, execute the commands below, altering them for your environment:
--function-name
argument (arn:aws:lambda:us-east-1:123456789:function:myLambdaFunction:production
) to the full ARN of your lambda function. This can be found by navigating to your AWS Lambda console and selecting your lambda function.statement-id
must be unique - if you receive an error stating that the provided statement-id
already exists, increment the statement-id(s) to a higher value.aws lambda add-permission \
--region us-east-1 \
--function-name arn:aws:lambda:us-east-1:123456789:function:myLambdaFunction:production \
--statement-id 1 \
--principal 338661164609 \
--action lambda:InvokeFunction
aws lambda add-permission \
--region us-east-1 \
--function-name arn:aws:lambda:us-east-1:123456789:function:myLambdaFunction:production \
--statement-id 2 \
--principal 457804467337 \
--action lambda:InvokeFunction
For HTTP integrations, your endpoint must be able to receive HTTP requests.
Once permissions have been granted, mParticle will use an internal tool to send a registration request to your integration. We will work with you to ensure that your registration response looks correct and that it includes what’s necessary for your service.
mParticle requires a high-resolution logo to represent your service in our dashboard. The logo must:
Provide mParticle with credentials for the required fields from your registration response for testing configuration.
Once your integration has been registered and added to the mParticle platform, we will work with you to perform final testing prior to making your service available to all mParticle customers.
mParticle servers will stream data to your function at the same rate at which it is received. By default, AWS lambda allows for 100 concurrent executions of your function. If your lambda function reaches this limit, mParticle will continually retry requests with a back-off until they have succeeded. If you are expecting a large customer integration, it is recommended that you request a higher limit by opening a case with AWS Support.
See here for more information on AWS rate limiting and how to increase your limit.
Keep this in mind as you’re developing your lambda function as it may determine how it should process and to which of your APIs you should send data. Data rate and volume will depend on:
For HTTP Integrations, you will need to have infrastructure in place to support a high volume of data.
Was this page helpful?