Developers
API References
Data Subject Request API

Data Subject Request API Version 1 and 2

Data Subject Request API Version 3

Platform API

Key Management

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

Audit Logs API

Calculated Attributes Seeding API

Bulk Profile Deletion API Reference

Custom Access Roles API

Data Planning API

Household Reach 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

Workspace Switching

Linting Data Plans

Troubleshooting the Android SDK

API Reference

Upgrade to Version 5

Upgrade to Version 6

Cordova

Cordova Plugin

Identity

Upgrade to Version 5

Flutter

Getting Started

Usage

API Reference

Direct Url Routing

Direct URL Routing FAQ

Web

Android

iOS

iOS

Workspace Switching

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

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

Upgrade to Version 9

.NET MAUI

Getting Started

Identity

React Native

Getting Started

Identity

Upgrade to Version 4

Roku

Getting Started

Identity

Media

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

Web

Initialization

Content Security Policy

Configuration

Event Tracking

User Attributes

IDSync

Page View Tracking

Commerce Events

Location Tracking

Media

Kits

Application State and Session Management

Data Privacy Controls

Error Tracking

Opt Out

Custom Logger

Persistence

Native Web Views

Self-Hosting

Multiple Instances

Web SDK via Google Tag Manager

Preventing Blocked HTTP Traffic with CNAME

Facebook Instant Articles

Troubleshooting the Web SDK

Browser Compatibility

Linting Data Plans

API Reference

Upgrade to Version 3 of the SDK

Alexa

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

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

Media SDKs

Android

Web

iOS

Server SDKs

Node SDK

Go SDK

Python SDK

Ruby SDK

Java SDK

Tools

Linting Tools

Smartype

mParticle Command Line Interface

The Developer's Guided Journey to mParticle

API Credential Management

Guides
Platform Overview

Introduction

Navigating mParticle

The Overview Map

Getting Started

Create an Input

Start capturing data

Connect an Event Output

Create an Audience

Connect an Audience Output

Transform and Enhance Your Data

mParticle Agent

Overview

Explore Your Data

Build Audiences

Create Predictions

Data and Privacy

mParticle Agent FAQ

Oversight

System Alerts

Observability

Observability Overview

Observability User Guide

Observability Troubleshooting Examples

Observability Span Glossary

Privacy

Data Subject Requests

Consent Filters

Data Privacy Controls

Data Platform

Trends

Setup

Connections

Feeds

Import Data with CSV Files

Import Data with CSV Files

CSV File Reference

SFTP Credentials

Live Stream

Data Catalog

Rules

Plans

Filters

Event Forwarding

Event Match Quality

Data Retention

Tiered Events

Blocked Data Backfill Guide

Data Warehouse
Composable Audiences

Warehouse Setup Overview

Connections

Connections Overview

Google BigQuery

Databricks

Amazon Redshift

Snowflake

Data Models

Data Models Overview

Create a User Data Model

Create an Event Data Model

Create a Generic Data Model

Warehouse Sync

Warehouse Sync User Guide

Historical Data and Warehouse Sync

Customer 360

Overview

User Profiles

Overview

User Profiles

Identity Dashboard

Identity Resolution Log

Household Reach

Calculated Attributes

Calculated Attributes Overview

Using Calculated Attributes

Create with AI Assistance

Calculated Attributes Reference

Predictions

Predictions Overview

What's Changed in the New Predictions UI

View and Manage Predictions

Predict Future Behavior

Future Behavior Predictions Overview

Create Future Behavior Prediction

Manage Future Behavior Predictions

Create an Audience with Future Behavior Predictions

Next Best Action

Next Best Action Overview

Create a Next Best Action Prediction

Manage Next Best Actions

Create an Audience with Next Best Actions

Find Similar Customers

Similar Customer Predictions Overview

Create Similar Customer Prediction

Manage Similar Customer Predictions

Build an Audience with Similar Customer Predictions

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

Probabilistic Identity Resolution

Overview

Real-Time Personalization

Analytics

Introduction

Core Analytics (Beta)

Analytics Free Trial

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

Analyses

Analyses Introduction

Segmentation: Basics

Getting Started

Visualization Options

For Clauses

Date Range and Time Settings

Calculator

Numerical Settings

Segmentation: Advanced

Assisted Analysis

Properties Explorer

Frequency in Segmentation

Trends in Segmentation

Did [not] Perform Clauses

Cumulative vs. Non-Cumulative Analysis in Segmentation

Total Count of vs. Users Who Performed

Save Your Segmentation Analysis

Export Results in Segmentation

Explore Users from Segmentation

Funnels: Basics

Getting Started with Funnels

