Documentation

Developers

API References
Data Subject Request API

Data Subject Request API Version 1 and 2

Data Subject Request API Version 3

Platform API

Platform API Overview

Accounts

Apps

Audiences

Calculated Attributes

Data Points

Feeds

Field Transformations

Services

Users

Workspaces

Warehouse Sync API

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

Client SDKs
AMP

AMP SDK

Android

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

Cordova Plugin

Identity

Direct Url Routing

Direct URL Routing FAQ

Web

Android

iOS

Flutter

Getting Started

Usage

API Reference

React Native

Getting Started

Identity

Roku

Getting Started

Identity

Media

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

Xbox

Getting Started

Identity

Unity

Upload Frequency

Getting Started

Opt Out

Initialize the SDK

Event Tracking

Commerce Tracking

Error Tracking

Screen Tracking

Identity

Location Tracking

Session Management

Web

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

Xamarin

Getting Started

Identity

Web

Alexa

Server SDKs

Node SDK

Go SDK

Python SDK

Ruby SDK

Java SDK

Tools

mParticle Command Line Interface

Linting Tools

Smartype

Media SDKs

Android

Web

iOS

Quickstart
Android

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

HTTP Quick Start

Step 1. Create an input

Step 2. Create an output

Step 3. Verify output

iOS Quick Start

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

Java Quick Start

Step 1. Create an input

Step 2. Create an output

Step 3. Verify output

Node Quick Start

Step 1. Create an input

Step 2. Create an output

Step 3. Verify output

Python Quick Start

Step 1. Create an input

Step 2. Create an output

Step 3. Verify output

Web

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

Guides
Partners

Introduction

Outbound Integrations

Outbound Integrations

Firehose Java SDK

Inbound Integrations

Kit Integrations

Overview

Android Kit Integration

JavaScript Kit Integration

iOS Kit Integration

Data Hosting Locations

Compose ID

Glossary

Migrate from Segment to mParticle

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

Guides

Getting Started

Create an Input

Start capturing data

Connect an Event Output

Create an Audience

Connect an Audience Output

Transform and Enhance Your Data

Platform Guide
The New mParticle Experience

The new mParticle Experience

The Overview Map

Observability

Observability Overview

Observability User Guide

Observability Span Glossary

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)

Analytics

Introduction

Setup

Sync and Activate Analytics User Segments in mParticle

User Segment Activation

Welcome Page Announcements

Settings

Project Settings

Roles and Teammates

Organization Settings

Global Project Filters

Portfolio Analytics

Analytics Data Manager

Analytics Data Manager Overview

Events

Event Properties

User Properties

Revenue Mapping

Export Data

UTM Guide

Query Builder

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

Analyses Introduction

Segmentation: Basics

Getting Started

Visualization Options

For Clauses

Date Range and Time Settings

Calculator

Numerical Settings

Segmentation: Advanced

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

Funnels: Basics

Getting Started with Funnels

Group By Settings

Conversion Window

Tracking Properties

Date Range and Time Settings

Visualization Options

Interpreting a Funnel Analysis

Funnels: Advanced

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

Cohorts

Getting Started with Cohorts

Analysis Modes

Save a Cohort Analysis

Export Results

Explore Users

Saved Analyses

Manage Analyses in Dashboards

Journeys

Getting Started

Event Menu

Visualization

Ending Event

Save a Journey Analysis

Users

Getting Started

User Activity Timelines

Time Settings

Export Results

Save A User Analysis

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

Analytics Resources

The Demo Environment

Keyboard Shortcuts

Tutorials

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

APIs

User Segments Export API

Dashboard Filter API

IDSync

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

Data Master
Group Identity

Overview

Create and Manage Group Definitions

Introduction

Catalog

Live Stream

Data Plans

Data Plans

Blocked Data Backfill Guide

Personalization
Predictive Attributes

Predictive Attributes Overview

Create Predictive Attributes

Assess and Troubleshoot Predictions

Use Predictive Attributes in Campaigns

Predictive Audiences

Predictive Audiences Overview

Using Predictive Audiences

Introduction

