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

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

Unity

Upload Frequency

Getting Started

Opt Out

Initialize the SDK

Event Tracking

Commerce Tracking

Error Tracking

Screen Tracking

Identity

Location Tracking

Session Management

Xbox

Getting Started

Identity

Roku

Getting Started

Identity

Media

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

Web

Alexa

Media SDKs

Android

iOS

Web

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

Tools

mParticle Command Line Interface

Linting Tools

Smartype

Server SDKs

Node SDK

Go SDK

Python SDK

Ruby SDK

Java SDK

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

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
Observability

Observability Overview

Observability User Guide

Observability Span Glossary

The New mParticle Experience

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)

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)
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

Integrations

Aarki

Audience

ABTasty

Audience

Abakus

Event

24i

Event

Actable

Feed

Adikteev

Event

Audience

Adjust

Event

Feed

AdChemix

Event

AdMedia

Audience

Adobe Marketing Cloud

Cookie Sync

Event

Adobe Campaign Manager

Audience

Adobe Audience Manager

Audience

Adobe Target

Audience

AdPredictive

Feed

Airship

Audience

Event

Feed

AgilOne

Event

Algolia

Event

AlgoLift

Event

Feed

Alooma

Event

Amazon Kinesis

Event

Amazon Advertising

Audience

Amazon Kinesis Firehose

Audience

Event

Amazon Redshift

Data Warehouse

Amazon S3

Event

Amazon SNS

Event

Amazon SQS

Event

Amobee

Audience

Adobe Marketing Cloud

Event

Amplitude

Forwarding Data Subject Requests

Event

Ampush

Audience

Event

Analytics

Audience

Event

Forwarding Data Subject Requests

AppsFlyer

Event

Feed

Forwarding Data Subject Requests

Anodot

Event

AppLovin

Audience

Event

Apptimize

Event

Apptentive

Event

Apteligent

Event

Attentive

Event

Feed

Attractor

Event

Microsoft Azure Blob Storage

Event

Batch

Audience

Event

Bing Ads

Event

Bidease

Audience

Bluecore

Event

Bluedot

Feed

Blueshift

Forwarding Data Subject Requests

Feed

Event

Branch

Event

Forwarding Data Subject Requests

Feed

Braze

Audience

Feed

Forwarding Data Subject Requests

Event

Branch S2S Event

Event

Bugsnag

Event

Button

Audience

Event

Cadent

Audience

ciValue

Event

Feed

CleverTap

Event

Audience

Feed

Census

Feed

comScore

Event

Conversant

Event

Cortex

Event

Feed

Forwarding Data Subject Requests

Cordial

Audience

Feed

Criteo

Audience

Event

Crossing Minds

Event

Custom Feed

Custom Feed

CustomerGlu

Event

Feed

Customer.io

Audience

Event

Feed

Databricks

Data Warehouse

Datadog

Event

Dynalyst

Audience

Didomi

Event

Dynamic Yield

Audience

Event

Edge226

Audience

Epsilon

Event

Emarsys

Audience

Everflow

Audience

Facebook

Audience

Event

Fiksu

Audience

Event

Flurry

Event

Facebook Offline Conversions

Event

Flybits

Event

Formation

Event

Feed

ForeSee

Event

Google Analytics for Firebase

Event

Foursquare

Audience

Feed

FreeWheel Data Suite

Audience

Google Ad Manager

Audience

Google Ads

Audience

Event

Google Analytics

Event

Google BigQuery

Audience

Data Warehouse

Google Cloud Storage

Audience

Event

Google Enhanced Conversions

Event

Google Analytics 4

Event

Google Marketing Platform Offline Conversions

Event

Google Pub/Sub

Event

Google Marketing Platform

Audience

Cookie Sync

Event

Google Tag Manager

Event

Heap

Event

Herow

Feed

Hightouch

Feed

Ibotta

Event

Indicative

Audience

Event

Hyperlocology

Event

Impact

Event

InMobi

Audience

Event

InMarket

Audience

Insider

Audience

Event

Feed

Intercom

Event

Inspectlet

Event

iPost

Feed

Audience

ironSource

Audience

Iterable

Event

Feed

Audience

Jampp

Event

Audience

Kayzen

Event

Audience

Kafka