Group By Settings

Conversion Window

Tracking Properties

Date Range and Time Settings

Visualization Options

Interpreting a Funnel Analysis

Funnels: Advanced

Group By

Filters

Conversion over Time

Conversion Order

Trends

Funnel Direction

Multi-path Funnels

Analyze as Cohort from Funnel

Save a Funnel Analysis

Explore Users from a Funnel

Export Results from a Funnel

Cohorts

Getting Started with Cohorts

Analysis Modes

Save a Cohort Analysis

Export Results

Explore Users

Saved Analyses

Manage Analyses in Dashboards

Journeys

Getting Started

Event Menu

Visualization

Ending Event

Save a Journey Analysis

Users

Getting Started

User Activity Timelines

Time Settings

Export Results

Save A User Analysis

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

User Attributes at Event Time

Understanding the Screen View Event

User Aliasing

Dashboards

Dashboards––Getting Started

Manage Dashboards

Dashboard Filters

Organize Dashboards

Scheduled Reports

Favorites

Time and Interval Settings in Dashboards

Query Notes in Dashboards

Analytics Resources

The Demo Environment

Keyboard Shortcuts

User Segments

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

APIs

User Segments Export API

Dashboard Filter API

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

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

Audiences

Audiences Overview

Create an Audience

Connect an Audience

Manage Audiences

Audience Insights

Audience Sharing

Match Boost

Inclusive & Exclusive Audiences (Early Access)

Inclusive & Exclusive Audiences Overview

Using Logic Blocks in Audiences

Combining Inclusive and Exclusive Audiences

Inclusive & Exclusive Audiences FAQ

Audience Expansion

Probabilistic Reach

Predictive Audiences

Predictive Audiences Overview

Using Predictive Audiences

Composable Audiences

Composable Audiences Overview

User Guide

User Guide Overview

Audience Setup

Frequently Asked Questions

Settings
Platform

Platform Configuration

mParticle Users and Roles

Key Management

Notifications

Audit Logs

Billing

Usage and Billing Report

Usage metering for value-based pricing (VBP)

Troubleshooting mParticle

Default Service Limits

Glossary

Integrations
24i

Event

Aarki

Audience

ABTasty

Audience

Actable

Feed

AdChemix

Event

Adikteev

Audience

Event

AdMedia

Audience

Adjust

Event

Feed

Adobe Audience Manager

Audience

Adobe Campaign Manager

Audience

Adobe Marketing Cloud

Cookie Sync

Server-to-Server Events

Platform SDK Events

Adobe Experience Platform

Event

Adobe Target

Audience

AdPredictive

Feed

AgilOne

Event

Airship

Audience

Feed

Event

Algolia

Event

Amazon Advertising

Audience

Event

Amazon Kinesis

Event

Amazon Kinesis Firehose

Audience

Event

Amazon Redshift

Data Warehouse

Amazon S3

Audience

Event

Amazon SNS

Event

Amobee

Audience

Amazon SQS

Event

Amplitude

Forwarding Data Subject Requests

Event

Ampush

Audience

Event

Analytics

Audience

Event

Forwarding Data Subject Requests

Anodot

Event

Antavo

Feed

AppLovin

Event

Audience

Apptimize

Event

AppsFlyer

Event

Feed

Forwarding Data Subject Requests

Apptentive

Event

Attentive

Feed

Event

Awin

Event

Microsoft Azure Blob Storage

Event

Batch

Audience

Event

Bluecore

Event

Bing Ads

Event

Bluedot

Feed

Bidease

Audience

Blueshift

Event

Forwarding Data Subject Requests

Feed

Branch

Event

Feed

Forwarding Data Subject Requests

Braze

Audience

Feed

Forwarding Data Subject Requests

Event

Branch S2S Event

Event

Button

Event

Audience

Bugsnag

Event

Cadent

Audience

CleverTap

Audience

Event

Feed

Census

Feed

comScore

Event

Conversant

Event

Cordial

Audience

Feed

Cortex

Event

Feed

Forwarding Data Subject Requests

Criteo

Event

Audience

Crossing Minds

Event

CustomerGlu

Event

Feed

Custom Feed

Custom Feed

Customer.io

Audience

Feed

Event

Databricks

Data Warehouse

Didomi

Event

Dynamic Yield

Audience

Event

Eagle Eye

Audience

Edge226

Audience

Datadog

Event

Emarsys

Audience

Epsilon

Event

Everflow

Audience

Facebook Offline Conversions

Event

Facebook

Audience

Event

Google Analytics for Firebase

Event

Flurry

Event

Flybits

Event

ForeSee

Event

Foursquare

Audience

Feed

