Search documentation...

K
ChangelogBook a demoSign up

Google Ads

Empower your marketing team to run highly granular retargeting and lookalike campaigns on Google

Supported syncing

Sync TypeDescriptionSupported Sync ModesAPI Reference
Customer Match User ListCreates a customer list for the Customer Match feature of Google Ads. Segments are automatically created in Google Ads based on the name of the modelAdd, Update, RemoveCustomer Match User List
Click ConversionsSends click conversion tracking information to Google Ads for each record in the query resultsInsertClick Conversions
Click Conversion AdjustmentsSends click conversion adjustments to Google Ads for each record in the query resultsInsertClick Conversion Adjustments
Call ConversionsSends call conversion tracking information to Google Ads for each record in the query resultsInsertCall Conversions
Offline Store ConversionsSends offline store sales conversion tracking information to Google Ads for each record in the query resultsInsertOffline Store Conversions

For more information about sync modes, refer to the sync modes docs.

API version in use: v16

Connect to Google Ads

Go to the Destinations overview page and click the Add destination button. Select Google Ads and click Continue. You can then authenticate Hightouch to Google Ads via OAuth.

Click Log in to Google Ads, log in with your Google Account, and click Allow. You should then see a success notification in the Hightouch UI.

Sync configuration

Once you've set up your Google Ads destination and have a model to pull data from, you can set up your sync configuration to begin syncing data. Go to the Syncs overview page and click the Add sync button to begin. Then, select the relevant model and the Google Ads destination you want to sync to.

Select account

To begin, select the account you want to sync data to. If an account appears at the top level, it means you have direct access to that ad account or manager account. Hightouch accesses nested accounts via the root account that you have direct access to.

Select Google Ads account

In the preceding example screenshot, the authenticated account has direct access to the Hightouch (5138398925) ad account and the Hightouch Manager Account (5277198417). The authenticated account also has access to the manager account's three nested accounts, including the Hightouch (5138398925) ad account.

Selecting either account at the top level syncs directly to those accounts without logging in via another manager account. Selecting a nested account requires Hightouch to login via the root manager account.

Syncing customer match user lists

Google's Customer Match tool lets you use the online and offline data your customers have shared with you to deliver targeted ads.

Hightouch lets you create and maintain customer match lists via the Google Ads API. It can take 6 to 48 hours for a list to be populated with members once Hightouch has sent the data to Google. You can find more information about this on the API reference page linked in the supported syncing section.

User list type

To begin, select the upload key type for the customer match list. It can be one of these values:

  • CONTACT_INFO
  • MOBILE_ADVERTISING_ID
  • CRM_ID

Selecting user list type

Choose the type that aligns with the data fields you are sending. For example, if you are sending email or address data, select CONTACT_INFO.

Select an existing list or create a new one

You can create a new Customer match user list or use an existing one. When creating a new list, you can optionally enter a name. Otherwise, Hightouch defaults to the name of the associated model.

New user list

To use an existing list, select the desired list from the dropdown.

Existing user list

If you choose to create a new list, you can't update the account to which you're syncing data after the initial sync run. If you need to change the account, configure a new sync.

Optionally, you can also set the membership lifespan for the list. The value must be between 0 and 540. If you do not set this value, the default value is 30. Check the Do not expire box if you want your users' cookies to stay on your list indefinitely.

User list membership lifespan

User identifiers

To identify which users to add or update in an audience, select model columns and the corresponding Google Ads fields. You must map at least one identifier.

Increase match rates in Google Ads customer match lists by enabling Match Booster.

Customer match user lists field mapping

Handling PII and hashing

You can enable PII hashing if you wish for Hightouch to detect whether your data requires normalization and hashing based on the chosen record mapping. For example, if you select Email and the model column with the email data is unhashed, Hightouch hashes the value for you.

By default, Hightouch automatically detects if the following fields require hashing:

  • Email
  • Phone
  • First Name
  • Last Name

PII hashing

Cleaning your data

Optionally, you can decide if Hightouch should clean your phone numbers and remove null or incorrectly formatted values from your data.

Clean phone numbers and remove null or incorrectly formatted fields

Delete behavior

The delete behavior you select dictates what to do when a row no longer appears in your model's query results. You have the following options:

BehaviorDescription
Do nothingKeep the record in the audience
Remove recordRemove the Google Ads record from the specified audience

If you are uploading data for users in the European Economic Area (EEA), you need to ensure you are passing the required consent signals to Google.