Event

Kissmetrics

Event

Klaviyo

Audience

Event

Kochava

Feed

Forwarding Data Subject Requests

Event

LaunchDarkly

Feed

Leanplum

Event

Audience

Feed

LifeStreet

Audience

Kubit

Event

Liftoff

Audience

Event

LiveLike

Event

Localytics

Event

Liveramp

Audience

MadHive

Audience

mAdme Technologies

Event

Marigold

Audience

Mailchimp

Event

Feed

Audience

Mautic

Audience

Event

MediaMath

Audience

Mediasmart

Audience

Microsoft Azure Event Hubs

Event

Mintegral

Audience

Mixpanel

Event

Forwarding Data Subject Requests

Audience

Moloco

Event

Audience

MoEngage

Event

Audience

Feed

Monetate

Event

Movable Ink - V2

Event

Movable Ink

Event

Multiplied

Event

myTarget

Event

Audience

Nami ML

Feed

Nanigans

Event

Narrative

Audience

Event

Feed

NCR Aloha

Event

Optimizely

Audience

Event

Neura

Event

OneTrust

Event

Oracle Responsys

Audience

Event

Oracle BlueKai

Event

Paytronix

Feed

Persona.ly

Audience

Personify XP

Event

PieEye

Inbound Data Subject Requests

Pinterest

Audience

Event

Plarin

Event

Pilgrim

Event

Feed

Postie

Event

Audience

Primer

Event

Punchh

Audience

Event

Feed

Quadratic Labs

Event

Pushwoosh

Audience

Event

Qualtrics

Event

Quantcast

Event

Reddit

Event

Audience

Radar

Event

Feed

Remerge

Event

Audience

Regal

Event

Retina AI

Event

Feed

Reveal Mobile

Event

RevenueCat

Feed

Rokt

Audience

RTB House

Event

Audience

Salesforce Email

Audience

Event

Feed

Sailthru

Audience

Event

Salesforce Mobile Push

Event

Samba TV

Audience

Event

Scalarr

Event

SendGrid

Audience

Feed

SessionM

Event

Feed

ShareThis

Feed

Audience

Shopify

Custom Pixel

Feed

Signal

Event

SimpleReach

Event

Singular

Event

Feed

Singular-DEPRECATED

Event

Skyhook

Event

Slack

Event

Smadex

Audience

Snapchat

Audience

Event

SmarterHQ

Event

Snapchat Conversions

Event

Snowflake

Data Warehouse

Snowplow

Event

Split

Event

Feed

Splunk MINT

Event

Sprig

Audience

Event

StartApp

Audience

Statsig

Event

Feed

Stormly

Event

Audience

Swrve

Event

Feed

Tapad

Audience

Talon.One

Audience

Event

Feed

Taplytics

Event

Tapjoy

Audience

Taptica

Audience

Teak

Audience

The Trade Desk

Cookie Sync

Audience

Event

Ticketure

Feed

Treasure Data

Audience

Event

TikTok Event

Audience

Audience (Deprecated)

Event

Audience Migration

Triton Digital

Audience

TUNE

Event

Valid

Event

Vkontakte

Audience

Twitter

Event

Audience

Voucherify

Audience

Event

Vungle

Audience

Webtrends

Event

Webhook

Event

White Label Loyalty

Event

Wootric

Event

Xandr

Audience

Cookie Sync

Yahoo (formerly Verizon Media)

Audience

Cookie Sync

Yotpo

Feed

YouAppi

Audience

Z2A Digital

Audience

Event

Zendesk

Event

Feed

Antavo

Feed

Event

This section describes the configuration settings necessary to activate mParticle’s event tracking integration with Facebook. The event tracking integration enables conversion tracking for Facebook advertising campaigns.

Supported Features

  • Event Forwarding

Data Processing Notes

Facebook has limits around the number of unique event names and attributes their platform can process as noted here: https://developers.facebook.com/docs/reference/android/current/class/AppEventsLogger/

  • 1000 unique event names
  • 25 attributes per event
  • Between 2 and 40 characters in an event name and attribute
  • It may takes up to 24 hours to see refreshed stats in Facebook Analytics

Prerequisites