Profiles

Calculated Attributes

Calculated Attributes Overview

Using Calculated Attributes

Create with AI Assistance

Calculated Attributes Reference

Audiences

Audiences Overview

Real-time Audiences

Standard Audiences

Journeys

Journeys Overview

Manage Journeys

Download an audience from a journey

Audience A/B testing from a journey

Journeys 2.0

Warehouse Sync

Data Privacy Controls

Data Subject Requests

Default Service Limits

Feeds

Cross-Account Audience Sharing

Approved Sub-Processors

Import Data with CSV Files

Import Data with CSV Files

CSV File Reference

Glossary

Video Index

Analytics (Deprecated)
Identity Providers

Single Sign-On (SSO)

Setup Examples

Settings

Debug Console

Data Warehouse Delay Alerting

Introduction

Developer Docs

Introduction

Integrations

Introduction

Rudderstack

Google Tag Manager

Segment

Data Warehouses and Data Lakes

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)

APIs

Dashboard Filter API (Deprecated)

REST API

User Segments Export API (Deprecated)

SDKs

SDKs Introduction

React Native

iOS

Android

Java

JavaScript

Python

Object API

Developer Basics

Aliasing

mParticle JSON Schema Reference

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.

Overall 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.

Common event data node properties

{
    "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.

custom_event

{
	"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 custom events

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.

commerce_event

{
	"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.

  1. Product-based - Used to measure data points associated with one or more products.
    These have a product_action and do NOT have a promotion_action or a product_impressions
  2. Promotion-based - Used to measure data points associated with internal promotions or campaigns.
    These have a promotion_action and do NOT have a product_action or a product_impressions
  3. Impression-based - Used to measure interactions with impressions of products and product-listings.
    These have a product_impressions and do NOT have a product_action or promotion_action
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

product_action

{
	"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

promotion_action

{
	"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_impressions

{
	"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.

shopping_cart

{
	"products": [{}]
}
Property Data Type Required Description
products array of objects optional An array of JSON objects, where each object contains a product.

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

Promotion

{
	"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

session_start

{
	"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.

session_end

{
	"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.

screen_view

{
	"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

uninstall

{
	"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.

crash_report

{
	"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

opt_out

{
	"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

push_registration

{
	"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

application_state_transition

{
	"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

push_message

{
	"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.

network_performance

{
	"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:

  • used to trigger behaviors for predefined data-points to a specific integration.
  • sent to the specific integration, and to all raw data event integrations (i.e. Amazon Kinesis, Amazon S3, Amazon SNS, Amazon SQS, Apache Kafka, Google Cloud Storage, Google Pub/Sub, Microsoft Azure Blob Storage, Microsoft Azure Event Hubs, Slack, and Webhook). This differs from custom_attributes, which are will sent to all connected integrations which support generic key/value attributes.
  • cannot be used within an audience definition.

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"
    }
}

Registering a new Partner Identity

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.

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.

Master Sample

{
  "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"
	}
  ]
}

Differences between incoming and outgoing JSON

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:

  • mParticle may add identifiers for the batch (batch_id), and each event (message_id). These are used by mParticle for internal processing tasks like de-duping.
  • mParticle adds a message_type field to each event, which is used for internal processing.
  • mParticle may add session management fields to each event: session_id, session_uuid and session_start_unixtime.
  • Outbound JSON will include an 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.
  • mParticle adds a top-level batch timestamp — 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.
  • Some fields are set automatically by one or more native SDKs. For example, the Android SDK automatically sets an 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.
  • The 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.
  • mParticle may add a top-level batch unique_id field if you enter a value for the Unique ID connection setting.

Outgoing User Identities

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
        }
    ]
}

JSON Schema Validation

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.

Python

The following example uses the popular jsonschema library and performs the following:

  • Downloads the latest Event API schemas (both the single and bulk variations)
  • Creates an arbitrary example upload as a dictionary
  • Validates both the single and bulk instance objects
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)

Additional Libraries

See the JSON Schema specification homepage for more JSON Schema validation tools.

Was this page helpful?

    Last Updated: December 5, 2024