FreeWheel Data Suite

Audience

Friendbuy

Event

Google Ad Manager

Audience

Google Analytics

Event

Google Ads

Audience

Event

Google Analytics 4

Event

Google Enhanced Conversions

Event

Google BigQuery

Audience

Data Warehouse

Google Cloud Storage

Audience

Event

Google Pub/Sub

Event

Google Marketing Platform Offline Conversions

Event

Google Marketing Platform

Cookie Sync

Audience

Event

Google Tag Manager

Event

Herow

Feed

Hightouch

Feed

Hyperlocology

Event

Heap

Event

Ibotta

Event

ID5

Kit

Impact

Event

InMarket

Audience

InMobi

Audience

Event

Inspectlet

Event

Insider

Audience

Event

Feed

Intercom

Event

iPost

Audience

Feed

ironSource

Audience

Iterable

Audience

Event

Feed

Kafka

Event

Jampp

Audience

Event

Kayzen

Audience

Event

Kissmetrics

Event

Klaviyo

Audience

Event

Kochava

Event

Feed

Forwarding Data Subject Requests

Kubit

Event

LaunchDarkly

Feed

Leanplum

Audience

Event

Feed

LifeStreet

Audience

Liftoff

Audience

Event

LinkedIn

Audience

LinkedIn Conversions API Integration

Liveramp

Audience

LiveLike

Event

Localytics

Event

MadHive

Audience

mAdme Technologies

Event

Mailchimp

Audience

Event

Feed

Marigold

Audience

MediaMath

Audience

Mautic

Audience

Event

Mediasmart

Audience

Microsoft Ads

Microsoft Ads Audience Integration

Microsoft Azure Event Hubs

Event

Mintegral

Audience

Mixpanel

Audience

Event

Mixpanel Cohort Feed Integration

Forwarding Data Subject Requests

MoEngage

Audience

Event

Feed

Monetate

Event

Moloco

Audience

Event

Movable Ink

Event

Multiplied

Event

Movable Ink - V2

Event

myTarget

Event

Audience

Nami ML

Feed

Nanigans

Event

NCR Aloha

Event

Narrative

Audience

Event

Feed

Neura

Event

OneTrust

Event

OpenAI

Event

Audience

Optimizely

Audience

Event

Oracle BlueKai

Event

Oracle Responsys

Audience

Event

Paytronix

Feed

Persona.ly

Audience

Personify XP

Event

PieEye

Inbound Data Subject Requests

Pilgrim

Event

Feed

Plarin

Event

Primer

Event

Pushwoosh

Event

Audience

Punchh

Audience

Event

Feed

Qualtrics

Event

Radar

Event

Feed

Quantcast

Event

Remerge

Audience

Event

Retina AI

Feed

Event

Regal

Event

Reveal Mobile

Event

RevenueCat

Feed

Rokt

Audience

Event

Rokt Thanks and Pay+

Sailthru

Audience

Event

RTB House

Event

Audience

Salesforce Email

Audience

Feed

Event

Salesforce Mobile Push

Event

Salesforce Sales and Service Cloud

Event

Feed

SendGrid

Audience

Feed

Scalarr

Event

SessionM

Event

Feed

Samba TV

Audience

Event

SFTP

Audience

ShareThis

Audience

Feed

Shopify

Feed

Custom Pixel

SimpleReach

Event

Singular

Event

Feed

Singular-DEPRECATED

Event

Skyhook

Event

Slack

Event

Smadex

Audience

SmarterHQ

Event

Snapchat

Audience

Event

Snapchat Conversions

Event

Snowflake

Audience

Data Warehouse

Snowplow

Event

Split

Event

Feed

Splunk MINT

Event

Sprig

Audience

Event

Spotify

Event

StartApp

Audience

Statsig

Event

Feed

Swrve

Event

Feed

Stormly

Audience

Event

Talon.One

Audience

Event

Feed

Loyalty Feed

Tapad

Audience

Taptica

Audience

Tapjoy

Audience

Taplytics

Event

Teak

Audience

The Trade Desk

Audience

Cookie Sync

Event

Ticketure

Feed

TikTok Event

Audience

Audience (Deprecated)

Event

Audience Migration

Treasure Data

Audience

Event

Triton Digital

Audience

TUNE

Event

Twitter

Audience

Event

Valid

Event

Vibe

Audience

Vkontakte

Audience

Vungle

Audience

Webhook

Event

Voucherify

Audience

Event

Webtrends

Event

White Label Loyalty

Event

Wootric

Event

X

Event

Yahoo (formerly Verizon Media)

Audience

Cookie Sync

Xandr

Audience

Cookie Sync

YouAppi