Event data from mParticle to Facebook is typically sent server side. However, Web data can be sent client or server side based on your implementation and settings. These different options require different settings:

  • iOS, tvOS, and Android - data is sent S2S, and you’ll need your app’s Facebook Application ID and Application Secret
  • Data Feeds - data is sent S2S, and you’ll need your Facebook Pixel ID
  • Web - for client side kit, you’ll need your Facebook Pixel ID
  • Web - for S2S, you’ll need your Facebook Pixel ID and Facebook Marketing API Access Token. You also need to enable both the Use Pixel Server-Side Forwarding and Forward Web Requests Server Side settings.
  • Roku, Xbox, SmartTV, FireTV, Alexa - you’ll need your Facebook Pixel ID and Facebook Marketing API Access Token.
  • os_version is required for iOS/tvOS events. If os_version is not present, the event will be rejected and an error message will be shown in System Alerts.

Configuring Facebook Pixel Server-to-Server

You need to perform a few steps in Facebook to create a Facebook Pixel S2S connection.

  1. Navigate to the Facebook Events Manager
  2. Connect a New Data Source: Select Web with a connection method of Conversions API.
  3. Create an Access Token: Open the settings for the new Pixel Data Source, scroll to the Conversions API > Set up manually section and click Create Access Token. Follow the steps described and copy the Access Token for setup in mParticle.

Configuring Duplicate Events

Facebook recommends sending the same pixel event twice - once from the browser and once from the server. If done incorrectly, this can result in duplicate events appearing in Facebook. The following steps walk through how to configure this within mParticle.

To do this using mParticle, you will need to perform the following steps:

  1. Setup the mParticle Web SDK in your application
  2. Setup two configurations for mParticle’s Facebook integration. One of these configurations must have Use Pixel Server-Side Forwarding enabled and the other must not. Both must have an access token set.
  3. Connect both of these configurations to your Web input. The configuration with server-side Pixel forwarding enabled, must also have Forward Web Requests Server Side enabled. Similarly, the connection with Pixel server-side forwarding disabled, must have Forward Web Requests Server Side disabled.

Other Scenarios

Ideally, all Web data sent to mParticle will be sent through the mParticle Web SDK, but it is still possible to deduplicate events outside of this flow if necessary. To ensure redundant events sent through Facebook Pixel and the Facebook Conversions API are correctly deduplicated when they reach Facebook, two conditions must be met:

  • Events must have consistent event_name values.
  • Events must have consistent event_id values. For this, the field source_message_id may be used to manually set the Event ID sent to Facebook.

If you use the mParticle Web SDK and server-side web integration, then this will be automatically handled.

If you need to manually assign a source_message_id via the web SDK and server-side separately, use the following API:

mParticle.logBaseEvent({
    messageType: 4, // This is the messageType for custom events.  Use 3 for page views
    name: 'Test Event',
    data: {attr1: 'value1'}, // custom attributes
    eventType: mParticle.EventType.Navigation, // optional for custom events. Do not set for page views
    customFlags: {flag1: 'flagValue1'},
    sourceMessageId: 'custom_source_message_id'
});

You can also assign a source_message_id to commerce events:

// 1. Create the product

const product1 = mParticle.eCommerce.createProduct(
    'Double Room - Econ Rate',  // Name
    'econ-1',                   // SKU
    100.00,                     // Price
    4,                          // Quantity
);

// 2. Summarize the transaction
const transactionAttributes = {
    Id: 'foo-transaction-id',
    Revenue: 430.00,
    Tax: 30
};

// 3. Log the purchase event
// Optional custom attributes for a product action can be defined as key/value pairs witin an object
const customAttributes = {
    'sale': true
};

// Optional custom flags can be defined as key/value pairs within an object
const customFlags = {
    'Google.Category': 'travel'
};

const options = {
    sourceMessageId: 'custom_source_message_id'
}

mParticle.eCommerce.logProductAction(
    mParticle.ProductActionType.Purchase,
    [product1],
    customAttributes,
    customFlags,
    transactionAttributes,
    options
);

Note that your workspace will need to be on event batching in order to leverage passing a custom source_message_id to the Web SDK for this to work. If you are not on web batching, please contact your customer success manager.

Visit the Facebook Business Help Center and Facebook For Developers for more information on the subject of deduplication.

