Integrations
Track purchases, signups and conversions from Google Ads and create Customer Match lists for targeting.
This integration utilizes Google’s Mobile Apps Conversion Tracking and Remarketing API.
There are three distinct ways of integrating with Google Ads from mParticle
This topic will cover using and setting up all of these types of implementations separately.
Regardless of whether you are using iOS, tvOS, or Android, you must first create Link IDs that allow mParticle to send data for your app to use the Google Ads integration.
To use the Google Ads integration, you will need to create a Link ID for your Google Ads account.
Note that, apart from the Link ID, other settings are not required, and are only present in the Dashboard to support an older version of the integration used by a few legacy customers.
To create a Link ID, do the following:
4353943319
You will use this Link ID in the mParticle app when you create a output connection in the Connection Output dialog.
Google’s current conversion tracking API supports a standard list of event types. mParticle events are automatically mapped to the appropriate Google Ads events as follows. The following table shows the data mapping for both native apps and Web.
Google Ads Event | mParticle Event |
---|---|
first_open |
Application State Transition, where install is true and upgrade is false . |
session_start |
Session Start |
view_item |
Commerce Event with a Product Action type of view_detail |
add_to_cart |
Commerce Event with a Product Action type of add_to_cart |
ecommerce_purchase |
Commerce Event with a Product Action type of purchase |
custom |
App Event |
Google Ads Event | Notes |
---|---|
in_app_purchase |
This event should be used only for purchase made in Google Play. For other purchases, use the ecommerce_purchase event. |
view_item_list |
|
view_search_results |
When forwarding Commerce Events, mParticle forwards the main event - ecommerce_purchase
, add_to_cart
, or view_item
- including the event attributes and transaction ID, plus one custom
event for each Product, including the event attributes, product attributes and the Transaction ID.
Google Ads Attribute | mParticle Attribute |
---|---|
app_event_name |
event_name (for App Event only) |
rdid (Raw Device ID) |
ios_advertising_id or android_advertising_id |
id_type |
"idfa" (iOS, tvOS) OR "advertisingid" (Android) |
lat |
device_info.limit_ad_tracking |
app_version |
application_info.version |
os_version |
device_info.version_release (iOS, tvOS) OR device_info.version_release (Android) |
sdk_version |
"mparticle-sdk-i-v<device_info.sdk_version>" (iOS, tvOS) OR "mparticle-sdk-a-v<device_info.sdk_version>" (Android) |
timestamp |
timestamp_unixtime_ms |
value |
product_action.total_amount (purchase only) |
currency_code |
currency_code |
The Google Ads integration requires the mParticle Google Ads Kit when connected to a web input. If you are initializing the web SDK using the Snippet Option then the Kit is automatically included for you. If you are Self Hosting the SDK then you need to add this kit manually into your source code.
The following settings are used for Web-specific configurations. These are the parameters you would set when setting up a Web-specific connection if you are forwarding data collected by mParticle to Google Ads.
You need to create a Conversion ID before you can use the Web integration for Google Ads. The instructions for creating a Conversion ID can be found at the following Google support page:
gtag
function invocation, the last argument is an object with a key of send_to
and a value in the format of “AW-CONVERSIONID/LABEL”. In the above example, the Conversion ID is 753728982
and the label is nl4-CKuq25wBENb7s-cC
Enter your Conversion ID in the Event Configuration Settings when you add an event output:If you are using mParticle’s Android, iOS, or tvOS SDK, the user agent string is automatically collected for you. If you are not using these SDKs, this section explains how to construct the user agent string.
The Google Ads integration utilizes Google’s Mobile Apps Conversion Tracking and Remarketing API. This requires a correctly formatted User-Agent header, retrieved from information about the device.
If you are forwarding data collected by mParticle’s native SDKs, the required information is collected automatically. Note that the one required field is the Advertising ID in the user agent header.
If other values are not present in a batch received using the Events API, mParticle will still attempt to construct a User Agent Header, based on default values. However, mParticle cannot guarantee that this header will be accepted by Google Ads. Therefore, it is important to provide accurate values.
As explained previously, if you are not using mParticle’s Android, iOS, or tvOS SDKs (or are using the mParticle Events API), you will need to ensure the following fields are provided.
mParticle Field | Device Type | Notes |
---|---|---|
device_info.ios_advertising_id |
iOS, tvOS | Required. Will return an error if not present |
device_info.os_version |
iOS, tvOS | iOS version number |
device_info.android_advertising_id |
Android only | |
device_info.build_version_release |
Android only | Android version number |
device_info.locale_language |
Android, iOS, tvOS | 2-character ISO 639-1 Language Code |
device_info.locale_country |
Android, iOS, tvOS | 2-character ISO 3166-1 Country Code |
device_info.device_model |
Android, iOS, tvOS | Model of the device, e.g. iPhone6,1 |
application_info.application_version |
Android, iOS, tvOS | Version number of your app |
device_info.build_identifier |
Android, iOS, tvOS | Build number of the operating system. See the section below about Obtaining Your Build Identifier |
One of the required fields to be included in the user agent string is the build identifier. In order to retrieve the build identifier, you can use one of the following code snippets to retrieve it.
To obtain the device_info.build_identifier
value:
String buildId = Build.ID;
@import Darwin.sys.sysctl;
NSString *buildId(void) {
size_t bufferSize = 64;
NSMutableData *buffer =
[[NSMutableData alloc]
initWithLength:bufferSize];
int status =
sysctlbyname("kern.osversion",
buffer.mutableBytes,
&bufferSize, NULL, 0);
if (status != 0) {
return nil;
}
return [[NSString alloc]
initWithCString:buffer.mutableBytes
encoding:NSUTF8StringEncoding];
}
When using the Google Ads web integration, you have the option of leveraging Google’s Enhanced Conversions. This allows you to send first-party customer data to Google in a secure way. Read more about Google’s Enhanced Conversions and how to set it up on Google’s side here.
mParticle prequisites:
Enable Google Site Tag
and Enable Enhanced Conversions
in connection settings.As with non-enhanced conversions, you will need to create a Conversion ID. Follow those directions from above.
Additionally, there are a few extra steps to set up enhanced conversions in Google’s set up page:
Enhanced conversions
, select Turn on enhanced conversions
.Implementation Method
, select Global site tag or Google Tag Manager
and press NEXT
.CHECK URL
.
select one manually
. If you don’t see this message, go to the next step.Global site tag
radio button and press NEXT
.
Edit code
from the drop down for how you want to set up enhanced conversions.
After completing the set up from Google’s side, you are ready to send Enhanced Conversions via mParticle to Google. Following the Test Search
example below, simply pass unhashed first-party data, to the custom flag "GoogleAds.ECData"
as a Custom Flag containing a stringified JSON Object.
The format of your first party data should follow Google’s support docs here under Identify and define your enhanced conversions variables
. See below for a full example:
mParticle.logEvent(
'Test Search',
mParticle.EventType.Search,
{ attr1: 'value1' },
{ "GoogleAds.ECData": JSON.stringify({
email: 'test@gmail.com',
phone_number: '1-911-867-5309',
first_name: 'John',
last_name: 'Doe',
home_address: {
street: '123 Main St',
city: 'San Francisco',
region: 'CA',
postal_code: '12345',
country: 'US',
}});
});
Per Google’s best practices, mParticle passes a unique ID for each event to Google in the form of a transaction_id
in order to de-duplicate events. If you are logging a purchase event, you are required to provide a transaction ID. Otherwise, the mParticle Web SDK automatically assigns all non-purchase commerce events, page views, and custom events a transaction_id
.
Google Ads has several notions of user-provided consent. Two of these apply to the S2S Google Ads events: ad_user_data
and ad_personalization
. These represent consent for ad user data and ad personalization.
For Web Customers using Google Ads Consent Mode, Google provides two additional fields: ad_storage
and analytics_storage
.
Additionally, based on the configured connection setting, server-to-server calls for iOS, Android and tvOS will indicate whether European regulations apply.
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 Event Batches. 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 can be deprecated in the future.
Regardless of whether you’re configuring/sending data from a Native Apps/Web platform, the following parameters must be set in the mParticle app. The tables below will guide you through what the parameters are and the platform to which they apply.
You will need to set the following parameters in the Setup > Outputs > Google Ads > Configuration settings dialog.
Setting Name | Data Type | Default Value | Platform | Description |
---|---|---|---|---|
Configuration Name | string |
All | The descriptive name you provide when creating the configuration. This is the name you will use when setting up the output connection to Google Ads. | |
Conversion ID | string |
All | The conversion ID provided in your Google Ads conversion tracking code snippet. This is only used for the legacy version of Google Ads | |
App Install Conversion Label | string |
Native Apps | The label provided in your Google Ads conversion tracking code snippet for app installs. This is only used for the legacy version of Google Ads |
When you are ready to use the Google Ads output from the data sent to mParticle, you must enter the following information in the Connections > [Web/iOS/Android/tvOS] > Connected Outputs > Google Ads dialog.
Setting Name | Data Type | Default Value | Platform | Description |
---|---|---|---|---|
Labels | Custom Field |
All | The mapping of your events to Google Ads conversion labels provided in the Google Ads conversion actions section under the ‘Set up your tracking method’ heading Note that there are a maximum of 50 Labels allowed. This is only used for the legacy version of Google Ads |
|
Custom Parameters | Custom Field |
Web | The mapping of your event attributes to Google Ads custom parameters as setup in the tracking template field under Campaign Advanced Settings. (Max # of Mappings Allowed: 3) Note that there are a maximum of three (3) Custom Parameters allowed. |
|
Link ID | string |
iOS, Android, tvOS | The unique identifier for binding a specific app to a specific developer token. If not present, we will use the legacy version of Google Ads | |
Remarketing Only | bool |
False | Web | If enabled, the integration is set to remarketing only mode which allows you to improve your marketing campaign’s targeting. |
Enable Google Site Tag | bool |
False | Web | If enabled, the Google Site Tag (gtag) JavaScript tagging framework and API is used for conversion tracking. |
Applies European Regulations | bool |
False | iOS, Android, tvOS | If enabled, server-to-server calls will indicate that European regulations apply. |
Consent Data Mapping | mapping |
null | All | A mapping of mParticle consents to Google Ads consents. |
Ad User Data Default Consent Value | string |
Unspecified |
All | The default consent value to forward for the Ad User Data field. |
Ad Personalization Default Consent Value | string |
Unspecified |
All | 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 |
Was this page helpful?