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
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
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
Compose ID
Data Hosting Locations
Glossary
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 (Snowplow Schema)
AWS S3 Integration (Define Your Own 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 mParticle JSON schema defines the structure of all data sent to the mParticle customer data platform from the HTTP API or the platform SDKs (such as the Web, iOS, or Android SDKs).
This same JSON schema also defines the structure of data sent from mParticle to output integrations. There are some differences between the format for inbound and outbound data. For a complete list of these differences, see differences between the inbound and outbound JSON format.
The following document includes several additional explanations and examples. Use the following raw JSON schema definitions for programmatic JSON generation and validation:
See JSON schema validation for information about using these schemas to test and validate data structure.
{
"events": [
{
"data": {},
"event_type": "custom_event"
}
],
"device_info": {},
"source_request_id":"7fa67be4-f83a-429f-9d73-38b660c50825",
"user_attributes": {},
"deleted_user_attributes": [],
"user_identities": {},
"application_info": {},
"schema_version": 2,
"environment": "production",
"context": {},
"mpid":7346244611012968789,
"ip": "172.217.12.142"
}
All properties are optional and support both input and output unless specified otherwise in the Description.
Property | Data Type | Description |
---|---|---|
events | array | An array of JSON objects, each representing an event. The event object consists of two nodes: data , and type . The type indicates the entity structure of the data node. |
schema_version | integer | Output only. This value is used internally by mParticle account representatives. It indicates the current schema version a message batch conforms to. |
device_info | object | A JSON object containing information about the device pertaining to this message batch. |
application_info | object | A JSON object of information about your app. |
source_request_id | string | A value to uniquely identify this request. This is used to deduplicate inbound requests. De-duplication is scoped by API key, found in Organization/Account/Workspace/Inputs, and remains in the system for enforcement anywhere from 30-60 days. Any valid string is accepted. |
user_attributes | object map | String key-value pairs of demographic information about the user that generated the app events. |
deleted_user_attributes | string array | An array of JSON strings describing previously provided user attributes which should be forgotten. |
user_identities | object map | String key-value pairs of user ID information, such as email address and social IDs. |
partner_identities | object map | String key-value pairs of partner identities. |
integration_attributes | object map | String key-value pairs of integration attributes indexed by module. |
environment | enum string | Default value: production . Must be either “production” or “development.” |
context | object | Data planning and location information. |
mpid | long | If known, the unique mParticle identifier for the user, calculated based on user and device identities in the batch, according to your Identity Strategy. |
ip | string | Input only. The IPv4 / IPv6 address of the consumer device. The IP address is stored on user profiles and is kept updated with the most recently seen value for each user. ip is only forwarded to connected outputs if the Enrich IP Address setting is available and enabled for the connection. |
events
The event object consists of two required nodes: data, and event_type.
{
"data": {},
"event_type": ""
}
The following event_type are allowed. These values are specified in the type fields within the events node.
event_type | Description |
---|---|
custom_event | A Custom event with a name and optional attributes. |
commerce_event | A Commerce event. |
session_start | Session Start event. |
session_end | Session End event. |
screen_view | Screen View. |
uninstall | App was uninstalled. |
crash_report | Crash Report. |
opt_out | User Opt-Out. |
push_registration | Registration of the device push token. |
application_state_transition | An event fired when the application starts, exits, comes into foreground, or enters background. |
push_message | A push message is received. |
network_performance | An event containing network performance details on external http calls made from the application. |
breadcrumb | Breadcrumbs are used for crash reporting to understand which events lead up to a crash. |
The type indicates the entity structure of the data node in the event. There are also some common elements to all data nodes.
{
"data": {
"event_id": 6004677780660780000,
"event_num": 0,
"source_message_id": "e8335d31-2031-4bff-afec-17ffc1784697",
"session_id": 4957918240501247982,
"session_uuid": "91b86d0c-86cb-4124-a8b2-edee107de454",
"timestamp_unixtime_ms": 1402521613976,
"location": {},
"device_current_state": {},
"custom_attributes": {},
"custom_flags": {}
},
"event_type": ""
}
Property | Data Type | Required | Description |
---|---|---|---|
event_id | Int64 | Read only | Unique ID generated by mParticle server as each event is received. |
event_num | Int64 | Read only, optional for S2S | Zero-based number indicating an event’s place within the current session. In a session with a single event, event_num will be 0. The iOS and Android SDKs populate event_num automatically, but for S2S connections developers should manually calculate and populate this value if desired. |
source_message_id | string | suggested | Unique Id of source event. Generated by mParticle client-side SDKs for platform data. For session start events, SDKs set this value to session_uuid. If sending data via Events API it is suggested to generate a UUID for each event. |
session_id | Int64 | Read only | Unique Id of session. |
session_uuid | string | suggested | An optional universally unique identifier for the session. The session_id will be derived from a hash of this value. |
timestamp_unixtime_ms | Int64 | suggested | Timestamp of event. The current server time will be used if not specified. |
location | location JSON | optional | The location the event occurred in. |
device_current_state | device_current_state JSON | optional | An object with a number of properties describing the state the device was in at the time the event was logged. See below for further details. |
custom_attributes | JSON key value pairs | optional | A dictionary of custom attributes. If the Event API is called using Custom or Partner feed credentials, the mParticle Source Feed custom attribute is included which contains the name of the input feed configuration. This attribute cannot be filtered. |
The details on location and device_current_state will be detailed after additional information on the event_type and the corresponding data nodes.
{
"data": {
"event_name": "click",
"custom_event_type": "navigation",
"event_id": 6004677780660780000,
"source_message_id": "e8335d31-2031-4bff-afec-17ffc1784697",
"session_id": 4957918240501247982,
"session_uuid": "91b86d0c-86cb-4124-a8b2-edee107de454",
"timestamp_unixtime_ms": 1402521613976,
"location": {},
"device_current_state": {},
"custom_attributes": {
"button_name": "home",
"other_attribute": "xyz"
}
},
"event_type": "custom_event"
}
Property | Data Type | Required | Description |
---|---|---|---|
event_name | string | required | The name of the event |
custom_event_type | string or enum | required | The type of custom event as detailed in the following table. |
custom_flags | JSON key-value pairs | optional | A dictionary of custom flags. For more information, see Custom Flags. |
The values for custom_event_type
appear in the criteria builder for audiences, journeys, and the Custom Events calculated attributes drop-down. For example, custom_event_type
:media
appears as Media in the criteria builder for audiences and in the Select Event drop-down under Custom Events for calculated attributes.
The allowed values of “custom_event_type” are:
custom_event_type | Description |
---|---|
attribution | Attribution events are set of user actions (“events” or “touch points”) that contribute in some manner to a desired outcome. |
location | Events that indicate where a user is located or interacting physically. Examples might include a check-in, geo fence, or GPS navigation. |
media | Events for logging user media and ad content consumption and user initiated player event attributes. |
navigation | Events that indicate a user click sequence or content consumption. Examples might include interface navigation, music listening, video view, menu or tab Selection, or when the back button is pressed. |
search | Any event where users input criteria to find content/answers. Examples might include a keyword search, voice search, or a QR code scan. |
social | Any action where users share content with others. Examples might include post, rate, tweet, share, attach, email. |
transaction | Any events that are part of a transaction workflow. Examples might include selecting a product, subscribe, upgrade, or bid. |
user_content | Events where users are creating content. Examples might include create task, compose, record, scan, or save. |
user_preference | Any event that creates personalization for the user. This includes registration, saving/labeling content items, creating profiles, setting application preferences or permissions. |
other | Use this event type to create an event that falls into no clear category. |
Attribution events are sent to mParticle as custom events with:
Property | Value |
---|---|
event_type | custom_event |
custom_event_type | attribution |
The custom event_name depends on the Attribution Type:
Attribution Type | event_name | Description |
---|---|---|
Install | attribution | Install attribution events allow you to attribute the install of your app to a specific publisher and campaign. The publisher and campaign information is stored on the user’s profile and the events are available in the audience builder. Install attribution events require campaign and publisher custom attributes representing the campaign and publisher which are credited for the installation. You should also include as many device and user identifiers as you can. |
Re-engagement | re-engagement | Re-engagement attribution events are typically created when a user opens an app which has already been installed as a result of clicking a deep link. Re-engagement attribution events can also accept campaign and publisher attributes. Re-engagement attribution information is not stored on the user profile. |
Engagement | any | Engagement attribution events allow you to attribute actions (i.e. add to cart, purchase, etc) a user takes in the app to a specific publisher and campaign. Engagement attribution events can also accept campaign and publisher attributes. Engagement attribution information is not stored on the user profile. |
{
"data": {
"product_action": {},
"promotion_action": {},
"product_impressions": [{}],
"shopping_cart": {},
"currency_code": "USD",
"screen_name": "",
"is_non_interactive": false,
"event_id": 6004677780660780000,
"source_message_id": "e8335d31-2031-4bff-afec-17ffc1784697",
"session_id": 4957918240501247982,
"session_uuid": "91b86d0c-86cb-4124-a8b2-edee107de454",
"timestamp_unixtime_ms": 1402521613976,
"location": {},
"device_current_state": {},
"custom_attributes": {}
},
"event_type": "commerce_event"
}
There are 3 core variations of the commerce_event.
Property | Data Type | Required | Description |
---|---|---|---|
product_action | product_action JSON | required or disallowed (see above) | Used to measure measured data points associated with one or more products |
promotion_action | promotion_action JSON | required or disallowed (see above) | Used to measure data points associated with internal promotions or campaigns |
product_impressions | An array of JSON product_impressions | required or disallowed (see above) | Product impressions |
shopping_cart | shopping_cart JSON | optional | current shopping cart state |
currency_code | string | optional | code representing the currency the transaction is conducted in |
screen_name | string | optional | screen name |
is_non_interactive | Boolean | optional | is non interactive |
{
"action": "add_to_cart",
"checkout_step": 3,
"checkout_options": "",
"product_action_list": "",
"product_list_source": "",
"transaction_id": "",
"affiliation": "",
"total_amount": "",
"tax_amount": "",
"shipping_amount": "",
"coupon_code": "",
"products": [{}]
}
Property | Data Type | Required | Description |
---|---|---|---|
action | string / enum | required | The type of action the descriptions are below |
checkout_step | Int32 | optional | The step of the checkout process |
checkout_options | string | optional | checkout options |
product_action_list | string | optional | product action list |
transaction_id | string | optional | transaction id |
affiliation | string | optional | affiliation |
total_amount | decimal | optional | total amount (mapped from revenue in the SDKs) |
tax_amount | decimal | optional | tax amount (mapped from tax in the SDKs) |
shipping_amount | decimal | optional | shipping amount (mapped from shipping in the SDKs) |
coupon_code | string | optional | coupon code |
products | An array of JSON Product | optional | products |
The allowed values of “action” are:
add_to_cart
remove_from_cart
checkout
checkout_option
click
view_detail
purchase
refund
add_to_wishlist
remove_from_wish_list
{
"action": "view",
"promotions": [{}]
}
Property | Data Type | Required | Description |
---|---|---|---|
action | string / enum | required | Type of action. Allowed values are view and click . |
promotions | An array of JSON Promotion | optional | promotions |
{
"product_impression_list": "",
"products": [{}]
}
Property | Data Type | Required | Description |
---|---|---|---|
product_impression_list | string | optional | List of product impressions. |
products | array of objects | optional | An array of JSON objects, where each object contains a product. |
{
"products": [{}]
}
Property | Data Type | Required | Description |
---|---|---|---|
products | array of objects | optional | An array of JSON objects, where each object contains a product. |
{
"id": "",
"name": "",
"brand": "",
"category": "",
"variant": "",
"position": "",
"price": "",
"quantity": "",
"coupon_code": "",
"added_to_cart_time_ms": "",
"total_product_amount": "",
"custom_attributes": {}
}
Property | Data Type | Required | Description |
---|---|---|---|
id | string | optional | id |
name | string | optional | name |
brand | string | optional | brand |
category | string | optional | category |
variant | string | optional | variant |
position | Int32 | optional | position |
price | decimal | optional | price |
quantity | decimal | optional | quantity |
coupon_code | string | optional | coupon code |
added_to_cart_time_ms | Int64 | optional | Added to card milliseconds since epoch |
total_product_amount | decimal | optional | total product amount |
custom_attributes | JSON key value pairs | optional | A dictionary of custom attributes |
{
"id": "",
"name": "",
"creative": "",
"position": ""
}
Property | Data Type | Required | Description |
---|---|---|---|
id | string | optional | id |
name | string | optional | name |
creative | string | optional | creative |
position | string | optional | position |
{
"data": {
"event_id": 6004677780660780000,
"source_message_id": "e8335d31-2031-4bff-afec-17ffc1784697",
"session_id": 4957918240501247982,
"session_uuid": "91b86d0c-86cb-4124-a8b2-edee107de454",
"timestamp_unixtime_ms": 1402521613976,
"location": {},
"device_current_state": {}
},
"event_type": "session_start"
}
No additional fields are allowed in the data node.
{
"data": {
"session_duration_ms": 6000,
"custom_attributes": {
"button_name": "home",
"other_attribute": "xyz"
},
"event_id": 6004677780660780000,
"source_message_id": "e8335d31-2031-4bff-afec-17ffc1784697",
"session_id": 4957918240501247982,
"session_uuid": "91b86d0c-86cb-4124-a8b2-edee107de454",
"timestamp_unixtime_ms": 1402521613976,
"location": {},
"device_current_state": {}
},
"event_type": "session_end"
}
Property | Data Type | Required | Description |
---|---|---|---|
session_duration_ms | Int64 | optional | The length of the session in milliseconds. |
custom_attributes | JSON key value pairs | optional | A dictionary of custom attributes. |
{
"data": {
"screen_name": "Home",
"event_id": 6004677780660780000,
"source_message_id": "e8335d31-2031-4bff-afec-17ffc1784697",
"session_id": 4957918240501247982,
"session_uuid": "91b86d0c-86cb-4124-a8b2-edee107de454",
"timestamp_unixtime_ms": 1402521613976,
"location": {},
"device_current_state": {},
"custom_attributes": {}
},
"event_type": "screen_view"
}
Property | Data Type | Required | Description |
---|---|---|---|
screen_name | string | optional | The name of the screen |
{
"data": {
"event_id":6004677780660780000,
"source_message_id":"e8335d31-2031-4bff-afec-17ffc1784697",
"session_id":4957918240501247982,
"session_uuid":"91b86d0c-86cb-4124-a8b2-edee107de454",
"timestamp_unixtime_ms":1402521613976,
"location":{},
"device_current_state":{},
"custom_attributes": {}
},
"event_type":"uninstall"
}
No additional fields are allowed in the data node.
{
"data": {
"class_name": "NSInvalidArgumentException",
"breadcrumbs": [{}],
"severity": "fatal",
"message": "-[MPCViewController crash]: unrecognized selector sent to instance 0x125e0d3d0",
"stack_trace": "Example Stack Trace here",
"exception_handled": false,
"topmost_context": "MPCViewController",
"pl_crash_report_file_base64": "base64 string here",
"ios_image_base_address": 4295507968,
"ios_image_size": 535216,
"session_number": 25,
"event_id": 6004677780660780000,
"source_message_id": "e8335d31-2031-4bff-afec-17ffc1784697",
"session_id": 4957918240501247982,
"session_uuid": "91b86d0c-86cb-4124-a8b2-edee107de454",
"timestamp_unixtime_ms": 1402521613976,
"location": {},
"device_current_state": {},
"custom_attributes": {}
},
"event_type": "crash_report"
}
Property | Data Type | Required | Description |
---|---|---|---|
class_name | string | optional | Exception class name |
breadcrumbs | An array of breadcrumb events | optional | An array of breadcrumb events |
severity | string | optional | severity |
message | string | optional | Error message |
stack_trace | string | optional | Exception stack trace |
exception_handled | bool | optional | Determines if the exception was handled |
topmost_context | string | optional | Topmost context of the exception |
pl_crash_report_file_base64 | string | optional | Plausible Labs Crash Report file, as Base-64 string |
ios_image_base_address | unsigned Int64 | optional | iOS or tvOS image base address |
ios_image_size | unsigned Int64 | optional | iOS or tvOS image size |
session_number | int32 | optional | Session number that the crash occurred on |
{
"data": {
"is_opted_out": true,
"event_id": 6004677780660780000,
"source_message_id": "e8335d31-2031-4bff-afec-17ffc1784697",
"session_id": 4957918240501247982,
"session_uuid": "91b86d0c-86cb-4124-a8b2-edee107de454",
"timestamp_unixtime_ms": 1402521613976,
"location": {},
"device_current_state": {},
"custom_attributes": {}
},
"event_type": "opt_out"
}
Property | Data Type | Required | Description |
---|---|---|---|
is_opted_out | bool | suggested, false by default | is the user opted out |
{
"data": {
"register": true,
"registration_token": "x",
"event_id": 6004677780660780000,
"source_message_id": "e8335d31-2031-4bff-afec-17ffc1784697",
"session_id": 4957918240501247982,
"session_uuid": "91b86d0c-86cb-4124-a8b2-edee107de454",
"timestamp_unixtime_ms": 1402521613976,
"location": {},
"device_current_state": {},
"custom_attributes": {}
},
"event_type": "push_registration"
}
Property | Data Type | Required | Description |
---|---|---|---|
register | bool | required | Add/remove registration flag |
registration_token | string | required | Registration Token |
{
"data": {
"is_first_run": false,
"is_upgrade": false,
"successfully_closed": true,
"push_notification_payload": "{}",
"application_transition_type": "application_initialized",
"register": true,
"registration_token": "x",
"event_id": 6004677780660780000,
"source_message_id": "e8335d31-2031-4bff-afec-17ffc1784697",
"push_notification_payload":null,
"launch_referral":"https://www.mparticle.com/?utm_source=adwords&utm_medium=paid-search&utm_campaign=homepage-us-key-cities&utm_term=mparticle&utm_content=growth-api-demo&gclid=EAIaIQobChMIhpjBzpSR4gIVg42zCh33nwf_EAAYASAAEgIAWfD_BwE",
"session_id": 4957918240501247982,
"session_uuid": "91b86d0c-86cb-4124-a8b2-edee107de454",
"timestamp_unixtime_ms": 1402521613976,
"location": {},
"device_current_state": {},
"custom_attributes": {}
},
"event_type": "application_state_transition"
}
Property | Data Type | optional | Description |
---|---|---|---|
is_first_run | bool | optional | Set to true if this is on an install. Only use this field if the application_transition_type is application_initialized . |
is_upgrade | bool | optional | Set to true if this is on an upgrade. Only use this field if the application_transition_type is application_initialized . |
successfully_closed | bool | optional | Set to true if the previous session successfully closed |
push_notification_payload | string | optional | Push notification message data in JSON format |
application_transition_type | string / enum | required | Accepted values are application_initialized , application_exit , application_background , or application_foreground |
launch_referral | string | optional | A string representing the referral URL that triggered the most recent app foreground and web navigation |
{
"data": {
"push_message_token": "x",
"push_message_type": "action",
"message": "Message Text to consumer",
"network": "apn",
"push_notification_payload": "{}",
"application_state": "foreground",
"action_identifier": "action",
"push_message_behavior": 2,
"event_id": 6004677780660780000,
"source_message_id": "e8335d31-2031-4bff-afec-17ffc1784697",
"session_id": 4957918240501247982,
"session_uuid": "91b86d0c-86cb-4124-a8b2-edee107de454",
"timestamp_unixtime_ms": 1402521613976,
"location": {},
"device_current_state": {},
"custom_attributes": {}
},
"event_type": "push_message"
}
Property | Data Type | Required | Description |
---|---|---|---|
push_message_token | string | optional | Push Message Token |
push_message_type | string / enum | required | “sent”, “received”, “action” |
message | string | optional | The text displayed in push message |
network | string / enum | suggested | “apn” for apple push notifications, “gcm” for google cloud messaging |
push_notification_payload | string | optional | push notification message data in JSON format |
application_state | string / enum | optional | “not_running”, “background”, or “foreground” |
action_identifier | string | optional | action identifier, 100 character limit |
push_message_behavior | integer | optional | Bit mask representing the behaviors that have been so far observed for the given push message. |
{
"data": {
"http_verb": "GET",
"url": "http://sample.url",
"time_elapsed": 450,
"bytes_in": 2048,
"bytes_out": 2048,
"response_code": "200",
"data": "",
"event_id": 6004677780660780000,
"source_message_id": "e8335d31-2031-4bff-afec-17ffc1784697",
"session_id": 4957918240501247982,
"session_uuid": "91b86d0c-86cb-4124-a8b2-edee107de454",
"timestamp_unixtime_ms": 1402521613976,
"location": {},
"device_current_state": {},
"custom_attributes": {}
},
"event_type": "network_performance"
}
Property | Data Type | Required | Description |
---|---|---|---|
http_verb | string | optional | HTTP Verb |
url | string | optional | URL |
time_elapsed | Int32 | optional | time elapsed during network call |
bytes_in | Int32 | optional | Bytes in |
bytes_out | Int32 | optional | Bytes out |
response_code | string | optional | Http response code |
data | string | optional | Base64 string |
{
"data": {
"session_number": 45,
"label": "label",
"event_id": "6004677780660780000",
"source_message_id": "e8335d31-2031-4bff-afec-17ffc1784697",
"session_id": 4957918240501247982,
"session_uuid": "91b86d0c-86cb-4124-a8b2-edee107de454",
"timestamp_unixtime_ms": 1402521613976,
"location": {},
"device_current_state": {},
"custom_attributes": {}
},
"event_type": "breadcrumb"
}
Property | Data Type | Required | Description |
---|---|---|---|
session_number | Int32 | optional | Session number |
label | string | required | Label |
location
Note this is the location for an event, not an event batch. For information on setting event batch location, see Context.
{
"location": {
"latitude": 40.7142,
"longitude": 74.0064,
"accuracy": 195.0165104914573,
"country_code": "US",
"region_code": "NY",
"city_name": "New York",
"postal_code": "10010",
"dma_code": 501,
"location_source": "lat_long"
}
}
Property | Data Type | Required | Description |
---|---|---|---|
latitude | double | optional | Latitude |
longitude | double | optional | Longitude |
accuracy | double | optional | Accuracy in meters. For example, an accuracy of 50 means the device is within 50 meters of the specified latitude and longitude. |
country_code | string | optional | Two letter ISO 3166-1 country code |
region_code | string | optional | Subdivision portion of the ISO 3166-2 code |
city_name | string | optional | City name |
postal_code | string | optional | Postal code |
dma_code | Int32 | optional | DMA code |
location_source | string | optional | One of “unknown”, “ip_lookup”, or “lat_long” |
context
{
"context": {
"data_plan": {
"plan_id": "mobile_data_plan",
"plan_version": 2
},
"location": {
"latitude": 40.7142,
"longitude": 74.0064,
"accuracy": 195.0165104914573,
"country_code": "US",
"region_code": "NY",
"city_name": "New York",
"postal_code": "10010",
"dma_code": 501,
"location_source": "lat_long"
}
}
}
The context field lets you enable additional mParticle features such as Data Planning. By providing your plan’s id and version, you can start validating incoming data against your expectations. Learn more about Data Planning here.
Property | Data Type | Required | Description |
---|---|---|---|
plan_id | string | optional | The Id of your data plan |
plan_version | Int32 | optional | The version of your data plan, if omitted the latest version of the plan_id will be used. |
The context field also lets you specify a location for an event batch. Location can be set automatically for some outputs if none is specified. Location is set from the first event with a valid location or IP if there are no events with valid locations.
Property | Data Type | Required | Description |
---|---|---|---|
latitude | double | optional | Latitude |
longitude | double | optional | Longitude |
accuracy | double | optional | Accuracy in meters. For example, an accuracy of 50 means the device is within 50 meters of the specified latitude and longitude. |
country_code | string | optional | Two letter ISO 3166-1 country code |
region_code | string | optional | Subdivision portion of the ISO 3166-2 code |
city_name | string | optional | City name |
postal_code | string | optional | Postal code |
dma_code | Int32 | optional | DMA code |
location_source | string | optional | One of “unknown”, “ip_lookup”, or “lat_long” |
custom_flags
{
"custom_flags": {
"Google.Category": "pageview",
"Google.Label": "main:mktg:personal::home",
"Google.Value": "123"
}
}
Custom flags are:
Reference the guide for each integration to see if you need to instrument custom flags. Custom flags are supported by the following partners:
device_current_state
{
"device_current_state": {
"cpu": "4",
"system_memory_available_Bytes": 536903680.0,
"system_memory_low": false,
"system_memory_threshold_bytes": 56590336,
"application_memory_available_bytes": 6995328,
"application_memory_max_bytes": 67108864,
"application_memory_total_bytes": 17604608.0,
"device_orientation": "undefined",
"status_bar_orientation": "undefined",
"time_since_start_ms": 5515182,
"battery_level": 0.95,
"data_connection_type": "wifi",
"data_connection_type_detail": "hdspa",
"gps_state": true,
"total_system_memory_usage_bytes": 2980528128,
"disk_space_free_bytes": 29716148224,
"external_disk_space_free_bytes": 10121
}
}
Property | Data Type | Required | Description |
---|---|---|---|
cpu | string | optional | CPU utilization in integer form |
system_memory_available_bytes | double | optional | Total bytes of system memory available |
system_memory_low | bool | optional | Boolean to indicate whether system memory is low |
system_memory_threshold_bytes | optional | double | Android only |
application_memory_available_bytes | double | optional | Total bytes of application memory available |
application_memory_max_bytes | double | optional | Maximum bytes of application memory used |
application_memory_total_bytes | double | optional | Total bytes of memory application is currently using |
device_orientation | string / enum | optional | “portrait”, “landscape”, or “square” |
status_bar_orientation | string | optional | iOS only |
time_since_start_ms | Int64 | optional | Time in milliseconds since application was loaded |
battery_level | double | optional | Integer representation of battery percentage remaining |
data_connection_type | string / enum | optional | “offline”, “wifi”, or “mobile” |
data_connection_type_detail | string | optional | data connection type details |
gps_state | string / enum | optional | String value indicating whether GPS is enabled - Values: “unknown”, “true”, or “false” |
total_system_memory_usage_bytes | Int64 | optional | |
disk_space_free_bytes | Int64 | optional | Total number of bytes of disk space available |
external_disk_space_free_bytes | Int64 | optional | Android only |
device_info
{
"device_info": {
"brand": "iPhone6,1",
"product": "iPhone6,1",
"device": "John's iPhone 5s",
"android_uuid": null,
"device_manufacturer": "Apple",
"platform": "iOS",
"os_version": "7.1.1",
"device_model": "iPhone6,1",
"screen_height": 1136,
"screen_width": 640,
"screen_dpi": 160,
"device_country": "USA",
"locale_language": "en",
"locale_country": "US",
"network_country": "us",
"network_carrier": "AT&T",
"network_code": "410",
"network_mobile_country_code": "310",
"timezone_offset": -4,
"build_identifier": "M4-rc20",
"http_header_user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 7_1 like Mac OS X) AppleWebKit/537.51.2 (KHTML, like Gecko) Mobile/11D167 mParticle/2.5.0",
"ios_advertising_id": "613ff528-afd1-4c1b-9628-e6ed25ece9c0",
"att_authorization_status": "authorized",
"att_timestamp_unixtime_ms": 1614187122051,
"push_token": "<e481f135 9629f0c3 fb634be0 82ca18b1 73ea45a2 b0b96a6e 2a00c829 bc9ff6eb>",
"cpu_architecture": "arm64",
"is_tablet": false,
"push_notification_sound_enabled": true,
"push_notification_vibrate_enabled": false,
"radio_access_technology": "LTE",
"supports_telephony": "",
"has_nfc": false,
"bluetooth_enabled": true,
"bluetooth_version": "",
"ios_idfv": "8c61383f-2216-4713-8c1c-1cb0a5d7a4cc",
"android_advertising_id": "",
"limit_ad_tracking": false,
"is_dst": false
}
}
Property | Data Type | Required | Description |
---|---|---|---|
brand | string | optional | Device Brand, e.g. Google |
product | string | optional | Product |
device | string | optional | Device Name |
android_uuid | string | optional | legacy Android ID |
device_manufacturer | string | optional | Device Manufacturer |
platform | string / enum | optional | Valid values: “iOS”, “Android”, “web”, “tvOS”, “roku”, “out_of_band”, “alexa”, “smart_tv”, “fire_tv”, “xbox” |
os_version | string / Version | optional | Major.Minor.Revision of OS, e.g. 7.1.1 |
device_model | string | optional | Name of Device Model, e.g. iPhone6,1 |
screen_height | Int32 | optional | Screen height in pixels |
screen_width | Int32 | optional | Screen width in pixels |
screen_dpi | Int32 | optional | Android only |
device_country | string | optional | Android only |
locale_language | string | optional | Current language device is set to |
locale_country | string | optional | Current locale device is set to |
network_country | string | optional | Country name data/cellular network bound to |
network_carrier | string | optional | network carrier |
network_code | string | optional | This is the mobile network code |
network_mobile_country_code | string | optional | Standardized country code of network bound to |
timezone_offset | Int32 | optional | This is the device’s timezone offset setting, in hours relative to UTC |
build_identifier | string | optional | Build UUID |
http_header_user_agent | string | optional | HTTP User Agent |
ios_advertising_id | GUID | optional | iOS and tvOS. Synonymous with Apple Identifier for Advertisers (IDFA). |
att_authorization_status | string / enum | optional | “authorized”, “denied”, “not_determined”, “restricted” |
att_timestamp_unixtime_ms | Int32 | optional | Specifies when the end-user first responded to the App Tracking Transparency prompt |
push_token | string | optional | Push messaging registration token |
cpu_architecture | string | optional | iOS and tvOS - CPU Architecture of device |
is_tablet | nullable bool | optional | True/False or null whether device is a tablet |
push_notification_sound_enabled | nullable bool | optional | Android only |
push_notification_vibrate_enabled | nullable bool | optional | Android only |
radio_access_technology | string | optional | radio access technology |
supports_telephony | nullable bool | optional | Android only |
has_nfc | nullable bool | optional | Android only |
bluetooth_enabled | nullable bool | optional | Android only |
bluetooth_version | string | optional | Android only |
ios_idfv | GUID | optional | iOS and tvOS only. Apple’s Identifier for Vendors (IDFV). |
android_advertising_id | GUID | optional | Android only. Synonymous with Google Advertising ID (GAID). |
roku_advertising_id | GUID | optional | Roku only |
roku_publisher_id | GUID | optional | Roku only |
microsoft_advertising_id | GUID | optional | UWP only |
microsoft_publisher_id | GUID | optional | UWP only |
fire_advertising_id | GUID | optional | Amazon Fire TV only |
limit_ad_tracking | nullable bool | optional | Limit Ad Tracking |
is_dst | nullable bool | optional | Is Daylight Savings Time |
application_info
{
"application_info": {
"application_name": "App Name",
"application_version": "1.0.1",
"application_build_number": "42",
"install_referrer": "utm_campaign=my_campaign&utm_source=google&utm_medium=cpc&utm_term=my_keyword&utm_content=ad_variation1",
"package": "com.mparticle.test",
"apple_search_ads_attributes": {
"Version3.1": {
"iad-lineitem-id": "9590781",
"iad-keyword": "foo",
"iad-org-name": "bar",
"iad-conversion-date": "11/04/2016 00:13:15",
"iad-attribution": "true",
"iad-adgroup-name": "Test Ad Group - Brand - Exact",
"iad-campaign-id": "123456",
"iad-adgroup-id": "654321",
"iad-lineitem-name": "Test Ad Group - Brand - Exact",
"iad-campaign-name": "Test Campaign - Brand",
"iad-click-date": "11/04/2016 00:13:09",
"iad-conversion-type": "Download",
"iad-keyword-matchtype": "Broad"
}
}
}
}
Property | Data Type | Required | Description |
---|---|---|---|
application_name | string | optional | Name of application |
application_version | string | optional | Version of application |
application_build_number | string | optional | Build of the application |
install_referrer | string | optional | Android Only - Provided by Google Play Store |
package | string | optional | Package name |
apple_search_ads_attributes | dictionary | optional | Apple App Store Search Ads attribution arguments |
user_attributes
The properties with the prefix ”$” are reserved attributes that drive specific behaviors in our platform. This object can also contain any number of custom user attributes that you can define from within your app. Custom attributes also allow for lists of values instead of scalar values, but in general a given attribute should not change between a scalar and a list in subsequent calls.
{
"user_attributes": {
"$age": "18",
"$gender": "M",
"$country": "USA",
"$zip": "10016",
"$city": "New York",
"$state": "NY",
"$address": "381 Park Avenue S",
"$firstname": "John",
"$lastname": "Doe",
"$mobile": "123-456-7890",
"a_custom_attribute": "some_value",
"a_custom_list": [
"value1",
"value2",
"valueN"
]
}
}
user_identities
{
"user_identities": {
"customer_id": "1234",
"email": "helpers@mparticle.com",
"facebook": "helpers@mparticle.com",
"twitter": "helpers@mparticle.com",
"google": "helpers@mparticle.com",
"microsoft": "helpers@mparticle.com",
"other": "helpers@mparticle.com",
"other_id_2": "helpers2@example.com",
"other_id_3": "helpers3@example.com",
"other_id_4": "helpers4@example.com",
"other_id_5": "helpers5@example.com",
"other_id_6": "helpers6@example.com",
"other_id_7": "helpers7@example.com",
"other_id_8": "helpers8@example.com",
"other_id_9": "helpers9@example.com",
"other_id_10": "helpers10@example.com",
"mobile_number": "800-555-1111",
"phone_number_2": "800-555-2222",
"phone_number_3": "800-555-3333"
}
}
partner_identities
Partner Identities are unique identifiers associated with a user, but specific to a partner system. They can be ingested by mParticle via Partner Feed or our S2S API, and can be sent to downstream connections associated with the given partner. A Partner Feed can only send in their registered partner identity, whereas a S2S request can include any partner identity.
{
"partner_identities": {
"partner_id": "1234"
}
}
Before a partner’s unique identity can be ingested, it must be registered with mParticle. Partners can register a new identity by either:
The naming convention for these identities is as follows: PartnerName_IdentityName
.
An example for mParticle could be: mParticle_mpid
integration_attributes
Integration attributes are unique values associated with a given user, for a given integration. They are generally required for the integration to function properly.
The JSON blob is indexed by Module ID
, meaning each integration can have its own values:
{
"integration_attributes": {
"123": {
"someIntegrationAttribute": "value"
}
}
}
In order to find out a given integration’s ID, you can check the corresponding URL
from the mParticle Directory.
consent_state
Used to communicate the GDPR consent state for the user. For GDPR, you must define the purposes (shown here as location_collection
and parental
) in the mParticle UI. For CCPA, only the below purpose is allowed and it does not need to be defined. Pass consented: true
to register a users opt-out to CCPA data sale.
{
"consent_state": {
"gdpr": {
"location_collection": {
"consented": true,
"document": "location_collection_agreement_v4",
"timestamp_unixtime_ms": 1523039002083,
"location": "17 Cherry Tree Lane",
"hardware_id": "IDFA:a5d934n0-232f-4afc-2e9a-3832d95zc702"
},
"parental": {
"consented": false,
"document": "parental_consent_agreement_v2",
"timestamp_unixtime_ms": 1523039002083,
"location": "17 Cherry Tree Lane",
"hardware_id": "IDFA:a5d934n0-232f-4afc-2e9a-3832d95zc702"
}
},
"ccpa": {
"data_sale_opt_out": {
"consented": true,
"document": null,
"timestamp_unixtime_ms": 1523039002083,
"location": null,
"hardware_id": null
}
}
}
}
source_info
This node is populated automatically by mParticle on receiving a batch. You do not need to send source_info
.
This node is available in the mParticle Rules environment, but all values are immutable.
{
"source_info": {
"channel": "server_to_server",
"partner": null,
"replay_request_id": null,
"replay_job_id": null,
"is_historical": true
}
}
Property | Data Type | Description |
---|---|---|
channel | string | Source the batch was received from. Valid values: “native”, “javascript”, “pixel”, “partner”, “server_to_server”, and “unknown”. |
partner | string | If the channel is Partner , this field is the name of the partner feed |
replay_request_id | string | If data is from a replay, unique ID for the replay request |
replay_job_id | string | If data is from a replay, unique ID for the replay job |
is_historical | string | If true, data was received via the historical endpoint. |
{
"environment": "production",
"device_info": {
"brand": "iPhone6,1",
"product": "iPhone6,1",
"device": "John's iPhone 5s",
"android_uuid": "",
"device_manufacturer": "Apple",
"platform": "iOS",
"os_version": "7.1.1",
"device_model": "iPhone6,1",
"screen_height": 1136,
"screen_width": 640,
"screen_dpi": 160,
"device_country": "USA",
"locale_language": "en",
"locale_country": "US",
"network_country": "us",
"network_carrier": "AT&T",
"network_code": "410",
"network_mobile_country_code": "310",
"timezone_offset": -4,
"build_identifier": "M4-rc20",
"http_header_user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 7_1 like Mac OS X) AppleWebKit/537.51.2 (KHTML, like Gecko) Mobile/11D167 mParticle/2.5.0",
"ios_advertising_id": "613ff528-afd1-4c1b-9628-e6ed25ece9c0",
"att_authorization_status": "authorized",
"att_timestamp_unixtime_ms": 1614187122051,
"push_token": "<e481f135 9629f0c3 fb634be0 82ca18b1 73ea45a2 b0b96a6e 2a00c829 bc9ff6eb>",
"cpu_architecture": "arm64",
"is_tablet": false,
"push_notification_sound_enabled": true,
"push_notification_vibrate_enabled": false,
"radio_access_technology": "LTE",
"supports_telephony": null,
"has_nfc": false,
"bluetooth_enabled": true,
"bluetooth_version": "",
"ios_idfv": "8c61383f-2216-4713-8c1c-1cb0a5d7a4cc",
"android_advertising_id": null,
"limit_ad_tracking": false,
"is_dst": false
},
"application_info": {
"application_name": "App Name",
"application_version": "1.0.1",
"application_build_number": "42",
"install_referrer": "utm_campaign=my_campaign&utm_source=google&utm_medium=cpc&utm_term=my_keyword&utm_content=ad_variation1",
"package": "com.newco.myapp"
},
"user_attributes": {
"$age": "18",
"$gender": "M",
"$country": "USA",
"$zip": "10016",
"$city": "New York",
"$state": "NY",
"$address": "381 Park Avenue S",
"$firstname": "John",
"$lastname": "Doe",
"$mobile": "123-456-7890",
"a_custom_attribute": "some_value",
"a_custom_list": [
"value1",
"value2",
"valueN"
]
},
"deleted_user_attributes": [
"an_old_attribute_name",
"another_old_attribute"
],
"user_identities": {
"customer_id": "1234",
"email": "helpers@mparticle.com",
"facebook": "helpers@mparticle.com",
"twitter": "helpers@mparticle.com",
"google": "helpers@mparticle.com",
"microsoft": "helpers@mparticle.com",
"alias": "helpers@mparticle.com",
"other": "helpers@mparticle.com"
},
"partner_identities": {
"partner_id": "1234"
},
"integration_attributes": {
"123": {
"key": "value"
}
},
"events": [
{
"data": {
"timestamp_unixtime_ms": 1432825980486,
"source_message_id": "4e34bef3-d2f9-4f07-8298-4646cce292fa",
"session_uuid": "DDFBEA89-9A54-41C3-97F3-334FDD3B98BC",
"session_id": 123141241343
},
"event_type": "session_start"
},
{
"data": {
"application_transition_type": "application_background",
"event_id": -1586912177303106600,
"session_uuid": "DDFBEA89-9A54-41C3-97F3-334FDD3B98BC",
"timestamp_unixtime_ms": 1402578873533,
"is_first_run": false,
"is_upgrade": true,
"successfully_closed": true,
"push_notification_payload": null,
"launch_referral": null,
"location": {
"latitude": 40.7142,
"longitude": 74.0064,
"accuracy": 195.0165104914573
},
"device_current_state": {
"time_since_start_ms": 713485,
"battery_level": -1,
"data_connection_type": "wifi",
"gps_state": true,
"total_system_memory_usage_bytes": 2981494784,
"disk_space_free_bytes": 29655015424,
"cpu": "0",
"system_memory_available_bytes": 182730752,
"application_memory_total_bytes": 17813504,
"device_orientation": 6,
"status_bar_orientation": 1
}
},
"event_type": "application_state_transition"
},
{
"data": {
"class_name": "NSInvalidArgumentException",
"severity": "fatal",
"message": "-[MPCViewController crash]: unrecognized selector sent to instance 0x125e0d3d0",
"stack_trace": "Example Stack Trace here",
"topmost_context": "MPCViewController",
"pl_crash_report_file_base64": "base64 string here",
"ios_image_base_address": 4295507968,
"ios_image_size": 535216,
"event_id": 1558493756361828400,
"timestamp_unixtime_ms": 1402579716192,
"location": {
"latitude": 40.7142,
"longitude": 74.0064,
"accuracy": 195.0165104914573
},
"device_current_state": {
"time_since_start_ms": 106554,
"battery_level": -1,
"data_connection_type": "wifi",
"gps_state": true,
"total_system_memory_usage_bytes": 2995585024,
"disk_space_free_bytes": 29653184512,
"cpu": "0",
"system_memory_available_bytes": 300056576,
"application_memory_total_bytes": 18108416,
"device_orientation": 6,
"status_bar_orientation": 1
}
},
"event_type": "crash_report"
},
{
"data": {
"timestamp_unixtime_ms": 1432825994215,
"session_duration_ms": 60000,
"source_message_id": "93862b36-adf3-43e6-87d2-2fcbf3f6d903",
"session_uuid": "DDFBEA89-9A54-41C3-97F3-334FDD3B98BC",
"custom_attributes": {
"key23": "value2"
}
},
"event_type": "session_end"
}
]
}
Described above is the format required for sending data to mParticle via the Events API. A very similar format is used to send data to event outputs that accept raw JSON, including:
For these forwarders, mParticle makes our output as complete as possible, including fields only used internally or fields that are set automatically by mParticle and not part of the inbound JSON reference. The most important difference between incoming and outgoing JSON is that the user_identities
field is expanded in the outgoing JSON to include additional information. In most other cases, additional fields added in the outgoing JSON are intended for internal use or to support edge cases and should be ignored unless you have a special need for these fields.
Some notable differences include:
batch_id
), and each event (message_id
). These are used by mParticle for internal processing tasks like de-duping.message_type
field to each event, which is used for internal processing.session_id
, session_uuid
and session_start_unixtime
.event_start_unixtime_ms
field. In almost all cases this will be the same as the main event timestamp_unixtime_ms
field. It exists to support timed event use cases.timestamp_unixtime_ms
— representing the time the batch was received by mParticle. This field is created by mParticle and should not be set manually when sending data via the Events API.activity_type
of activity_started
or activity_stopped
on Screen View events. This field is used by some event integrations to determine how to forward the event.system_notifications
field is currently used by mParticle to forward changes in consent state to some partners. In outbound JSON this field is present but empty unless you are instrumenting data privacy controls.unique_id
field if you enter a value for the Unique ID connection setting.In outgoing JSON, the user_identities
node is an array of identity objects. Each object contains the identity type, the value, and a timestamp showing when the identity was last updated. For example:
{
"user_identities": [
{
"identity_type": "customer_id",
"identity": "h.jekyll.md",
"timestamp_unixtime_ms": 1540483995196
},
{
"identity_type": "email",
"identity": "h.jekyll.md@example.com",
"timestamp_unixtime_ms": 1540483995196
}
]
}
mParticle’s server-side SDKs are designed to generate correct JSON in all cases. If you are unable to use mParticle’s SDKs, you can use the mParticle Events API JSON schema documents to validate your JSON prior to upload.
The following example uses the popular jsonschema
library and performs the following:
from jsonschema import validate, exceptions
import urllib.request, json
schema_url = "https://docs.mparticle.com/schema/mparticle.inbound.eventsapi.schema.json"
url = urllib.request.urlopen(schema_url)
schema = json.loads(url.read().decode())
bulk_schema_url = "https://docs.mparticle.com/schema/mparticle.inbound.eventsapi.bulk.schema.json"
bulk_url = urllib.request.urlopen(bulk_schema_url)
bulk_schema = json.loads(bulk_url.read().decode())
# Create a dictionary to be validated
instance = {
"source_request_id":"769D83CB-8C60-48F9-A0C1-C38CF1B40A4F",
"device_info": {
"ios_advertising_id":"1cc8138f-8aaf-410a-b0b9-6465cfb2af6a",
"ios_idfv":"0f129dcb-d5b9-450b-9003-a38a7b7e946d",
"att_authorization_status":"authorized",
"att_timestamp_unixtime_ms":1614187122051
},
"user_attributes":{ "Test attribute":"Test value" },
"user_identities":{ "customer_id":"123456" },
"environment":"production"
}
# You can also load an existing JSON string into a dictionary
# instance = json.loads("{}")
# If you're sending via the bulk endpoint, create an array of batches
bulk_instance = [instance]
try:
# If your JSON is badly formed, this will throw a ValidationError
validate(instance=instance, schema=schema)
validate(instance=bulk_instance, schema=bulk_schema)
except exceptions.ValidationError as e:
# Read more on ValidationError objects here:
# https://python-jsonschema.readthedocs.io/en/stable/errors/
print(e.message)
print(e.path)
See the JSON Schema specification homepage for more JSON Schema validation tools.
Was this page helpful?