Troubleshooting Facebook Pixel Issues

Please run through the following steps to confirm your settings are correct:

If you run into issues with either of the above steps, please repeat the steps described in Configuring Facebook Pixel Server-to-Server.

Event Data Mapping

  • The iOS/tvOS and Android integrations forward App State Transition, Commerce, Custom, Screen View, and Session Start events.
  • The Web integration forwards Commerce, Custom, Screen View, and Session Start / End events.

iOS14 Update for Device Data Mapping

The Facebook advertiser_tracking_enabled field is set based on the att_authorization_status and limit_ad_tracking fields as defined below. Check the iOS14 Implementation guide for more information.

If att_authorization_status is available:

att_authorization_status advertiser_tracking_enabled
authorized 1
All other values 0

If att_authorization_status is not available, the limit_ad_tracking field is evaluated:

limit_ad_tracking advertiser_tracking_enabled
Not available or false 1
true 0

User Data Mappings

mParticle will send a variety of user data fields to Facebook for advanced matching. The specific fields sent depends on if Facebook Pixel server-side forwarding is enabled or not.

Facebook Pixel Server-Side Forwarding Disabled

mParticle will hash and send the following fields to Facebook when they are set for a user.

mParticle Field Facebook Field Description
email User Identity em mParticle will send the email identity based on the value of the Email Type setting. The email user identity will be hashed before forwarding to Facebook, other user identities will not be hashed prior to forwarding.
Identity as defined by External User Identity Type setting external_id mParticle will hash and send a single identity based on the value of the External User Identity Type setting.
Phone Number User Identity ph mParticle will hash and send a single phone number identity. mParticle will use the mobile_number identity if it is provided. If not, mParticle will use phone_number_2 if it is provided. If neither of those are provided, mParticle will use phone_number_3 if it is provided. If none of those are provided, mParticle will use the $mobile user attribute if it is provided.
Device Identity advertiser_id mParticle will send an Advertiser ID if the user has an IDFA (Apple Identifier for Advertisers), GAID (Google Advertising ID), or RAID (Roku Advertising Identifier)
$gender User Attribute ge
$firstname User Attribute fn
$lastname User Attribute ln
$city User Attribute ct
$state User Attribute st
$zip User Attribute zp
$country User Attribute country

Facebook Pixel Server-Side Forwarding Enabled

mParticle Field Facebook Field Name Hashed? Description
email User Identity em Yes mParticle will send the email identity based on the value of the Email Type setting. The email user identity will be hashed before forwarding to Facebook, other user identities will not be hashed prior to forwarding.
Facebook.BrowserId Custom Flag fbp No Facebook Browser ID
Facebook.ClickId Custom Flag fbc No Facebook Click ID
Facebook.ActionSource Custom Flag action_source No This field allows you to specify where your conversions occurred. Knowing where your events took place helps ensure your ads go to the right people. The accepted values are email, website, app, phone_call, chat, physical_store, system_generated and other. The website action source requires that the Facebook.EventSourceUrl custom flag is set on the event. Please see Facebook’s documentation for details.
Phone Number User Identity ph Yes mParticle will hash and send a single phone number identity. mParticle will use the mobile_number identity if it is provided. If not, mParticle will use phone_number_2 if it is provided. If neither of those are provided, mParticle will use phone_number_3 if it is provided. If none of those are provided, mParticle will use the $mobile user attribute if it is provided.
Identity as defined by External User Identity Type setting external_id Yes mParticle will hash and send a single identity based on the value of the External User Identity Type setting.
$gender User Attribute ge Yes
$firstname User Attribute fn Yes
$lastname User Attribute ln Yes
$city User Attribute ct Yes
$state User Attribute st Yes
$zip User Attribute zp Yes
$country User Attribute country Yes
ip client_ip_address No
Device Info http_header_user_agent client_user_agent No The http_header_user_agent is required if the Default Action Source is set to Website in your configuration settings. Please see Facebook’s documentation for details.

Custom Mappings

mParticle’s Facebook integration supports custom mappings which allows you to map your events and attributes for Facebook. mParticle provides mappings for the following Facebook event types:

