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

Custom Access Roles API

Data Planning API

Group Identity API Reference

Calculated Attributes Seeding API

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

Direct Url Routing

Direct URL Routing FAQ

Web

Android

iOS

Flutter

Getting Started

Usage

API Reference

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

React Native

Getting Started

Identity

Roku

Getting Started

Identity

Media

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

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

Xamarin

Getting Started

Identity

Cordova

Cordova Plugin

Identity

Web

Alexa

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

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

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

HTTP 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

Media SDKs

Android

iOS

Web

Server SDKs

Node SDK

Go SDK

Python SDK

Ruby SDK

Java SDK

Tools

mParticle Command Line Interface

Linting Tools

Smartype

Guides
Partners

Introduction

Outbound Integrations

Outbound Integrations

Firehose Java SDK

Inbound Integrations

Kit Integrations

Overview

Android Kit Integration

JavaScript Kit Integration

iOS Kit Integration

Compose ID

Data Hosting Locations

Glossary

Rules Developer Guide

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

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

Export Results from a Funnel

Explore Users 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)
Settings

Debug Console

Data Warehouse Delay Alerting

Identity Providers

Single Sign-On (SSO)

Setup Examples

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

REST API

Dashboard Filter API (Deprecated)

User Segments Export API (Deprecated)

SDKs

SDKs Introduction

React Native

iOS

Android

Java

JavaScript

Python

Object API

Developer Basics

Aliasing

Create an Input

Introduction

The purpose of this guide is to walk you through the basic steps of setting up mParticle in your app, unlocking core functionality, and troubleshooting common issues. Along the way, you’ll cover some important concepts you need to understand to be successful with mParticle.

This is not a complete guide to all of mParticle’s features and capabilities. If you already know your way around mParticle and you’re looking for in-depth docs, head to our Developers or Guides sections.

Examples

The tutorials in this guide follow the process of setting up mParticle in the mPTravel app: a mobile and web app that sells luxury travel packages to its users.

Later on in this guide, you’ll learn about sending data from mParticle to some of our many integration partners. As examples, the tutorials use services which are simple to set up and verify, and which offer a free account tier, so that you will be able follow the examples exactly if you wish. However, mParticle is agnostic about which integrations you choose and you can follow the same basic steps from this guide to implement any of our integrations.

Inputs and Outputs

One of the key functions of mParticle is to receive your data from wherever it originates, and send it wherever it needs to go. The sources of your data are inputs and the service or app where it is forwarded are outputs. A connection is a combination of an input and output.

  • Inputs include:

    • Apps or services built on any platform we support, such as iOS, Android, or Web. You can view the full list in SETUP > Inputs in the PLATFORMS tab.
    • Data feeds of any other data you want to send into mParticle. This could be data you have collected yourself or from a feed partner. Once configured, feed inputs are listed in SETUP > Inputs on the FEEDS tab.
  • Outputs may be configured for events, audiences, cookie syncs, or data subject requests depending on what the output supports. You can see the list of configured outputs in SETUP > Outputs or SETUP > Data Warehouses. Outputs include:
  • Analytics partners such as Indicative
  • Advertising partners such as Facebook
  • In-app messaging partners such as Braze
  • Data Warehouse partners, such as Amazon Redshift, Google BigQuery, or Snowflake

To get started with mParticle, you need some data, which means you need to create at least one input.

Create Access Credentials

The first thing you need to do is to to create a set of access credentials that will allow a client-side SDK or a server-side application to forward data to this workspace.

  1. Login to your mParticle account. If you’re just getting started, your first workspace is created for you. The first screen you see is an overview of activity in the workspace. Since you haven’t yet sent any data, there’s nothing to report, so far.
  2. Navigate to Setup > Inputs in the left column. Here you can see each platform type accepted by mParticle. Different platforms are associated with different sets of metadata, such as device identifiers, and most outputs only accept data from a limited set of platforms, so it is important to select the right platform. To capture data from your native Android app, choose Android. Just click the + next to your chosen platform.
  3. Click Issue Keys.
  4. Copy and save the generated Key and Secret.