For each sync, you can specify the consent status for these types:

  • ad_user_data: consent for sending user data to Google for advertising purposes
  • ad_personalization: consent for ad personalization

Check out Google's support doc to learn more.

Syncing conversion events

Hightouch supports syncing the following conversion events:

When syncing conversion events, Hightouch treats any records added to your source as new events and sends them to Google Ads when your sync runs.

To ensure syncs send each event, your event model must use a truly unique primary key. See the events syncs documentation for more information.

Custom conversion variables

You can map custom variables when syncing conversion events to Google Ads. First, you need to set up custom conversion variables in Google. Custom conversion variables are only available for the following:

You can read more about this in Google Ads Help and also in Google Ads' API documentation.

Currency codes

Google requires all conversion events to include a currency code in a separate column in addition to the amount. This applies to click conversions, click conversion adjustments, and offline store conversions. Consult Google's chart of supported currency codes to ensure your data meets their specifications.

Enhanced conversions

You can sync both types of Enhanced conversions to Google Ads using Hightouch:

  1. Enhanced conversions for leads: set up an Offline click conversion in Google Ads; then select Click Conversions as the sync type and set up your field mappings accordingly
  2. Enhanced conversions for web: select Click Conversion Adjustments as the sync type and Enhancement as the adjustment type

If you are uploading data for users in the European Economic Area (EEA), you need to ensure you are passing the required consent signals to Google.

For click conversions, call conversions and offline store conversions, you can specify the Google consent status for advertising purposes, by mapping these fields in the sync configuration:

  • Ad user data consent (for the ad_user_data property)
  • Ad personalization consent (for the ad_personalization property)

As per Google's API documentation, these fields only accept the following values: ​GRANTED​, ​DENIED​, UNSPECIFIED​, ​UNKNOWN​.

Check out Google's support doc to learn more.

Syncing click conversions

Google Ads allows you to import conversions from ad clicks to see how your online ads are performing. Before setting up your sync, you need to set up a conversion action in Google Ads.

After clicking New conversion action, remember to select Website.

Setting up conversion action

It can take over 24 hours for click conversions to be processed by Google. You can find more information about this and other requirements on the API reference page linked in the supported syncing section.

Offline click conversions

Offline click conversions are not offline store conversions.

You can sync offline click conversion imports which allow you to measure what happens in the offline world after an ad results in a click or call to your business. For these events, you need to set up offline conversion imports.

After clicking New conversion action, remember to select Import.

Setting up conversion action

Then select CRMs, files, or other data sources and Track conversions from clicks and continue the offline conversion import setup. You can safely skip setting up a data source.

Import offline conversions

Check out our blog post and playbook to learn how to sync offline click conversions to Google Ads.

Select conversion action

Select the conversion action you previously set up in your Google Ads account. The dropdown menu displays the conversion action IDs present in your Google Ads account.

Select conversion action

User identifiers

Select which columns to sync from your source to Google Ads' fields. When syncing click conversions, at least one identifier is required:

  • GCLID
  • GBRAID
  • WBRAID
  • User hashed email(s)
  • User hashed phone(s)

Furthermore, Conversion time is a mandatory field.

Click conversion field mapping

You can send enhancements as click conversions by mapping the User hashed email(s) and User hashed phone(s) fields instead of GCLID. The model columns mapped to these fields can contain either single values or arrays. Read through Google Ads' API documentation for more details.

If you opt to send user emails and/or phone numbers instead of GCLID, keep in mind that each click conversion can only have up to five user identifiers in total. For example, a click conversion can have three emails and two phone numbers, or any combination that adds up to five.

These enhancements are also referred to as Enhanced conversions for leads. They are not Enhanced conversions for web, which are described in the Syncing click conversion adjustments section.

Avoid storing your GCLID, GBRAID, and WBRAID data in the same model column since this can cause issues when syncing your data. Google Ads' limitations determine which values can and cannot be synced together. If this data is in the same model column and you try mapping this column to multiple Google Ads fields (such as GCLID and WBRAID), you might receive a VALUE_MUST_BE_UNSET or GBRAID_WBRAID_BOTH_SET error. Check out the common errors section to learn more about these errors.

If a model row contains a null value in a model column mapped to the GCLID, GBRAID, or WBRAID fields, Hightouch ignores that value when syncing the row Google Ads. This process helps reduce VALUE_MUST_BE_UNSET or GBRAID_WBRAID_BOTH_SET errors.

Learn more about the EU consent policy in this section.

