CategoriesAll

Event

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.

Native Apps Integration

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.

Required Settings

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:

  1. From the Google Ads dashboard, click Tools > Setup section > select Linked Accounts
  2. Navigate to the Third-party app analytics tile, click Details, select Create Link ID
  3. Navigate to App analytics provider > Other provider, and enter mParticle’s provider ID:
  • 4353943319
  1. Select your app’s platform and find your app in the Look up your app field.
  2. Click the CREATE LINK ID button. The screen refreshes to show you the Third-party app analytics page with the LINK IDs you’ve just created.

You will use this Link ID in the mParticle app when you create a output connection in the Connection Output dialog.

Data Mapping (Native Apps and Web)

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.

Supported Events

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

Unsupported Events

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

Commerce Event Expansion

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.

Attribute Mapping

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

Web Integration

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.

Creating a Conversion ID and Label

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:

  1. It is recommended to click the New tab and follow the instructions on that page to generate a new Conversion ID.
  2. Once you have followed the steps to create a Conversion ID, you must select the Conversion IDs for the Event snippet. You will see a similar dialogue box as below.

  1. In the 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:

  1. Enter your label in the Connection Settings once you connect Google Ads to Javascript as an output:

  1. In the mParticle app, set up the configuration (explained in the Configuration Settings section), and then configure the connection (explained in the Connection Settings section).

Using mParticle’s Events API

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.

Constructing a Correctly Formed User-Agent Header

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

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];
}

Enhanced Conversions

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.

Prerequisites

  • mParticle prequisites:

    • Your web workspace needs to be configured for event batching in order to leverage Enhanced Conversions. If it is not configured for event batching, please contact your customer success manager. To determine if you are on web batching, follow the instructions here.
    • Check both Enable Google Site Tag and Enable Enhanced Conversions in connection settings.

Creating a Conversion ID and Label

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:

  1. Under Enhanced conversions, select Turn on enhanced conversions.
  2. Under Implementation Method, select Global site tag or Google Tag Manager and press NEXT.
  3. You will be prompted for your URL. Enter that into the text field and click CHECK URL.

  1. If mParticle loads Google Tag Manager dynamically for you, Google tells you that the tracking tag was not detected. Click on select one manually. If you don’t see this message, go to the next step.
  2. Click the Global site tag radio button and press NEXT.

  1. Select 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.

mParticle App Configuration/Connection Settings (Native Apps/Web)

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.

Configuration Settings

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

Connection Settings

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?