Event Name Standard Mapping Pixel Mapping
Achieved Level fb_mobile_level_achieved N/A
Ad Click AdClick N/A
Ad Impression AdImpression N/A
Added Payment Info fb_mobile_add_payment_info AddPaymentInfo
Added to Cart fb_mobile_add_to_cart AddToCart
Added to Wishlist fb_mobile_add_to_wishlist AddToWishlist
Added to Wishlist - Automotive fb_mobile_add_to_wishlist AddToWishlist
Completed Registration fb_mobile_complete_registration CompleteRegistration
Completed Tutorial fb_mobile_tutorial_completion N/A
Contact Contact Contact
Customize Product CustomizeProduct CustomizeProduct
Donate Donate Donate
Find Location FindLocation FindLocation
Initiated Checkout fb_mobile_initiated_checkout InitiateCheckout
Initiated Checkout - Travel fb_mobile_initiated_checkout InitiateCheckout
Lead N/A Lead
Lead - Automotive N/A Lead
Page View PageView PageView
Purchased fb_mobile_purchase Purchase
Purchased - Travel fb_mobile_purchase Purchase
Rated fb_mobile_rate N/A
Schedule Schedule Schedule
Searched fb_mobile_search Search
Searched - Automotive fb_mobile_search Search
Searched - Travel fb_mobile_search Search
Spent Credits fb_mobile_spent_credits N/A
Start Trial StartTrial StartTrial
Submit Application N/A SubmitApplication
Subscribe Subscribe Subscribe
Unlocked Achievement fb_mobile_achievement_unlocked N/A
Viewed Content fb_mobile_content_view ViewContent
Viewed Content - Automotive fb_mobile_content_view ViewContent
Viewed Content - Travel fb_mobile_content_view ViewContent

fb_content_type

When setting up the custom mappings, the fb_content_type can provide additional information on the event to be used for Collaborative Ads. The acceptable values for fb_content_type are:

  • product
  • product_group
  • destination
  • flight
  • hotel
  • vehicle
  • [“product”, “local_service_business”]

If a value provided for fb_content_type is not in the above list, the value sent will be product.

Product Events

mParticle forwards the mParticle product events Added to Cart and Added to Wishlist to Facebook using Facebook’s corresponding pre-defined event names. mParticle Product Views are forwarded to Facebook as the pre-defined event “Viewed Content”. The unit price, currency, product category, and SKU are passed to Facebook as well. See below for a sample Added to Cart event call using the Facebook SDK, and an equivalent call using the mParticle SDK.

//Facebook SDK call
[FBAppEvents logEvent:FBAppEventNameAddedToCart
           valueToSum:54.23
           parameters:@{ FBAppEventParameterNameCurrency    : @"USD",
                         FBAppEventParameterNameContentType : @"shoes",
                         FBAppEventParameterNameContentID   : @"HDFU-8452" } ];

//Equivalent mParticle SDK call
MPProduct *product = [[MPProduct alloc] initWithName:@"A Shoe"
                                            category:@"shoes"
                                            quantity:1
                                       revenueAmount:54.23];
product.unitPrice = 54.23;
product.sku = @"HDFU-8452";

[[MParticle sharedInstance] logProductEvent:MPProductEventAddedToCart product:product];
//Facebook SDK call
Bundle parameters = new Bundle();
parameters.putString(AppEventsConstants.EVENT_PARAM_CURRENCY, "USD");
parameters.putString(AppEventsConstants.EVENT_PARAM_CONTENT_TYPE, "shoes");
parameters.putString(AppEventsConstants.EVENT_PARAM_CONTENT_ID, "HDFU-8452");

logger.logEvent(AppEventsConstants.EVENT_NAME_ADDED_TO_CART,
        54.23,
        parameters);

//Equivalent mParticle SDK call
MPProduct product = new MPProduct.Builder("A Shoe", "HDFU-8452")
    .quantity(1)
    .unitPrice(54.23)
    .totalRevenue(54.23)
    .productCategory("shoes")
    .currencyCode("USD")
    .build();
mp.logProductEvent(MPProduct.Event.ADD_TO_CART, product);

Purchase Events

Purchase events logged through mParticle’s eCommerce SDK methods will be forwarded to Facebook using Facebook’s “Purchased” pre-defined event name.

Custom Events