Syncing click conversion adjustments

After sending a click conversion to Google Ads, you can adjust the conversion later by sending a click conversion adjustment. Wait at least 24 hours after a click conversion is reported to Google Ads before adjusting it to avoid a CONVERSION_NOT_FOUND or TOO_RECENT_CONVERSION error. You can find more information about this on the API reference page linked in the supported syncing section.

Select conversion action and adjustment type

Select the conversion action you previously set up in your Google Ads account. The dropdown menu displays the conversion action IDs present in your Google Ads account.

You also need to select the adjustment type. You can choose from:

Select conversion action and adjustment type

Enhancements are also referred to as Enhanced conversions for web. They are not Enhanced conversions for leads, which are described in the Syncing click conversions section.

If you select the Enhancement adjustment type, you need to select if this is a first party or third party data upload.

First or third party data upload

Field mapping

Select which columns to sync from your source to Google Ads' fields:

  • GCLID
  • Conversion time
  • Adjustment time
  • Order ID

If you select the Retraction adjustment type, you can only map those fields.

Retraction field mapping

If you select the Restatement adjustment type, you can map those four fields plus:

  • Restatement value, which is mandatory
  • Restatement currency

Restatement field mapping

If you select the Enhancement adjustment type, you can map those four fields plus:

  • Enhancement User Agent
  • various hashed fields: Email, Phone, First Name, Last Name, Street Address
  • Country
  • Postal Code
  • State
  • City

Enhancement field mapping

Handling PII and hashing

You can find more information about this in the PII and hashing section.

Syncing call conversions

Google Ads allows you to import phone call conversions to keep track of how your calls impact your ad campaigns. After setting up phone call conversions, you can use Hightouch to sync your data to Google Ads. You can find more information about this on the API reference page linked in the supported syncing section.

Select conversion action

Select the conversion action you previously set up in your Google Ads account. The dropdown menu displays the conversion action IDs present in your Google Ads account.

Select conversion action

Field mapping

Select which columns to sync from your source to Google Ads' fields. Conversion time, Caller ID, and Call start time are mandatory fields.

Call conversion field mapping

Learn more about the EU consent policy in this section.

Syncing offline store conversions

Offline store conversions are not offline click conversions.

Google Ads offers enhanced store sales measurement and reporting data to better optimize your online ads. After setting up offline store sales conversions, you can use Hightouch to sync your data to Google Ads. You can find more information about this on the API reference page linked in the supported syncing section.

Select conversion action

Select the conversion action you previously set up in your Google Ads account. The dropdown menu displays the conversion action IDs present in your Google Ads account.

Select conversion action

Optional settings

You can decide if you would like to include the following information:

  • custom key, to segment store sales conversions
  • loyalty fraction, which is a decimal value that sets the percentage of overall sales that can be associated with a customer
  • transaction upload fraction, which is a decimal value that sets the percentage of overall sales with customer information that are already uploaded to Google Ads

Offline store conversions optional settings

First or third party data

You need to select if this is a first party or third party data upload.

First or third party data upload

Field mapping

Select which columns to sync from your source to Google Ads' fields. Transaction time and Transaction amount (micros) are mandatory fields.

Offline store conversions field mapping

Any transaction amount here should be in the unit micros. For example, $200 = 200000000.

Learn more about the EU consent policy in this section.

Handling PII and hashing

You can find more information about this in the PII and hashing section.

Cleaning your data

You can find more information about this in the Cleaning your data section.

Tips and troubleshooting

Matched users count

Below only applies to the customer match user list sync type.

Hightouch retrieves the audience metadata from Google Ads in real-time. The matched number displayed in Hightouch should reflect what you see in Google Ads. Note that the matched numbers are approximated to maintain privacy thresholds. Hightouch takes the matched count to calculate a match rate for your sync, where applicable. The calculation breakdown:

matched_user_count / # of rows queried in the latest sync run

The match rate is

not

calculated when:
  • syncing to an existing segment because the total number of records to ever be uploaded to the segment is unknown
  • removed users from your model is not removed in Google Ads because the matched user count would be inflated in the calculation

Common causes for low match rates:

  • Your audience model is too small. Most ad platforms do not display the matched number unless there's at least one thousand matched users to maintain privacy thresholds.
  • The upload is still processing. We recommend waiting at least

    72 hours

    from the first sync run for numbers to settle.
  • Your data isn’t cleaned or hashed properly. Hightouch normalizes and hashes your data according to destination requirements, but it’s still good to make sure that the data is as clean as possible. Note that Hightouch cannot clean your data if you opt to hash it yourself. In that case, ensure you follow the data cleaning requirements forGoogle Ads.