About Access Credentials

mParticle labels the credentials you create for an integration the key and secret, but they are not exactly like an API key and secret, since you embed these credentials in the app. However, this is not the security risk that exposing API credentials would be:

  • The client-side key and secret can’t read data from the system.
  • You can block bad data to stop any traffic that doesn’t match the data you expect as defined in your schema.

Most anonymous client-server architectures, including Adobe, Braze, Firebase, Google Analytics, and Segment don’t have per-session or per-instance credentials, nor does mParticle.

Install and Initialize an mParticle SDK

You need a developer to help you install and initialize an SDK. See the Getting Started guides for the iOS, Android or Javascript SDKs to get set up before continuing.

Verify: Look for Incoming Data in the Live Stream

  1. Navigate to Activity > Live Stream in the left column. The Live Stream lets you inspect all incoming data from your development environments. It’s an easy way to check that you have correctly initialized mParticle in your app. When you first open up the Live Stream, it will be empty, as we haven’t yet started sending data.
  2. Start up a development build of your app (get a developer to help you if necessary). The mParticle SDKs automatically collect and forward data about installs and user sessions, so just by opening a development build of your app, you should start to see data in the Live Stream.

Advanced Platform Configuration Settings

For the iOS, Android, tvOS, and Web platforms, some advanced configuration settings are available. To change these settings, navigate to Setup > Inputs in the left column and select either iOS, Android, tvOS, or Web from the list of platforms.

Expand the Advanced Settings by clicking the + icon.

Restrict Device ID by Limit Ad Tracking

iOS, Android, and tvOS (Apple TV) devices allow users to limit the collection of advertising IDs. Advertising IDs are unique identifiers you may use to associate event and user data with a specific device. For both iOS and Android devices, if a user has not provided explicit consent to share their device’s advertising ID, then the value of that ID is set to an all-zero value.

By checking Restrict Device ID by Limit Ad Tracking, mParticle will not collect advertising IDs from users who have enabled the Limit Ad Tracking setting on their device.

Remember, mParticle will collect advertising IDs for both iOS and Android devices, regardless of whether or not a user has enabled the Limit Ad Tracking setting on their device. However, the IDs collected from users who have opted out will be all-zero values.

Following are descriptions of Apple and Google’s policies for device advertising IDs:

iOS Advertising IDs

After the release of iOS 14.5, Apple introduced the App Tracking Transparency (ATT) framework, which requires app developers to request users’ explicit consent to share their advertising IDs. If a user of your app has not provided this consent, Apple’s advertising ID (IDFA) will be set to all an all-zero value: 00000000-0000-0000-0000-000000000000. Read more about Apple advertising identifiers in their documentation.

For more information about the ATT framework, visit the iOS 14 Guide.

Android Advertising IDs

Google allows Android users to opt out from sharing their devices’ advertising IDs. Similar to Apple’s policy, Google will set a user’s advertising ID (GAID or AAID) to an all-zero value if that user has opted out from sharing their ID. Read more about Google’s advertising identifiers in their documentation.

Collect Integration-Specific Identifiers

The Web SDK can collect integration-specific identifiers to enrich the user data forwarded to your connected outputs.

When Collect Integration-Specific Identifiers is checked, these integration-specific identifiers are collected and used to enrich your user data to help optimize the match rate of your audiences in downstream tools. Currently, these identifiers include Facebook’s fbc and fbp fields.

Troubleshoot

If you don’t see data appearing in the Live Stream within the first few minutes after opening a development build:

  • Check that you have copied your Key and Secret correctly
  • Check that you have properly included the mParticle SDK in your project and it is correctly initialized. The necessary steps will differ depending on the platform. Check our iOS, Android and Web docs for more.

Next Steps

Congratulations, you have created a working data input. Now it’s time to start capturing some data.

Was this page helpful?

    Last Updated: November 8, 2024