Audience

Yotpo

Feed

Z2A Digital

Audience

Event

Zendesk

Feed

Event

Apteligent

Event

Reddit

Audience

Event

Rakuten

Event

Postie

Audience

Event

Pinterest

Audience

Event

Event

Google’s Enhanced conversions offerings help you to improve the accuracy of your conversion measurement by supplementing your existing conversion tags with first-party conversion data, like email address and phone number. How the data is used depends on whether you’re uploading enhanced conversions for web or for leads. Check out these docs to learn more about Enhanced Conversions and its types: Google Enhanced Conversions Overview.

This page is organized in three parts:

  1. Choose an API: compare the two ways this integration can send conversions to Google.
  2. Set up your configuration with the Google Ads API or the Data Manager API.
  3. Reference for both APIs: supported events, identifiers, field mappings, consent, and settings.

Choose an API

This integration can send conversions to Google through either of two APIs. You choose the API for each configuration.

  • Google Ads API (default, legacy): The original integration path, which uses Google’s Upload Click Conversions and Upload Conversion Adjustments APIs. Configurations use this API unless you turn on Use Data Manager. This path remains fully supported.
  • Data Manager API (recommended by Google): The Data Manager API is Google’s unified API for sending first-party data, such as conversions and audiences, to Google advertising products. It’s where Google is focusing new conversion features. To use it, turn on Use Data Manager for the configuration.
Google Ads API (default, legacy) Data Manager API (recommended by Google)
Google access Sign in to Google from mParticle (OAuth) and keep that grant active. Link mParticle once from within Google Ads. No Google sign-in is needed.
Matching signals Email, phone number, address info, order ID, and click identifiers (GCLID, GBRAID, WBRAID). Email, phone number, address info, click identifiers (GCLID, GBRAID, WBRAID), IP address, and session attributes.
Address info Requires first name, last name, street address, city, country, and zip. Requires only first name, last name, country, and zip.
Where the conversion occurred Conversion Environment setting (App or Web), for allowlisted Google Ads accounts only. Event Source setting (web, app, in store, phone, message, or other), with a per-event override.
Customer classifications Not supported. Customer type (new, returning, re-engaged) and value (low, medium, high).
Last updated timestamp Not supported. Supported.
Consent ad_user_data ad_user_data and ad_personalization
Multi-source conversions Not supported. Supported. See Multi-source conversions.
Retraction adjustments Supported. Not supported. Retraction Adjustment events are rejected.

Before you choose the Data Manager API, also note:

  • Adjustments require the original order ID and conversion time. Enhancement and restatement adjustments must include the order_id and conversion_date_time of the original conversion, and restatements must include a value and currency. If Google can’t find a matching conversion, it treats the adjustment as a new conversion. A restatement with a value of 0 is supported, but it doesn’t remove the conversion count.
  • A successful upload means Google accepted the request. It doesn’t confirm that Google has finished processing or attributing the conversions.

Prerequisites

To set up the Google Enhanced Conversions Event integration with either API, you will need to have a working Ads account and know your Client Customer ID, which you can obtain from your Google Account Manager. Full requirements on Google’s end are noted in their set-up docs, respectively:

Note: to send product information along with relevant conversions to Google, your account also needs to be allowlisted as per Google’s docs.

Set up with the Google Ads API

Step 1: Create the configuration and sign in to Google

  1. In mParticle, go to Setup > Outputs and add a Google Enhanced Conversions configuration. Leave Use Data Manager off.
  2. When prompted, sign into your Google Ads account using your username and password in order to give mParticle permission to upload conversion information.
  3. Enter your Client Customer ID, and your Manager Customer ID if a manager account manages your Google Ads account.
  4. Save the configuration. mParticle validates the settings with an API call. If there’s any inconsistency between the provided customer IDs and the associated login, an error is displayed to prompt you to verify and try again.

Step 2: Connect your inputs

Connect your inputs to the configuration and fill in the connection settings. If your Google Ads account is allowlisted for it, you can also set Conversion Environment.

Set up with the Data Manager API

With the Data Manager API, mParticle sends data to Google as a Google data partner, so you don’t sign in to Google from mParticle. Instead, you link mParticle to your Google Ads account from within Google Ads.

  1. Sign in to the Google Ads account that owns your conversion actions, or to the Google Ads manager account that manages it.
  2. In Google Ads, open Data manager and find the Rokt mParticle tile.
  3. Follow the prompts to link Rokt mParticle to your account.

You can create the link on the Google Ads account that owns the conversion actions, or on its parent manager account. If you link a manager account, enter that account’s ID in the Manager Customer ID configuration setting.