Google Ads contain a few different matched users count in their platform. Hightouch refers to the display network size and the search network size. If the display network size is available, that is used in our app, else the search network size is used. Google Ads also have a concept of a match rate but this is different than what Hightouch is calculating, which is the % of targetable users from your model in this GoogleAds audience. Per Google, ”Your Customer Match match rate is the percentage of your uploaded customer list that could be connected to Google users, so you can see how much of your list is usable. Keep in mind that your match rate is not an indicator of how your lists will perform, but rather an indicator of whether you're uploading the right data in the right way” (reference).

Common errors

If you encounter an error or question not listed below and need assistance, don't hesitate to . We're here to help.

At least one click identifier ('gclid', 'gbraid' or 'wbraid') is required

Make sure that you mapped at least one identifier when syncing Click conversions.

CONVERSION_PRECEDES_EVENT

As described in Google Ads' documentation, this error occurs if the imported event has a conversion_date_time that precedes the click. To avoid this error, make sure that the timestamps in your source data and your Google Ads account have the same timezone configured.

EXPIRED_EVENT

As explained in Google Ads' documentation, this error happens when a click conversion can't be accepted since its click occurred before this conversion's click-through window.

GBRAID_WBRAID_BOTH_SET

This error happens if you sync data both to the GBRAID and WBRAID fields. You can read more about this in Google Ads' API documentation.

INCOMPATIBLE_UPLOAD_KEY_TYPE

When syncing Customer Match user lists, make sure to select the correct user list type. If you selected the wrong type when setting up your sync, create a new sync with the correct type.

INVALID_CONVERSION_ACTION

When syncing Click conversions, ensure that you've chosen the correct conversion type within the Google Ads UI. For normal Click conversions, choose the Website type. For Offline click conversions, choose the Import type.

Furthermore, make sure that:

  • your data satisfies the requirements outlined in this section of Google Ads' API documentation
  • you selected the correct Google Ads account in your sync configuration

INVALID_CUSTOMER_ID

You may receive a 400 - {"error":{"code":400,"message":"Request contains an invalid argument."..."message":"Invalid customer ID...} error message because you are attempting to sync to a Google account that is different from the initial sync.

If there has been a successful initial sync with sync configurations of Customer Match User List and Create a new user list, changing the Google account will result in sync failure on the next run. You can resolve the error by either:

  • Selecting the original Google account that was used on the initial sync
  • Creating a new sync and selecting the new Google Account

INVALID_GRANT

The token for the user that connected the Google Ads destination has expired or revoked. Please re-auth within the destination settings.

No error message provided

This error can happen if you rename a model column after adding it as a field mapping in your sync configuration. To resolve this, update your field mappings to contain the updated model column names.

REQUIRED_FIELD_MISSING

Customer Match User Lists require at least one personal identifier. Check the required fields relevant for the match list type you've chosen.

UNAUTHORIZED_CUSTOMER

This can happen when you try syncing a click conversion to Google Ads that is associated with a different ad account. If you wish to sync click conversions from different ad accounts without needing to use separate syncs, you can set up a manager account and enable cross-account conversion tracking.

VALUE_MUST_BE_UNSET

This error happens if you:

  • sync data to the GCLID field and also to the GBRAID or WBRAID fields
  • sync data to custom conversion variables and also to the GBRAID or WBRAID fields

You can read more about this in Google Ads' API documentation.

Live debugger

Hightouch provides complete visibility into the API calls made during each of your sync runs. We recommend reading our article on debugging tips and tricks to learn more.

Sync alerts

Hightouch can alert you of sync issues via Slack, PagerDuty, SMS, or email. For details, please visit our article on alerting.

Ready to get started?

Jump right in or a book a demo. Your first destination is always free.

Book a demoSign upBook a demo

Need help?

Our team is relentlessly focused on your success. Don't hesitate to reach out!

Feature requests?

We'd love to hear your suggestions for integrations and other features.

Last updated: Aug 22, 2024

On this page

Supported syncingConnect to Google AdsSync configurationSelect accountSyncing customer match user listsSyncing conversion eventsSyncing click conversionsSyncing click conversion adjustmentsSyncing call conversionsSyncing offline store conversionsTips and troubleshootingMatched users countCommon errorsLive debuggerSync alerts

Was this page helpful?