All custom app events, which are logged via mParticle’s logEvent SDK method, will be forwarded to Facebook as custom app events, using the event name passed to mParticle’s logEvent SDK method.

//Facebook SDK call
[FBAppEvents logEvent:@"battledAnOrc"];

//Equivalent mParticle SDK call
[[MParticle sharedInstance] logEvent:@"battledAnOrc"];
//Facebook SDK call
logger.logEvent("battledAnOrc");

//Equivalent mParticle SDK call
mp.logEvent("battledAnOrc");

Screen Views

For the Web platform, mParticle will forward screen views as ‘PageView’ events.

  • Note: This also applies to Pixel server-side forwarding.

For the iOS/tvOS and Android platforms, screen views are supported by custom mappings. Reference the custom mappings section for more.

Web Server-to-Server Fields

There are several fields only accepted by server-to-server Web connections. These fields and the mParticle fields they are set from are listed below:

Facebook Field Name
Description
mParticle Field
client_user_agent The user agent for the browser corresponding to the event. This flag is required if the Default Action Source is set to Website in the connection configuration. Facebook.ClientUserAgent custom flag
event_source_url The browser URL where the event happened. This flag is required if the Default Action Source is set to Website in the connection configuration. Facebook.EventSourceUrl custom flag
opt_out A flag that indicates Facebook should not use this event for ads delivery optimization. CCPA Opt Out Status
Custom Data Fields Additional data used for ads delivery optimization. Custom attributes*

*Custom data fields can also be set via custom mappings or E-Commerce event fields. See the relevant sections for more details.

Configuration Settings

Setting Name Data Type Default Value Description
Access Token string The Facebook Access Token used to make Marketing API calls. Required for Web. Facebook recommends using a System User Access Token.
Use Pixel Server-Side Forwarding bool False If enabled, mParticle will use Facebook’s Pixel Server-Side API to forward events for Web and Out-of-Band connections. Notes: this setting is read-only. To enable it, create a new configuration.

Connection Settings

Setting Name Data Type Default Value Platform Description
Send Purchase Product Data bool False All If enabled, additional product data will be forwarded for purchase events
Facebook Application ID string iOS, Android, tvOS The App ID found on your Facebook application’s dashboard
Facebook Application Secret string iOS, Android, tvOS The App Secret found on your Facebook application’s dashboard
Send Activate On string ast iOS, Android, tvOS Specifies whether to send Facebook activate and deactivate messages based on mParticle application state transition messages or session start messages
Limit Event and Data Usage bool False iOS, Android, tvOS Sets whether data sent to Facebook should be restricted from being used for purposes other than analytics and conversions, such as targeting ads
Pixel ID string Web Facebook Pixel ID
Default Action Source string other Web, Feed The default value for a conversion’s action source. This value will be used if the Facebook.ActionSource custom flag is not set on the event. Please see the documentation for information on setting the custom flag.
Forward Web Requests Server Side bool False Web If enabled, requests will only be forwarded server-side
Disable Automatic Page Logging bool False Web Single Page Applications Only - By default, the Facebook Pixel has an HTML5 History State API listener activated. Whenever a new state is pushed into History, it will automatically fire a PageView event (outside of mParticle). This could lead to duplicate PageViews in Facebook. If you want all PageViews to be tracked via mParticle instead, check this box to disable this listener.
External User Identity Type string Customer ID All The User Identity to send to Facebook as an External ID. The identity is sent hashed for every selection except for MPID, which is sent raw.
Send CCPA Limited Data Use enum Never All When should mParticle send the CCPA limited data use flag to Facebook. Note: the flag can only be sent for batches with country and state user attributes defined or for Pixel connections with client IP defined.
Email Type enum Email All The mParticle User Identity type to forward as an Email to Facebook. The email user identity will be hashed before forwarding to Facebook, other user identities selected from this dropdown will not be hashed prior to forwarding.
Enrich Facebook Cookie Identifiers bool False Web, Feed If enabled, cookie-based identifiers are stored on a user’s profile, and batches are enriched with the most-recently seen identifiers when missing from the batch. Currently, cookie identifiers include only fbc and fbp.
Enrich IP Address bool False Web, Feed If enabled, a batch will be enriched with the most-recently seen IP address when missing from the batch.
    Last Updated: December 10, 2024