Step 2: Turn on Data Manager in mParticle

  1. In mParticle, go to Setup > Outputs and open your Google Enhanced Conversions configuration, or add a new one.
  2. Turn on Use Data Manager. The Google sign-in is hidden, because the Data Manager API doesn’t use it.
  3. Enter your Client Customer ID, and your Manager Customer ID if you linked a manager account in Step 1.
  4. Save the configuration. mParticle checks that Client Customer ID and Manager Customer ID are 10-digit Google Ads account IDs, and that mParticle is linked to your Google Ads account. If you entered a Manager Customer ID, mParticle looks for the link on the manager account. Otherwise, it looks on the client account. If no link is found, an error asks you to link mParticle from the Rokt mParticle tile in Google Ads and save again.

Step 3: Review your connection settings

Connect your inputs to the configuration, or open each existing connection, and confirm its connection settings. The following settings are used only by the Data Manager API:

  • Event Source: Optional. If you leave it blank, mParticle uses App for iOS and Android inputs, Web for web inputs, and Other for all other inputs.
  • Ad Personalization Consent Mapping and Ad Personalization Default Consent Value: Optional. Configure these to forward ad_personalization consent.

Switching an existing configuration

If you turn on Data Manager for a configuration that used the Google Ads API:

  • Shared settings keep their values and continue to apply.
  • If you linked mParticle to the client account rather than a manager account, clear Manager Customer ID. Otherwise mParticle checks for the link on the manager account and the save fails.
  • Set up your Custom Variable Mapping again, using each custom variable’s name instead of its ID. Mappings saved while the configuration used the Google Ads API aren’t carried over to the Data Manager API.
  • The Google Ads API-only Conversion Environment setting is hidden. Use Event Source instead.

Data Manager API event fields

With the Data Manager API, you can send the following optional fields with each conversion as additional signals for Google. These fields are ignored by configurations that use the Google Ads API.

mParticle doesn’t calculate these values. To send one, add it to the event in either of these ways:

  • Event custom attribute: An attribute on the event itself, such as customer_type. Like other event attributes, it’s part of the event data that your other connected outputs can also receive.

    • For commerce purchase events, add a custom attribute to the event, using the name in the Event Custom Attribute column.
    • For events sent through a Custom Mapping, map one of your existing event attributes to that name in the mapping.
  • Custom flag: A value that only this integration reads, such as GoogleEnhancedConversions.CustomerType. Use a custom flag when you want to send the value to Google without adding it to your event data. Set it in your event’s custom flags, using the name in the mParticle Custom Flag column.

Use one of the two. If a field is set both ways, the event custom attribute is used.

For example, either of these commerce events tells Google the purchase came from a new customer:

// Event custom attribute
{
  "event_type": "commerce_event",
  "data": {
    "product_action": { "action": "purchase", "transaction_id": "ORD-123", "total_amount": 49.99 },
    "custom_attributes": { "customer_type": "NEW" }
  }
}

// Custom flag
{
  "event_type": "commerce_event",
  "data": {
    "product_action": { "action": "purchase", "transaction_id": "ORD-123", "total_amount": 49.99 },
    "custom_flags": { "GoogleEnhancedConversions.CustomerType": "NEW" }
  }
}
Event Custom Attribute mParticle Custom Flag Description
event_source GoogleEnhancedConversions.EventSource Where the conversion occurred: WEB, APP, IN_STORE, PHONE, MESSAGE, or OTHER. Overrides the Event Source connection setting for this event. An invalid value is ignored and the connection setting is used.
session_attributes GoogleEnhancedConversions.SessionAttributes The encoded session attributes string that your website read from the Google tag, sent unchanged. See Session attributes.
last_updated_timestamp GoogleEnhancedConversions.LastUpdatedTimestamp When your system last changed this conversion, as an RFC 3339 timestamp with a time zone offset, for example 2026-09-24T18:30:00Z.
customer_type GoogleEnhancedConversions.CustomerType Whether this is a NEW, RETURNING, or REENGAGED customer, based on your own customer data.
customer_value_bucket GoogleEnhancedConversions.CustomerValueBucket How valuable the customer is to you: LOW, MEDIUM, or HIGH, based on your own customer data.

If an optional value is invalid, mParticle drops that field and still sends the rest of the conversion.

Session attributes

Session attributes are an encoded string that the Google tag (gtag.js) creates on your website to describe the visit from a Google ad. Google uses it to match a conversion to the ad click, even when no click ID is available. To use them, your website must read the string from the Google tag when the conversion happens, for example when a lead form is submitted, and send it to mParticle with the conversion. mParticle passes the string to Google unchanged and doesn’t create session attributes. To learn how to capture them, see Google’s session attributes documentation.

