Data Subject Request API Version 1 and 2
Data Subject Request API Version 3
Platform API Overview
Accounts
Apps
Audiences
Calculated Attributes
Data Points
Feeds
Field Transformations
Services
Users
Workspaces
Warehouse Sync API Overview
Warehouse Sync API Tutorial
Warehouse Sync API Reference
Data Mapping
Warehouse Sync SQL Reference
Warehouse Sync Troubleshooting Guide
ComposeID
Warehouse Sync API v2 Migration
Bulk Profile Deletion API Reference
Calculated Attributes Seeding API
Custom Access Roles API
Data Planning API
Group Identity API Reference
Pixel Service
Profile API
Events API
mParticle JSON Schema Reference
IDSync
AMP SDK
Initialization
Configuration
Network Security Configuration
Event Tracking
User Attributes
IDSync
Screen Events
Commerce Events
Location Tracking
Media
Kits
Application State and Session Management
Data Privacy Controls
Error Tracking
Opt Out
Push Notifications
WebView Integration
Logger
Preventing Blocked HTTP Traffic with CNAME
Linting Data Plans
Troubleshooting the Android SDK
API Reference
Upgrade to Version 5
Cordova Plugin
Identity
Direct URL Routing FAQ
Web
Android
iOS
Getting Started
Identity
Initialization
Configuration
Event Tracking
User Attributes
IDSync
Screen Tracking
Commerce Events
Location Tracking
Media
Kits
Application State and Session Management
Data Privacy Controls
Error Tracking
Opt Out
Push Notifications
Webview Integration
Upload Frequency
App Extensions
Preventing Blocked HTTP Traffic with CNAME
Linting Data Plans
Troubleshooting iOS SDK
Social Networks
iOS 14 Guide
iOS 15 FAQ
iOS 16 FAQ
iOS 17 FAQ
iOS 18 FAQ
API Reference
Upgrade to Version 7
Upload Frequency
Getting Started
Opt Out
Initialize the SDK
Event Tracking
Commerce Tracking
Error Tracking
Screen Tracking
Identity
Location Tracking
Session Management
Initialization
Content Security Policy
Configuration
Event Tracking
User Attributes
IDSync
Page View Tracking
Commerce Events
Location Tracking
Media
Kits
Application State and Session Management
Data Privacy Controls
Error Tracking
Opt Out
Custom Logger
Persistence
Native Web Views
Self-Hosting
Multiple Instances
Web SDK via Google Tag Manager
Preventing Blocked HTTP Traffic with CNAME
Facebook Instant Articles
Troubleshooting the Web SDK
Browser Compatibility
Linting Data Plans
API Reference
Upgrade to Version 2 of the SDK
Getting Started
Identity
Web
Alexa
Node SDK
Go SDK
Python SDK
Ruby SDK
Java SDK
Overview
Step 1. Create an input
Step 2. Verify your input
Step 3. Set up your output
Step 4. Create a connection
Step 5. Verify your connection
Step 6. Track events
Step 7. Track user data
Step 8. Create a data plan
Step 9. Test your local app
Overview
Step 1. Create an input
Step 2. Verify your input
Step 3. Set up your output
Step 4. Create a connection
Step 5. Verify your connection
Step 6. Track events
Step 7. Track user data
Step 8. Create a data plan
Step 1. Create an input
Step 2. Create an output
Step 3. Verify output
Introduction
Outbound Integrations
Firehose Java SDK
Inbound Integrations
Data Hosting Locations
Compose ID
Glossary
Migrate from Segment to mParticle
Migrate from Segment to Client-side mParticle
Migrate from Segment to Server-side mParticle
Segment-to-mParticle Migration Reference
Rules Developer Guide
API Credential Management
The Developer's Guided Journey to mParticle
Create an Input
Start capturing data
Connect an Event Output
Create an Audience
Connect an Audience Output
Transform and Enhance Your Data
The new mParticle Experience
The Overview Map
Introduction
Data Retention
Connections
Activity
Live Stream
Data Filter
Rules
Tiered Events
mParticle Users and Roles
Analytics Free Trial
Troubleshooting mParticle
Usage metering for value-based pricing (VBP)
Introduction
Sync and Activate Analytics User Segments in mParticle
User Segment Activation
Welcome Page Announcements
Project Settings
Roles and Teammates
Organization Settings
Global Project Filters
Portfolio Analytics
Analytics Data Manager Overview
Events
Event Properties
User Properties
Revenue Mapping
Export Data
UTM Guide
Data Dictionary
Query Builder Overview
Modify Filters With And/Or Clauses
Query-time Sampling
Query Notes
Filter Where Clauses
Event vs. User Properties
Group By Clauses
Annotations
Cross-tool Compatibility
Apply All for Filter Where Clauses
Date Range and Time Settings Overview
Understanding the Screen View Event
Analyses Introduction
Getting Started
Visualization Options
For Clauses
Date Range and Time Settings
Calculator
Numerical Settings
Assisted Analysis
Properties Explorer
Frequency in Segmentation
Trends in Segmentation
Did [not] Perform Clauses
Cumulative vs. Non-Cumulative Analysis in Segmentation
Total Count of vs. Users Who Performed
Save Your Segmentation Analysis
Export Results in Segmentation
Explore Users from Segmentation
Getting Started with Funnels
Group By Settings
Conversion Window
Tracking Properties
Date Range and Time Settings
Visualization Options
Interpreting a Funnel Analysis
Group By
Filters
Conversion over Time
Conversion Order
Trends
Funnel Direction
Multi-path Funnels
Analyze as Cohort from Funnel
Save a Funnel Analysis
Explore Users from a Funnel
Export Results from a Funnel
Saved Analyses
Manage Analyses in Dashboards
Dashboards––Getting Started
Manage Dashboards
Organize Dashboards
Dashboard Filters
Scheduled Reports
Favorites
Time and Interval Settings in Dashboards
Query Notes in Dashboards
User Aliasing
The Demo Environment
Keyboard Shortcuts
Analytics for Marketers
Analytics for Product Managers
Compare Conversion Across Acquisition Sources
Analyze Product Feature Usage
Identify Points of User Friction
Time-based Subscription Analysis
Dashboard Tips and Tricks
Understand Product Stickiness
Optimize User Flow with A/B Testing
User Segments
IDSync Overview
Use Cases for IDSync
Components of IDSync
Store and Organize User Data
Identify Users
Default IDSync Configuration
Profile Conversion Strategy
Profile Link Strategy
Profile Isolation Strategy
Best Match Strategy
Aliasing
Overview
Create and Manage Group Definitions
Introduction
Catalog
Live Stream
Data Plans
Blocked Data Backfill Guide
Predictive Attributes Overview
Create Predictive Attributes
Assess and Troubleshoot Predictions
Use Predictive Attributes in Campaigns
Predictive Audiences Overview
Using Predictive Audiences
Introduction
Profiles
Warehouse Sync
Data Privacy Controls
Data Subject Requests
Default Service Limits
Feeds
Cross-Account Audience Sharing
Approved Sub-Processors
Import Data with CSV Files
CSV File Reference
Glossary
Video Index
Single Sign-On (SSO)
Setup Examples
Introduction
Introduction
Introduction
Rudderstack
Google Tag Manager
Segment
Advanced Data Warehouse Settings
AWS Kinesis (Snowplow)
AWS Redshift (Define Your Own Schema)
AWS S3 Integration (Define Your Own Schema)
AWS S3 (Snowplow Schema)
BigQuery (Snowplow Schema)
BigQuery Firebase Schema
BigQuery (Define Your Own Schema)
GCP BigQuery Export
Snowflake (Snowplow Schema)
Snowplow Schema Overview
Snowflake (Define Your Own Schema)
Aliasing
Event
Audience
Event
Audience
Feed
Event
Audience
Cookie Sync
Event
Audience
Audience
Feed
Audience
Event
Event
Event
Audience
Event
Event
Data Warehouse
Event
Event
Event
Audience
Event
Event
Event
Event
Event
Audience
Event
Event
Event
Feed
Event
Audience
Event
Feed
Event
Event
Event
Data Warehouse
Custom Feed
Feed
Event
Audience
Event
Audience
Audience
Event
Audience
Event
Event
Event
Event
Event
Audience
Event
Audience
Event
Audience
Data Warehouse
Event
Audience
Cookie Sync
Event
Event
Event
Event
Feed
Event
Feed
Event
Event
Event
Audience
Event
Event
Audience
Event
Event
Event
Feed
Audience
Event
Audience
Audience
Event
Event
Audience
Audience
Audience
Event
Audience
Event
Event
Event
Event
Event
Feed
Event
Event
Event
Event
Feed
Audience
Event
Event
Event
Event
Event
Event
Event
Audience
Feed
Event
Event
Custom Pixel
Feed
Event
Event
Event
Event
Event
Event
Event
Audience
Event
Data Warehouse
Event
Audience
Audience
Audience
Audience
Event
Audience
Audience
Cookie Sync
Event
Feed
Audience
Event
Event
Event
Audience
Audience
Event
Event
Event
Audience
Cookie Sync
Event
Audience
Audience
Cookie Sync
Feed
Google Analytics 4, or GA4 (formerly known as “App + Web”), is a new kind of property, with different reports than what you’re used to seeing in legacy Universal Analytics (UA) and Firebase properties. GA4 is an analytics service that enables you to measure traffic and engagement across your websites and mobile apps using customizable reports. One advantage of a GA4 property is that you can use it for a website, an app, or both a website and app together. UA properties only support websites and the Firebase Console only supports native app data.
Data collection is enabled through SDK instrumentation. Once your app is properly configured, data is ingested into the mParticle platform, which maps inbound data to Google Analytics features and their required formats, and then forwards the data to Google Analytics.
You will need a GA4 account and an app property for every app that you want to track. To set that up, follow Google’s instructions here. mParticle supports sending data to GA4 via web, native iOS and Android apps, and server to server. Each platform will require a data stream. See Google’s documentation for how to create a GA4 data stream.
On mParticle you need to create a new Configuration. To do so, find Google Analytics 4 on the Directory, click on Setup, give your new Configuration a name and decide if you want the same credentials for Development and Production. Finally, click Save.
Data can be sent to GA4 via Web both client and server side. If you are self-hosting, you can import either @mparticle/web-google-analytics-4-client-kit or @mparticle/web-google-analytics-4-server-kit depending on your use case. Note that if you want to send data server side, you must import the server kit AND enable Forward Web Requests Server Side. Enabling this setting and importing the client side kit will not work.
A GA4 Measurement ID
is automatically generated when a web data stream is added. To find your Measurement ID, see here. Our GA4 web integration allows you to send your web data both client and server side.
To send data client side on web, simply create a new Google Analytics 4 output in the mParticle UI and add it as a Connected Output to the Web Input. Add the Measurement ID
to the appropriate field in the GA4 Connection Settings in the mParticle UI. Sending data server side requires mParticle to load Google’s GA4 web SDK (gtag.js).
As required by the Google API, you must use the GA4 SDK for server-side integration. mParticle supports forwarding with both a client-side kit to forward to GA4 and S2S to the GA4 Measurement Protocol API. However, both have requirements that require the GA4 SDK be integrated natively. If you turn on the GA4 integration in our UI AND are using the mParticle web SDK, mParticle does this for you. If you want to forego the web SDK altogether, you must include the GA4 SDK yourself (GA4 docs). If you are currently forwarding data S2S to mParticle’s Events API, you must update the payloads to support forwarding to GA4, which requires the GA4 SDK to grab the relevant client_id
.
You may prefer to send web data server side in order to reduce both the number of calls the browser makes, and the size of your website. In this scenario, events are sent to mParticle’s servers, and then forwarded from mParticle’s servers to GA4.
To send data server side, check Forward Requests Server Side
in the Connection Settings. Add the Measurement ID
and you will also need to include a Measurement Protocol API Secret for Web Stream
. On GA4, each data stream can have one or more Measurement Protocol API Secrets
. To create one:
Measurement Protocol API Secrets
Create
.Create
again.Secret value
and paste it into the mParticle setting into the mParticle connection setting for GA4.Google’s server side API for GA4 requires a client_id
which still necessitates loading Google’s Global Site Tag (gtag.js), but our web SDK automatically loads gtag.js for you. mParticle sends the client_id
to our servers which then forward to Google server side.
Optionally, if you are not using the mParticle web SDK, you can resolve the client_id
by directly calling the Global site tag API.
When you send the payload to the mParticle endpoint, include client_id
as part of integration attributes under the key 160
. For example:
"integration_attributes": {
"160": {
"client_id": "your_client_id"
}
}
Note that screen_view
events are not sent, even if you include client_id
as part of the integration_attributes
.
You can set up your native app to process GA4 data client side from your users’ devices.
mParticle’s GA4 integration requires that you add the mParticle GA4 Kit to your iOS/tvOS or Android app.
mParticle publishes the GA4 kit as separate iOS/tvOS and Android libraries which have a transitive dependency on the mParticle core libraries. You can add them to your app via Carthage, Cocoapods, or Gradle:
target '<Your Target>' do
pod 'mParticle-Google-Analytics-Firebase-GA4'
end
dependencies {
// Ensure the Kit version matches that of the mParticle Core SDK that you're using
compile 'com.mparticle:android-googleanalyticsfirebasega4-kit:VERSION'
}
Reference the Apple SDK and Android SDK guides to read more about kits.
Firebase is still used to send data client side to GA4. As a result, there are several references to Firebase and Firebase docs throughout this page.
Before GA4, mobile data was analyzed within the Firebase Console. If you have a legacy Firebase property, Google provides step-by-step instructions to upgrade a Firebase instance so that data will also flow to GA4. After upgrading, your mobile data will be available for analyzing within the GA4 dashboard alongside web data. Once your Firebase properties are upgraded to GA4, the data will show up in both the Firebase Console and the GA4 console.
To send data to GA4 client side in an app, first add a platform-specific data stream`
google-services.json
for Android, or the GoogleService-Info.plist
for iOS/tvOS.Due to a known issue in the Firebase Android SDK, it is impossible to programatically initialize Firebase at runtime - you must follow the Firebase documentation for adding Firebase to your application. mParticle will be tracking this issue and if it is resolved, the integration will be updated to support runtime initialization.
The Firebase-GA4 kit will detect if you have initialized Firebase, and use the existing instance in your app if present. Despite this, all typical mParticle controls such as data filtering and user-filtering are available as expected to protect the flow of event data from mParticle to GA4. However, by directly including the Firebase SDK and configuration files in your app, mParticle cannot prevent it from collecting other data automatically.
Please see Firebase’s Android setup guide here.
Our iOS/tvOS implementation also requires you to manually instrument and initialize the Firebase SDK. Data will be automatically forwarded to that instance - mParticle will not create an additional instance.
You must follow the Firebase docs to create a Firebase project and download your GoogleService-Info.plist
configuration file. You must then include the plist directly in your app.
Please see Firebase’s iOS/tvOS setup guide here.
You may prefer to send this data server side in order to reduce both the number of calls the device makes, and the size of your app. In this scenario, events are sent to mParticle’s servers, and then forwarded from mParticle’s servers to GA4.
To send data server side, check Forward Requests Server Side
in the Connection Settings. You will also need to include your Firebase App ID
and a Measurement Protocol API Secret for Firebase
to forward web requests server side. Each data stream can have one or more Measurement Protocol API Secret
. To create one:
Measurement Protocol API Secrets
Create
.Create
again.Secret value
and paste it into the mParticle setting into the mParticle connection setting for GA4.Firebase App ID
from the Data Stream details page into the connection settings as well.Google’s server side API for GA4 requires an app_instance_id
which comes from the Firebase SDK. The mParticle Firebase for GA4 kit automatically sends the app_instance_id
to our servers to then forward to Google. This means you will need to include the mParticle Firebase Kit and Firebase SDK in your app.
Optionally, you can resolve the app_instance_id
by directly calling the Firebase SDK.
When the payload is sent to our endpoint, it will require the app_instance_id
as part of the integration attributes under the key 160
as the following example:
"integration_attributes": {
"160": {
"app_instance_id": "your_app_instance_id"
}
}
To connect a feed, you must provide at least a Firebase App ID
or a Measurement ID
, and select your Preferred Platform ID
that it’s only available for this type of output.
If your preferred platform has an associated instance ID in the processed batch, it will be automatically selected to forward the information. If not, the system will attempt to fall back to the other platform if it’s set up and the corresponding instance id is present in the batch.
Because Google has the requirement for either the app_instance_id
or the client_id
property in all requests, which come from Google’s SDKs, we are not supporting any other platforms at the time. We are working closely with Google to support other platforms when they provide a strategy that doesn’t require an SDK.
While mParticle forwards all data in real time, GA4 has different processing times depending on the data you are sending. See the Google documentation for more information on latency and data limits.
GA4 has limits around the number of custom dimensions and custom metrics as noted here.
GA4 enforces specific limits when it comes to event names and properties on iOS/Android/server-to-server. To prevent GA4 from rejecting any data, mParticle will make the following modifications to your payloads before sending them to GA4. These modifications are automatic and do not require any configuration.
_
. The replacement scheme is 1:1, so a single character (:
) is replaced by a single underscore (_
) and two special characters (::
) are replaced with two underscores (__
).Unlike Android/iOS/server-to-server, events forwarded to the GA4 web SDK are not impacted by the specific limits that Google outlines. This means that if you are using the same event names/properties across platforms, your web data will differ from other sources.
Use the Enable Data Cleansing setting when configuring your GA4 web connection to avoid these potential name discrepancies. When Enable Data Cleansing is set to true
, mParticle automatically modifies names for events ingested from the Web SDK so that they follow the same limitations imposed on the iOS, Android, and server-to-server inputs.
mParticle’s GA4 web kit will follow the above modifications, and also offers a callback that allows customers to modify the individual strings themselves before hitting our cleansing logic.
For connections created before September 25 2023, Enable Data Cleansing is defaulted to false
. You must manually enable this setting for these connections. For all newer connections, Enable Data Cleansing defaults to true
.
You can customize the replacement scheme by defining your own name standardization logic in your app’s code with a callback function immediately before initializing the mParticle SDK. Currently, this is available for the iOS and Android SDKs only.
// The following snippet should be executed prior to initializing the mParticle SDK
[MPKitFirebaseGA4Analytics setCustomNameStandardization:^(NSString* name) {
// Add your customization logic here to standardize your event names and to eliminate any rejected characters
return @"your-modified-event-name";
}];
GoogleAnalyticsFirebaseGA4Kit.setClientStandardizationCallback(callback)
// The following snippet should be executed prior to initializing the mParticle SDK
MPKitFirebaseGA4Analytics.setCustomNameStandardization { name in
// Add your customization logic here to standardize your event names and to eliminate any rejected characters
return "your-modified-event-name"
}
GoogleAnalyticsFirebaseGA4Kit.setClientStandardizationCallback(callback)
// The following snippet should be executed prior to initializing the mParticle SDK
var callback = object : GoogleAnalyticsFirebaseGA4Kit.MPClientStandardization {
override fun nameStandardization(name: String): String {
// Add your customization logic here to standardize your event names and to eliminate any rejected characters
return "your-modified-event-name"
}
}
GoogleAnalyticsFirebaseGA4Kit.setClientStandardizationCallback(callback)
mParticle.ready(function() {
window.GoogleAnalytics4Kit.setCustomNameStandardization = function(name) {
// In this example, the first letter is removed the event or attribute names
return name.slice(1);
}
})
Depending on if you are migrating from a web or a native property, there are different considerations.
From a code perspective, there are a few changes you will need to make when migrating from UA to GA4. You may want to familiarize yourself with the differences between GA4 and UA by reading Google’s in-depth comparison here.
Specifically, a few core changes Google made from UA to GA4 that impact our kits are as follows:
All the associated custom flags related to the above are no longer relevant and should not be included when implementing mParticle’s GA4 web kit.
Because the GA4 data model is driven by Firebase, no changes are needed to keep your current code working. However, we do support the new GA4 ecommerce events: add_shipping_info
and add_payment_info
. See Custom Flags for more information.
The Firebase event select_content
is select_item
in GA4.
Google can auto-generate reports based on recommended event names and recommended event parameters when sent to GA4. You may already have a data model that does not line up exactly with GA4’s new recommended event names and parameters. As such, mParticle and Google’s UIs allow you to map data being sent to them to match Google’s data model for recommended events. Note that mParticle automatically maps commerce events for you, though you may want to customize the mapping.
Depending on your use case, mapping mParticle events to Google’s recommended events is done in either the mParticle UI or the Google UI.
Google specifies in their documentation that modifications in their UI are executed client side before the data reaches Google. Additionally, modifications are generally updated within an hour, but may take longer to take effect. The following is a summary of how to set up event modifications:
Google’s UI does not support modifications to their server. However, our Custom Mappings feature does support mapping event names and parameters server-side.
If you don’t see data in your GA4 UI, there could be a couple of issues:
You can configure the integration to automatically map the following identities to GA4:
The mParticle integration for GA4 automatically forwards some event types to Google by default, without requiring any manual configuration. See Events mapped to Google Analytics 4 by default below for more information.
You can use custom mappings to forward different events, or events that are not automatically mapped by mParticle, to Google. See Custom mappings for events below for more information.
This section describes which mParticle event types are supported and mapped to GA4 by default. To see which event types can be mapped to GA4 using custom mappings, see Custom mappings for events
mParticle forwards all custom events to GA4 — including the event name and any custom attributes. For kit integrations, this is via the logEvent
API.
These follow the GA4 naming rules for valid characters, reserved names and reserved prefixes.
Note:
_
.Crash report events are forwarded s2s and include 2 outgoing parameters:
description
: This is determined by the CrashReportEvent's
stack_trace
field, if present, or the message
field otherwise.fatal
: This is determined by the CrashReportEvent's
severity
and exception_handled
fields.mParticle automatically maps your data to the following GA4 commerce events. Select a GA4 event type to see the corresponding mParticle event and attributes.
The product
field on mParticle commerce events maps to items
in GA4. Here are the corresponding GA4 item parameters for each mParticle product attribute.
mParticle product attribute | GA4 item parameter | Notes |
---|---|---|
id |
item_id |
|
name |
item_name |
|
brand |
item_brand |
|
category |
item_category |
|
variant |
item_variant |
|
price |
price |
|
quantity |
quantity |
|
coupon_code |
coupon |
|
custom_attributes[someKey] |
someKey |
Note that someKey here refers to any arbitrary key/value pair. |
affiliation |
affiliation |
ad_impression
Platform | Event name | GA4 event name |
---|---|---|
Android Kit | ad_impression |
|
iOS/tvOS Kit | ad_impression |
|
Web Kit | ad_impression |
|
S2S Commerce | ad_impression |
add_payment_info
Requires custom flags on native mP commerce events. Alternatively, this is also supported via s2s Custom Mappings.
Platform | Event name | GA4 event name |
---|---|---|
Android Kit | Product.CHECKOUT_OPTION |
add_payment_info |
iOS/tvOS Kit | MPCommerceEventActionCheckoutOptions |
add_payment_info |
Web Kit | ProductActionType.CheckoutOption |
add_payment_info |
S2S Commerce | product_action.action.checkout_option |
add_payment_info |
add_payment_info
event attribute mappingsmP field name | GA4 parameter name | Required | Notes |
---|---|---|---|
coupon_code |
coupon |
no | |
currency_code |
currency |
yes | |
total_amount |
value |
yes | This can optionally be specified by the GA4.Value custom flag instead. |
products |
items |
yes | See product attribute mappings to see how product attributes map to GA4 item parameters. |
add_shipping_info
Requires custom flags on native mP commerce events. Alternatively, this is also supported via s2s Custom Mappings.
Platform | mParticle event name | GA4 event name |
---|---|---|
Android Kit | Product.CHECKOUT_OPTION |
add_shipping_info |
iOS/tvOS Kit | MPCommerceEventActionCheckoutOptions |
add_shipping_info |
Web Kit | ProductActionType.CheckoutOption |
add_shipping_info |
S2S Commerce | product_action.action.checkout_option |
add_shipping_info |
add_shipping_info
event attribute mappingsmP field name | GA4 parameter name | Required | Notes |
---|---|---|---|
coupon_code |
coupon |
no | |
currency_code |
currency |
yes | |
total_amount |
value |
yes | This can optionally be specified by the GA4.Value custom flag instead. |
custom_flags["GA4.ShippingTier"] or custom_flags_ext["GA4.ShippingTier"] |
shipping_tier |
no | See custom flag for more. |
products |
items |
yes | See product attribute mappings to see how product attributes map to GA4 item parameters. |
add_to_cart
Platform | mParticle event name | GA4 event name |
---|---|---|
Android Kit | Product.ADD_TO_CART |
add_to_cart |
iOS/tvOS Kit | MPCommerceEventActionAddToCart |
add_to_cart |
Web Kit | ProductActionType.AddToCart |
add_to_cart |
S2S Commerce | product_action.action.add_to_cart |
add_to_cart |
add_to_cart
event attribute mappingsmP field name | GA4 parameter name | Required | Notes |
---|---|---|---|
currency_code |
currency |
yes | |
total_amount |
value |
yes | This can optionally be specified by the GA4.Value custom flag instead. |
products |
items |
yes | See product attribute mappings to see how product attributes map to GA4 item parameters. |
add_to_wishlist
Platform | Event name | GA4 event name |
---|---|---|
Android Kit | Product.ADD_TO_WISHLIST |
add_to_wishlist |
iOS/tvOS Kit | MPCommerceEventActionAddToWishList |
add_to_wishlist |
Web Kit | ProductActionType.AddToWishlist |
add_to_wishlist |
S2S Commerce | product_action.action.add_to_wishlist |
add_to_wishlist |
add_to_wishlist
event attribute mappingsmP field name | GA4 parameter name | Required | Notes |
---|---|---|---|
currency_code |
currency |
yes | |
total_amount |
value |
yes | This can optionally be specified by the GA4.Value custom flag instead. |
products |
items |
yes | See product attribute mappings to see how product attributes map to GA4 item parameters. |
begin_checkout
Platform | Event name | GA4 event name |
---|---|---|
Android Kit | Product.CHECKOUT |
begin_checkout |
iOS/tvOS Kit | MPCommerceEventActionCheckout |
begin_checkout |
Web Kit | ProductActionType.Checkout |
begin_checkout |
S2S Commerce | product_action.action.checkout |
begin_checkout |
begin_checkout
event attribute mappingsmP field name | GA4 parameter name | Required | Notes |
---|---|---|---|
coupon_code |
coupon |
no | |
currency_code |
currency |
yes | |
total_amount |
value |
yes | This can optionally be specified by the GA4.Value custom flag instead. |
products |
items |
yes | See product attribute mappings to see how product attributes map to GA4 item parameters. |
purchase
Platform | Event name | GA4 event name |
---|---|---|
Android Kit | Product.PURCHASE |
purchase |
iOS/tvOS Kit | MPCommerceEventActionPurchase |
purchase |
Web Kit | ProductActionType.Purchase |
purchase |
S2S Commerce | product_action.action.purchase |
purchase |
purchase
event attribute mappingsmP field name | GA4 parameter name | Required | Notes |
---|---|---|---|
coupon_code |
coupon |
no | |
currency_code |
currency |
yes | |
total_amount |
value |
yes | This can optionally be specified by the GA4.Value custom flag instead. |
transaction_id |
transaction_id |
yes | |
shipping_amount |
shipping |
no | |
tax_amount |
tax |
no | |
products |
items |
yes | See product attribute mappings to see how product attributes map to GA4 item parameters. |
refund
Platform | Event name | GA4 event name |
---|---|---|
Android Kit | Product.REFUND |
refund |
iOS/tvOS Kit | MPCommerceEventActionRefund |
refund |
Web Kit | ProductActionType.Refund |
refund |
S2S Commerce | product_action.action.refund |
refund |
refund
event attribute mappingsmP field name | GA4 parameter name | Required | Notes |
---|---|---|---|
coupon_code |
coupon |
no | |
currency_code |
currency |
yes | |
total_amount |
value |
yes | This can optionally be specified by the GA4.Value custom flag instead. |
transaction_id |
transaction_id |
yes | |
shipping_amount |
shipping |
no | |
tax_amount |
tax |
no | |
products |
items |
no | See product attribute mappings to see how product attributes map to GA4 item parameters. |
remove_from_cart
Platform | Event name | GA4 event name |
---|---|---|
Android Kit | Product.REMOVE_FROM_CART |
remove_from_cart |
iOS/tvOS Kit | MPCommerceEventActionRemoveFromCart |
remove_from_cart |
Web Kit | ProductActionType.RemoveFromCart |
remove_from_cart |
S2S Commerce | product_action.action.remove_from_cart |
remove_from_cart |
remove_from_cart
event attribute mappingsmP field name | GA4 parameter name | Required | Notes |
---|---|---|---|
currency_code |
currency |
yes | |
total_amount |
value |
yes | This can optionally be specified by the GA4.Value custom flag instead. |
products |
items |
yes | See product attribute mappings to see how product attributes map to GA4 item parameters. |
screen_view
Platform | Event name | GA4 event name |
---|---|---|
Android Kit | logScreen |
screen_view |
iOS/tvOS Kit | logScreen |
screen_view |
Web Kit | logPageView |
screen_view |
S2S Commerce | screen_view |
screen_view |
screen_view
event attribute mappingsmP field name | GA4 parameter name | Required | Notes |
---|---|---|---|
screen_name |
screen_name |
no | The name of the page or screen viewed by the user during the event. |
select_item
Platform | Event name | GA4 event name |
---|---|---|
Android Kit | Product.CLICK |
select_item |
iOS/tvOS Kit | MPCommerceEventActionClick |
select_item |
Web Kit | ProductActionType.Click |
select_item |
S2S Commerce | product_action.action.click |
select_item |
select_item
event attribute mappingsmP field name | GA4 parameter name | Required | Notes |
---|---|---|---|
products |
items |
yes | See product attribute mappings to see how product attributes map to GA4 item parameters. Google only expects a single item in the items array, if multiple items are present then only the first element in the array is used. |
select_promotion
Each promotion is mapped to a distinct GA4 event, as opposed to product-based events which can include that info in an items
array.
Platform | Event name | GA4 event name |
---|---|---|
Android Kit | Promotion.CLICK |
select_promotion |
iOS/tvOS Kit | MPPromotionActionClick |
select_promotion |
Web Kit | PromotionType.PromotionClick |
select_promotion |
S2S Commerce | promotion_action.action.click |
select_promotion |
select_promotion
event attribute mappingsmP Promotion Action Field Name | GA4 Parameter Name | Required | Relevant GA4 Event Types |
---|---|---|---|
id |
promotion_id |
no | select_promotion |
name |
promotion_name |
no | select_promotion |
creative |
creative_name |
no | select_promotion |
position |
creative_slot |
no | select_promotion |
view_item
Platform | Event name | GA4 event name |
---|---|---|
Android Kit | Product.DETAIL |
view_item |
iOS/tvOS Kit | MPCommerceEventActionViewDetail |
view_item |
Web Kit | ProductActionType.ViewDetail |
view_item |
S2S Commerce | product_action.action.view_detail |
view_item |
view_item
event attribute mappingsmP field name | GA4 parameter name | Required | Notes |
---|---|---|---|
currency_code |
currency |
yes | |
total_amount |
value |
yes | This can optionally be specified by the GA4.Value custom flag instead. |
products |
items |
yes | See product attribute mappings to see how product attributes map to GA4 item parameters. |
view_item_list
Platform | Event name | GA4 event name |
---|---|---|
Android Kit | CommerceEvent.Impression |
view_item_list |
iOS/tvOS Kit | MPCommerceEventKindImpression |
view_item_list |
Web Kit | ProductActionType.Impression |
view_item_list |
S2S Commerce | product_impressions |
view_item_list |
view_item_list
event attribute mappingsmParticle field name | GA4 parameter name | Required | Notes |
---|---|---|---|
product_impression_list |
item_list_id |
no | |
product_impression_list |
item_list_name |
no | |
products |
items |
yes | See product attribute mappings to see how product attributes map to GA4 item parameters. |
view_promotion
Each promotion is mapped to a distinct GA4 event, as opposed to product-based events which can include that info in an items
array.
Platform | Event name | GA4 event name |
---|---|---|
Android Kit | Promotion.VIEW |
view_promotion |
iOS/tvOS Kit | MPPromotionActionView |
view_promotion |
Web Kit | PromotionType.PromotionView |
view_promotion |
S2S Commerce | promotion_action.action.view |
view_promotion |
view_promotion
event attribute mappingsmP Promotion Action Field Name | GA4 Parameter Name | Required | Relevant GA4 Event Types |
---|---|---|---|
id |
promotion_id |
no | select_promotion |
name |
promotion_name |
no | select_promotion |
creative |
creative_name |
no | select_promotion |
position |
creative_slot |
no | select_promotion |
Custom flags are used with native mParticle event types to send partner-specific data points:
Custom Flag | Data Type | Platform | Description |
---|---|---|---|
GA4.CommerceEventType |
string |
All | One of add_shipping_info or add_payment_info . Constants are available on Android and iOS/tvOS. |
GA4.PaymentType |
string |
All | To be used with GA4.CommerceEventType of add_payment_info . Constants are available on Android and iOS/tvOS. |
GA4.ShippingTier |
string |
All | To be used with GA4.CommerceEventType of add_shipping_info . Constants are available on Android and iOS/tvOS. |
GA4.Title |
string |
Web | The title of the page |
GA4.Location |
string |
Web | The full URL (document location) of the page on which content resides. Example: http://example.com/example |
GA4.Referrer |
string |
Web | The previous webpage that a person was on right before they landed on the current page |
GA4.Value |
number |
All | The total value of the event. |
add_shipping_info
custom flag exampleTo map to a Firebase add_shipping_info
event, pass a custom flag of GA4.CommerceEventType
equal to add_shipping_info
and an optional custom flag of GA4.ShippingTier
with a string value. The following examples show constants being used for iOS/tvOS and Android:
import com.google.firebase.analytics.FirebaseAnalytics;
import com.mparticle.kits.GoogleAnalyticsFirebaseGA4Kit;
CommerceEvent event = new CommerceEvent.Builder(Product.CHECKOUT_OPTION, new Product.Builder("Spa Essentials", "spa-1", 100.00).build())
.addCustomFlag(GoogleAnalyticsFirebaseGA4Kit.CF_GA4COMMERCE_EVENT_TYPE, FirebaseAnalytics.Event.ADD_SHIPPING_INFO)
.addCustomFlag(GoogleAnalyticsFirebaseGA4Kit.CF_GA4_SHIPPING_TIER, "overnight")
.build();
MParticle.getInstance.logEvent(event);
import com.google.firebase.analytics.FirebaseAnalytics
val event = CommerceEvent.Builder(Product.CHECKOUT_OPTION, Product.Builder("Spa Essentials", "spa-1", 100.00).build())
.addCustomFlag(GoogleAnalyticsFirebaseGA4Kit.CF_GA4COMMERCE_EVENT_TYPE, FirebaseAnalytics.Event.ADD_SHIPPING_INFO)
.addCustomFlag(GoogleAnalyticsFirebaseGA4Kit.CF_GA4_SHIPPING_TIER, "overnight")
.build()
MParticle.getInstance().logEvent(event)
@import mParticle_Apple_SDK;
@import mParticle_Google_Analytics_Firebase_GA4;
@import FirebaseAnalytics;
MPProduct *product = [[MPProduct alloc] initWithName:@"Spa Essentials" sku:@"spa-1" quantity:@1 price:@100.00];
MPCommerceEvent *event = [[MPCommerceEvent alloc] initWithAction:MPCommerceEventActionCheckoutOptions product:product];
[event addCustomFlag:kFIREventAddShippingInfo withKey:kMPFIRGA4CommerceEventType];
[event addCustomFlag:@"overnight" withKey:kMPFIRGA4ShippingTier];
[[MParticle sharedInstance] logEvent:event];
import mParticle_Apple_SDK
import mParticle_Google_Analytics_Firebase_GA4
import FirebaseAnalytics
let product = MPProduct(name: "Spa Essentials", sku: "spa-1", quantity: 1, price: 100.0)
let event = MPCommerceEvent(action: .checkoutOptions, product: product)
event.addCustomFlag(AnalyticsEventAddShippingInfo, withKey: kMPFIRGA4CommerceEventType)
event.addCustomFlag("overnight", withKey: kMPFIRGA4ShippingTier)
MParticle.sharedInstance().logEvent(event)
const product1 = mParticle.eCommerce.createProduct(
'Spa Essentials', // Name
'spa-1', // SKU
100.00, // Price
4 // Quantity
);
const customAttributes = {sale: true};
const customFlags = {
'GA4.CommerceEventType': 'add_shipping_info',
'GA4.ShippingTier': 'overnight'
};
mParticle.eCommerce.logProductAction(
mParticle.ProductActionType.CheckoutOption,
[product1],
customAttributes,
customFlags);
add_payment_info
custom flag exampleTo map to a Firebase add_payment_info
event, pass a custom flag of GA4.CommerceEventType
equal to add_payment_info
(Firebase provides a constant for this), and an optional custom flag of GA4.PaymentType
with a string value:
import com.google.firebase.analytics.FirebaseAnalytics;
CommerceEvent event = new CommerceEvent.Builder(Product.CHECKOUT_OPTION, new Product.Builder("Spa Essentials", "spa-1", 100.00).build())
// how to import GoogleAnalyticsFirebaseGA4Kit? in the tests, it sows up as kitInstance
.addCustomFlag(GoogleAnalyticsFirebaseGA4Kit.CF_GA4COMMERCE_EVENT_TYPE, FirebaseAnalytics.Event.ADD_PAYMENT_INFO)
.addCustomFlag(GoogleAnalyticsFirebaseGA4Kit.CF_GA4_PAYMENT_TYPE, "Visa")
.build();
MParticle.getInstance.logEvent(event);
import com.google.firebase.analytics.FirebaseAnalytics
val event = CommerceEvent.Builder(Product.CHECKOUT_OPTION, Product.Builder("Spa Essentials", "spa-1", 100.00).build())
.addCustomFlag(GoogleAnalyticsFirebaseGA4Kit.CF_GA4COMMERCE_EVENT_TYPE, FirebaseAnalytics.Event.ADD_PAYMENT_INFO)
.addCustomFlag(GoogleAnalyticsFirebaseGA4Kit.CF_GA4_PAYMENT_TYPE, "Visa")
.build()
MParticle.getInstance().logEvent(event)
@import mParticle_Apple_SDK;
@import mParticle_Google_Analytics_Firebase_GA4;
@import FirebaseAnalytics;
MPProduct *product = [[MPProduct alloc] initWithName:@"Spa Essentials" sku:@"spa-1" quantity:@1 price:@100.00];
MPCommerceEvent *event = [[MPCommerceEvent alloc] initWithAction:MPCommerceEventActionCheckoutOptions product:product];
[event addCustomFlag:kFIREventAddPaymentInfo withKey:kMPFIRGA4CommerceEventType];
[event addCustomFlag:@"visa" withKey:kMPFIRGA4PaymentType];
[[MParticle sharedInstance] logEvent:event];
import mParticle_Apple_SDK
import mParticle_Google_Analytics_Firebase_GA4
import FirebaseAnalytics
let product = MPProduct(name: "Spa Essentials", sku: "spa-1", quantity: 1, price: 100.0)
let event = MPCommerceEvent(action: .checkoutOptions, product: product)
event.addCustomFlag(AnalyticsEventAddPaymentInfo, withKey: kMPFIRGA4CommerceEventType)
event.addCustomFlag("visa", withKey: kMPFIRGA4PaymentType)
MParticle.sharedInstance().logEvent(event)
const product1 = mParticle.eCommerce.createProduct(
'Spa Essentials', // Name
'spa-1', // SKU
100.00, // Price
4 // Quantity
);
const customAttributes = {sale: true}; // if not passing any custom attributes, pass null
const customFlags = {
'GA4.CommerceEventType': 'add_payment_info',
'GA4.PaymentType': 'credit card'
};
mParticle.eCommerce.logProductAction(
mParticle.ProductActionType.CheckoutOption,
[product1],
customAttributes,
customFlags);
The mParticle integration for Google Analytics 4 supports optional Custom Mappings for server-to-server configurations. These optional custom mappings can help if:
Following are all event types that can be forwarded to GA4 using custom mappings. Event types that are already mapped to GA4 by default are noted in the column on the right, but remember that even events mapped by default can be mapped using a custom mapping to suit the specific needs of your implementation.
Event Type | Mapped to GA4 by default? |
---|---|
ad_impression | yes |
add_payment_info | yes |
add_shipping_info | no |
add_to_cart | yes |
add_to_wishlist | yes |
begin_checkout | yes |
earn_virtual_currency | no |
generate_lead | no |
join_group | no |
level_up | no |
login | no |
post_score | no |
purchase | yes |
refund | yes |
remove_from_cart | yes |
screen_view | yes |
search | no |
select_content | no |
select_item | yes |
select_promotion | yes |
share | no |
sign_up | no |
spend_virtual_currency | no |
tutorial_begin | no |
tutorial_complete | no |
unlock_achievement | no |
view_cart | no |
view_item | yes |
view_item_list | yes |
view_promotion | yes |
view_search_results | no |
For details on which event attributes are supported by each event type, refer to the Google Analytics 4 documentation .
mParticle will map attributes to GA4 following GA4’s limitations for valid name characters rules and length limitations for parameter names and values.
All invalid characters at the start of a parameter name are skipped until a valid one is found and any following invalid characters are replaced by a _
.
All attributes are alphabetically sorted and sent to GA4 until the limit defined per event in the GA4’s limitations docs.
Google has revamped how custom dimensions and metrics work and are implemented in GA4. Through mParticle, send events with any event attributes as normal. In Google’s UI, you can then pick the parameter and associate it with a specific custom dimension or metric. See here for how to create custom dimensions and metrics in Google’s UI.
If the Forward Session ID
dropdown connection setting is set to a value other than None
, mP will try to forward the associated value to GA4 under the session_id
field. This only applies to server-to-server data.
Options:
None
session_id
field will not be forwarded.Forward Hashed Session ID
events[x].data.session_id
long
field, and generally represents mP-generated session IDs.Note: Due to GA4 asynchronously rejecting negative long
values for the session_id
field, mParticle will first transform the value before sending it. The value is hashed using sha256
and then converted into a 64 bit hex string for readability.
123
-> a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3
Forward Session Uuid
events[x].data.session_uuid
string
field, and represents customer-defined session IDs.Note: This generally only applies to app-based inputs (e.g. iOS, tvOS, Android).
Web
, the above setting doesn’t apply.Feed
and Roku
inputs, the session_id
is forwarded if the given data’s platform
resolves to Firebase. One example is when the Preferred Platform ID
connection setting is set to the Firebase App ID
, and the Firebase App details are present in the data.In GA4, you can set a single Content Group as an event attribute content_group
. See here for more info about the change in Content Groups between UA and GA4.
Kit integrations automatically invoke setScreen
APIs for every screen event passed through mParticle.
This is not relevant for s2s forwarding.
To log page views for single-page web applications, you’ll need to use our custom flags Google.Page
and Google.Title
to set the url and title of the page.
mParticle.logPageView(
"Product Detail Page",
{ page: window.location.pathname },
{"Google.Location": window.location.pathname,
"Google.Title": "The title of the page"}
);
Read more about logging page views through our Web SDK here.
Google Analytics 4 has added specific Consent Mode parameters that must be sent via gtag implementation: ad_user_data
, ad_personalization
, ad_storage
and analytics_storage
when sending events.
To configure user consent forwarding under this value, a mapping should be set-up leveraging mParticle’s notion of Consent Purposes. To learn more about handling user consent within mParticle’s platform, see the following docs: Data Privacy Controls.
Once a Consent Purpose is set-up, user consent information can be associated with it in subsequent Events. The Consent Purpose data mapping can then be configured for downstream forwarding via the User Consent Data Mapping connection setting.
In the absence of a user-defined consent value for the ad_user_data
, ad_personalization
, ad_storage
, and analytics_storage
fields via the Consent Purpose mapping, a default value can be optionally configured via a separate drop-down setting for each consent type. When no user consent is provided, the default status is used, if specified. If omitted, the Unspecified
status will be sent.
Caution: It is recommended that in the long term, you set up user-specified consent through the Consent Purpose mapping, such that the user consent is correctly forwarded to Google. It is your responsibility as a Data Controller to stay compliant under the GDPR, and set up user consent collection for downstream forwarding. The consent default setting may be deprecated in the future.
mParticle follows Google’s recommendations when forwarding consent state defaults and consent state updates. However, the Web kit behaves differently depending on how your default consent states are configured:
If your consent state default is set to Denied
or Granted
:
custom event
or page view
event is triggered.If your consent state default is set to Unspecified
:
Setting Name | Data Type | Default Value | Platform | Description |
---|---|---|---|---|
Firebase App ID | string |
iOS, Android, tvOS, Feed | The Firebase project ID | |
Measurement ID | string |
Web, Feed | The Measurement ID for a Data Stream. The format is G-XXXXXXXXXX. | |
Measurement Protocol API secret for Firebase | string |
iOS, Android, tvOS, Feed | Your Google Analytics 4 Measurement Protocol API secret value for Firebase | |
Measurement Protocol API secret for Web Stream | string |
Web, Feed | Your Google Analytics 4 Measurement Protocol API secret value for Web Stream | |
External User Identity Type | string |
None | All | The mParticle user identity type to forward as a user ID (uid) to Google Analytics. |
Late Event Action | string |
Send | All | Choose what will happen when an event arrives too late for Google to handle the event. Send - Send anyways. Drop - Do not send, Transform - Change the event date time to ensure event is accepted. |
Enable Configuration Page View | bool |
false |
Web | If enabled, GA4 will automatically send a page view when loaded. This results in an extra page view on GA4 which will not appear in mParticle. By default this is disabled to keep mParticle and GA4 page views more in line. |
Enable Data Cleansing | bool |
true |
Web | If enabled, the Web SDK sanitizes ingested data following iOS/Android/S2S rules to improve data consistency across platforms. For connections created before September 25 2023, Enable Data Cleansing defaults to false . New connections default to true . See Enable Data Cleansing for more information. |
Hash User ID | bool |
true |
All | If enabled, mParticle will hash the selected user ID (uid) before forwarding to Google. |
Forward Web Requests Server Side | bool |
false |
All | If enabled, requests will only be forwarded server-side. |
Preferred Platform ID | string |
Firebase App ID | Feed | Specifies whether your preferred feed is Firebase App ID or a Measurement ID when both are present. Feed only setting. |
Consent Data Mapping | mapping |
null | All | A mapping of mParticle consents to Google Ads consents. |
Ad User Data Default Consent Value | string |
Unspecified |
Web | The default consent value to forward for the Ad User Data field. |
Ad Personalization Default Consent Value | string |
Unspecified |
Web | The default consent value to forward for the Ad Personalization field. |
Ad Storage Default Consent Value | string |
Unspecified |
Web | The default consent value to forward for the Ad Storage Field |
Analytics Storage Default Consent Value | string |
Unspecified |
Web | The default consent value to forward for the Analytics Storage Field |
Forward Session ID | string |
None |
iOS, Android, tvOS, FireTv, Feed, Roku | The various options around how to forward GA4’s session_id field. For Feed and Roku platforms, the session_id is forwarded when the platform resolves to Firebase. |