Device information

You can send the IP address and other device details with each conversion. The IP address is the only device signal used for matching. Device details can describe two moments:

  • Landing page: the device the user had when they arrived from the ad. Use the event custom attribute landing_page_device_info.{EVENT_CUSTOM_ATTRIBUTE_FIELD} or the custom flag GoogleEnhancedConversions.LandingPageDeviceInfo.{CUSTOM_FLAG_FIELD}.
  • Event: the device the user had when the conversion occurred. Use the event custom attribute event_device_info.{EVENT_CUSTOM_ATTRIBUTE_FIELD} or the custom flag GoogleEnhancedConversions.EventDeviceInfo.{CUSTOM_FLAG_FIELD}.

Replace {EVENT_CUSTOM_ATTRIBUTE_FIELD} or {CUSTOM_FLAG_FIELD} with a field from the table below. For example, to send the IP address captured on the landing page, send landing_page_device_info.ip_address or GoogleEnhancedConversions.LandingPageDeviceInfo.IpAddress. Event custom attributes are set the same way as the other Data Manager API event fields.

Event Custom Attribute Field Custom Flag Field Description
ip_address IpAddress The IPv4 or IPv6 address.
user_agent UserAgent The browser’s user agent string.
category Category The device category, such as desktop or mobile.
language_code LanguageCode The device language.
operating_system OperatingSystem The operating system.
operating_system_version OperatingSystemVersion The operating system version.
model Model The device model.
brand Brand The device brand.
browser Browser The browser name.
browser_version BrowserVersion The browser version.
screen_height ScreenHeight The screen height in pixels.
screen_width ScreenWidth The screen width in pixels.

For event device details, if you don’t provide user agent, language, operating system and version, model, brand, or screen size, mParticle uses the device information it already collected for the event. mParticle never fills in the IP address or any landing page details for you.

Multi-source conversions

With the Data Manager API, you can supplement conversions that your website’s Google tag already records, using a conversion action of type WEBPAGE. To match the website tag’s conversion:

  • Set the event source to WEB, either in the Event Source connection setting or per event.
  • Send the same transaction ID that the website Google tag recorded, using the commerce event’s transaction_id or the mapped order_id attribute.

Google applies a 14-day trial period to new multi-source conversion actions. To learn more, see Google’s conversion adjustments documentation.

Supported Events

Required Event Type

This integration supports two event types:

  1. Commerce Events with the purchase product action type.
  2. Custom events using the custom mapping feature, see the Custom Event Mappings section below.

Supported Identifiers

Google recommends to include as many of the following identifiers as possible, but at a minimum to be forwarded, each outgoing conversion and adjustment must have at least one identifier. If none of the following identifiers are present for an incoming event, the conversion will not be forwarded and a system alert will be reported.

With the Data Manager API, a captured IP address or session attributes can also serve as the identifier for a conversion.

User Identifiers

User Identifiers include the email, phone number, and address info of the user. The Google Ads API doesn’t send them for GBRAID or WBRAID events, but the Data Manager API does.

Email

If specified for a given user, mParticle will try to forward an email identity in an outgoing conversion. This is determined by the Email Identity Type drop-down Connection Setting. mParticle sends emails to Google Ads as SHA-256 hashed values.

Phone Numbers

If specified for a given user, mParticle will try to forward one of the 3 phone number identities in an outgoing conversion. This is determined by the Phone Identity Type drop-down Connection Setting. mParticle sends phone numbers to Google Ads as SHA-256 hashed values.

Address Info

To include address information for a conversion, the following user attributes are required. If any required attribute is missing, address info will not be included with the conversion.

User Attribute Google Ads API Data Manager API
$FirstName (will be SHA-256 hashed) Required Required
$LastName (will be SHA-256 hashed) Required Required
$Address (will be SHA-256 hashed) Required Not required
$City Required Not required
$Country Required Required. Must be an ISO 3166-1 alpha-2 country code.
$Zip Required Required

Order Id

The order_id associated with the conversion. For commerce purchase events, the transaction_id of the product action will be used as the order_id. With the Google Ads API, if a conversion has a GCLID but no order ID, User Identifiers aren’t sent.

With the Data Manager API, the order ID is sent as transaction_id and doesn’t qualify as an identifier on its own. Each conversion must also include a click or braid identifier, a user identifier, an IP address, or session attributes. Otherwise, the conversion isn’t sent.

Click & Braid Identifiers

The Click or Braid Identifier, i.e. the gclid, gbraid, or wbraid associated with the conversion. Note that only one of these will be forwarded for each conversion, with the preference order being: gclid, gbraid, wbraid. Click and Braid Identifiers sent to Google can be configured using Custom Flags or Custom Mappings.

GCLID

GCLID (Google Click Identifier) is the preferred tracking parameter to identify the campaign and other attributes of the click associated with the ad for ad tracking and campaign attribution. GCLID is not available from IOS traffic in some cases due to Apple’s App Tracking Transparency (ATT) policy changes.

GBRAID

GBRAID is used for measuring app-to-app conversions. This new parameter, compliant with Apple’s App Tracking Transparency (ATT) framework, helps measure app conversions driven by ad campaigns on iOS. Note that Custom Variables are not supported for events using this identifier. With the Google Ads API, User Identifiers are also not supported for these events. With the Data Manager API, Google ignores cart data, such as product details, for these events.

WBRAID

WBRAID is used for measuring web-to-app conversions. This new parameter, compliant with Apple’s App Tracking Transparency (ATT) framework, helps attribute conversions back to ad campaigns and work with conversion modeling to give a more accurate measurement on iOS. Note that Custom Variables are not supported for events using this identifier. With the Google Ads API, User Identifiers are also not supported for these events. With the Data Manager API, Google ignores cart data, such as product details, for these events.

Native Field Mappings

mParticle supports the following field mappings for native CommerceEvents:

mParticle Field Google Ads API Field Data Manager API Field Description
event.product_action.transaction_id order_id transaction_id The Order ID
event.product_action.currency currency_code currency ISO 4217 code.
event.timestamp conversion_date_time event_timestamp The date and time of the conversion.
event.product_action.total_amount conversion_value conversion_value The total value of the order or items sold. If omitted, mParticle will try to calculate the total by summing each constituent product total (i.e. item.price*item.quantity).
event.product_action.products[x].price cart_data.items[x].unit_price cart_data.items[x].unit_price The price of the given item.
event.product_action.products[x].quantity cart_data.items[x].quantity cart_data.items[x].quantity Number of the given item.
event.product_action.products[x].id cart_data.items[x].product_id cart_data.items[x].merchant_product_id ID of the given item. With the Data Manager API, it's also sent as item_id when the product has no item_id attribute.
event.product_action.products[x].attributes.item_id Not sent cart_data.items[x].item_id The item's identifier.

Custom Flags

Set these custom flags on your commerce events to send the following fields with each conversion.

mParticle Custom Flag Google Ads API Field Data Manager API Field Is Required Description
GoogleEnhancedConversions.Gclid gclid ad_identifiers.gclid False The identifier you captured at the time of the click for the conversion's click or impression. Populate this field for the most accurate measurement.
GoogleEnhancedConversions.Gbraid gbraid ad_identifiers.gbraid False gbraid is used for measuring app-to-app conversions with Apple's ATT framework. gbraid is sent when gclid is absent.
GoogleEnhancedConversions.Wbraid wbraid ad_identifiers.wbraid False wbraid is used for measuring web-to-app conversions with Apple's ATT framework. wbraid is sent when gclid and gbraid are absent.
GoogleEnhancedConversions.ConversionActionId conversion_action product_destination_id of the destination True The numeric ID of the Google Ads conversion action to record the conversion against. With the Google Ads API, the conversion action must have a type of UPLOAD_CLICKS. With the Data Manager API, it can also be a WEBPAGE conversion action for multi-source conversions. The conversion action must exist in the Google Ads account that tracks conversions for the account associated with the click.
GoogleEnhancedConversions.LocalTransactionCost cart_data.local_transaction_cost cart_data.transaction_discount False The sum of all transaction-level discounts, in the same currency as the conversion.

mParticle includes these values in outgoing events to Google. If these values are set via both custom mappings and custom flags, the custom mapping value will be used.

The Data Manager API supports additional custom flags. See Data Manager API event fields.

Custom Event Mappings

This integration also supports Custom Mappings as well. These can be configured for a particular connection within our UI to support both Click Conversions and Conversion Adjustments, given that the latter don’t map one-to-one with a mP event type. This feature allows incoming mParticle events to be mapped to known Google event types, including specific attributes and outgoing parameters.

Enhanced Conversions for Web

To integrate with Google’s Enhanced Conversions for Web functionality, the Enhancement Adjustment Custom Mapping can be configured via the mParticle UI.

As per Google’s docs, each outgoing Enhancement Adjustment event requires the order_id field, even if the gclid is known as well. If not, it will be dropped instead of forwarded. This is in contrast with other supported event types. See Supported Identifiers for more.

Google Ads has several notions of user-provided consent, only one of which applies to Enhanced Conversions for Leads: ad_user_data. This represents consent for ad user data.

With the Data Manager API, you can also forward ad_personalization consent, which represents consent for ad personalization. It is configured the same way as ad_user_data, using the Ad Personalization Consent Mapping and Ad Personalization Default Consent Value connection settings.

To configure user consent forwarding under this value, a mapping should be set-up leveraging mParticle’s notion of ConsentPurposes. To learn more about handling user consent within mParticle’s platform, see the following docs: Data Privacy Controls.

Once a ConsentPurpose is set-up, user consent information can be associated with it in subsequent EventBatches. The ConsentPurpose 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 field via the ConsentPurpose mapping, a default value can be optionally configured via a separate drop-down setting. When no user consent is provided, the default status is used as specified by the default dropdown setting.

Custom Variable Mapping

All valid incoming events for this integration can optionally specify custom variables to be forwarded along to Google with the given conversion. For this to work, the following needs to occur:

  • The given Custom Variables need to be set-up on Google’s end.
  • The Custom Variable Mapping setting in Connection Settings needs to be configured to map mParticle attributes to a given Google Custom Variable. Identify each custom variable by its ID for the Google Ads API, or by its name for the Data Manager API. With the Data Manager API, Google ignores a name it doesn’t recognize without returning an error, so make sure each name exactly matches the custom variable in Google Ads.
  • The event must not be using a GBRAID or WBRAID identifier.

If you switch a configuration to the Data Manager API, set up your custom variable mappings again, using each custom variable’s name instead of its ID. Mappings saved for the Google Ads API aren’t carried over.

Settings

Settings marked Google Ads API only or Data Manager API only apply to just that API. They’re hidden when the configuration uses the other API. All other settings apply to both.

Configuration Settings

Setting Name Data Type Default Description
Use Data Manager bool False If enabled, mParticle sends supported conversions through Google’s Data Manager API instead of the Google Ads API. Requires mParticle to be linked to your Google Ads account. See Set up with the Data Manager API.
Client Customer ID string null Your Google Ads Client Customer ID. Please contact your Google TAM or AM to obtain this value. For the Data Manager API, this must be the Google Ads account that owns the conversion actions.
Manager Customer ID string null The Customer ID of the Google Ads Manager account that manages the Ads account where data will be sent. If you do not use a manager account, this can be left blank. For the Data Manager API, enter this only if you linked mParticle to the manager account rather than directly to the Client Customer ID account.

Connection Settings

Setting Name Data Type Default Description
Merchant ID string null The ID of the associated Merchant Center account.
Merchant Feed Country Code string null The ISO 3166 two-character region code of the Merchant Center feed.
Merchant Feed Language Code string null The ISO 639-1 language code of the Merchant Center feed.
Email Identity Type enum null The Identity Type to forward as the email to Google. It will be hashed before forwarding.
Phone Identity Type enum null The Identity Type to forward as the phone number to Google. It will be hashed before forwarding.
Conversion Environment enum Unspecified Google Ads API only. Environment of the uploaded conversions, either Unspecified, App, or Web. Google enforces that setting the Conversion Environment is only available to allowlisted Google Ads accounts. Contact your Google rep if you are interested in using this, and use this setting only if your Google account is allowlisted.
Event Source enum null Data Manager API only. Where the conversions occurred: Web, App, In Store, Phone, Message, or Other. If left blank, mParticle uses App for iOS and Android inputs, Web for web inputs, and Other for all other inputs. Can be overridden per event. See Data Manager API event fields.
User Consent Data Mapping mapping null The mParticle ConsentPurpose mapping. This allows user-specified consent values to be forwarded for the ad_user_data field.
Default Ad User Data Consent Value string Unspecified The default consent value to forward for the Ad User Data field.
Ad Personalization Consent Mapping mapping null Data Manager API only. The mParticle ConsentPurpose mapping. This allows user-specified consent values to be forwarded for the ad_personalization field. If the purpose has no consent state, the default value is used.
Ad Personalization Default Consent Value enum Unspecified Data Manager API only. The default consent value to forward for the Ad Personalization field: Unspecified, Granted, or Denied.
Custom Variable Mapping mapping null The mapping of mParticle event attributes to Google Enhanced Conversion custom variables, as defined in Google Ads portal. Mappings aren’t carried over when you switch a configuration to the Data Manager API. When you set them up again, use the custom variable’s name instead of its ID. See Custom Variable Mapping.
Enrich with Cookie Identifiers bool False If enabled, cookie-based identifiers will be stored on a user’s profile, and a batch will be enriched with the most-recently seen identifiers when missing from the batch. Currently, cookie identifiers include only gclid.
    Last Updated: November 20, 2026