This integration allows you to write Treasure Data job results directly in the Google Ads Server to improve the accuracy of your conversion measurements. In Google Ads, a conversion is when a user performs some specified action after clicking an ad or viewing a Display Network ad, such as purchasing a product, installing a mobile app, or signing up for an email list.
Conversion tracking provides critical insights into users' actions after viewing or clicking an ad. The below conversion data is supported in this integration:
- Offline click conversion
- Enhanced conversion for Lead
- Enhanced conversion for Web
- Offline call conversion
- Store sales conversion (for eligible Advertisers only)
Basic knowledge of Treasure Data, including TD Toolbelt.
Documentation: Google Ads API
Setup guide:
A Google Ads Account with admin permissions to use Enhanced Conversions features by Google.
Authorize the Treasure Data Google OAuth app to access your Google Ads account.
You must specify columns with the exact names in lowercase and data types corresponding to the selected Conversion Action Type.
For Store Sales conversion, upload at least a few hundred transactions to increase the likelihood that the job will not fail with an
Insufficient transactionserror.Uploading jobs can take up to 24 hours to proceed entirely by Google.
To use Custom Variable with Store Sales conversion:
- Enable one Custom Variable for the Store Sales conversion on the Google Ads UI.
- If the custom variable is enabled for Store Sales, the variable name must be filled in on the Configuration screen of this integration.
You must create and configure the data connection on TD Console before running your query. As part of the data connection, you provide authentication to access the integration using the following steps.
- Open TD Console.
- Navigate to Integrations Hub > Catalog.
- Search for and select Google Enhanced Conversion via Google Ads.
- Select Create Authenticationand provide the OAuth of a Google account with access to the target Google Ads account.
- Select **Continue,**enter a name for the Authentication, and then select Done.
The TD Console supports multiple ways to export data. Complete the following steps to export data from the Data Workbench.
- Navigate to Data Workbench > Queries.
- Select New Query and define your query.
- Select Export Results and configure the data exporting.
- Select an existing Google Enhanced Conversion authentication or create a new one.
- Configure the exporting parameters and select Done
| Parameter | Type | Description | Required |
|---|---|---|---|
| Customer ID | number | Displays the Google Ads account number without the hyphen. | Yes |
| Conversion Action Type | dropdown | Select one of the supported conversion types. | Yes |
| Custom Variable | string | If used, you must declare the Custom Variable name for Store Sales. | |
| Skip on invalid records | checkbox | Any valid records encountered during the data export process are skipped when selected. |
- Select Done.
From Google: after March 6th, 2024, Google Ads will no longer accept uploads of Customer Match, conversions, and store sales data for EU users without valid consent. Any audiences with "UNSPECIFIED" or "UNKNOWN" consent for EU users will not be processed. Specify consent value (and contact your Google Representative if your account needs to be whitelisted for consent upload). This integration will send ad_user_data consent when specified (refer to https://developers.google.com/google-ads/api/reference/rpc/v15/Consent.)
To be accepted, the exported data must follow specific formatting guidelines. Incorrect formatting can lead to an upload error or a low number of matched records.
- Hashing requirement: User-identifiable information must be hashed using SHA-256 after being normalized ( lowercase, no white space before or after). If the data is plain text, the integration will automatically be applied to the following fields:
- phone_number, phone_number_1, phone_number_2, phone_number_3, phone_number_4
- first_name
- last_name
- street_address
- Data format requirements:
- Phone number: use the E.164 format, for example, +1234567890
- Country code: 2-letter country code in ISO-3166-1 alpha-2
- Datetime (conversion_date_time, adjustment_date_time, ...): the format is
**YYYY-MM-DD HH:MM:SS[+/-HH:MM]**, where [+/-HH:MM] is an optional timezone offset from UTC. If the offset is absent, the API will use the account's timezone as default. Examples: "2018-03-05 09:15:00" or "2018-02-01 14:34:30+03:00" - Currency code: ISO 4217
- Column names: All name are in lowercase and cannot be duplicated.
| Field Name (Output Schema) | Description | Data Type | Required? |
|---|---|---|---|
| gbraid | The click identifier for clicks associated with app conversions and originating from iOS devices starting with iOS14. | String | Yes - one of these fields must have a value. |
| The click identifier for clicks associated with web conversions and originating from iOS devices starting with iOS14. | String | ||
| gclid | The Google click ID (gclid) that is associated with this conversion. | String | |
| external_attribution_data | Additional data about externally attributed conversions. This field is required for conversions with an externally attributed conversion action but should not be set otherwise. | String of serialized JSON object { "external_attribution_credit": 1.2, "external_attribution_model": "sample model"} | No |
| custom_variables | The custom variables associated with this conversion. | String of serialized array JSON object [{ "conversion_custom_variable": 1, "value": "1"}] | No |
| cart_data | The cart data associated with this conversion | String of serialized JSON object { "merchant_id": 111, "feed_country_code": "US", "feed_language_code": "en", "local_transaction_cost": 1.2, "items": [{ "product_id": "123", "quantity": 2, "unit_price": 1.2 }]} | No |
| conversion_environment | The environment in which this conversion was recorded was an app or web. | String Accepted value: UNSPECIFIED, UNKNOWN, APP, WEB | No |
| conversion_action_id | Resource name of the conversion action associated with this conversion. | ||
| conversion_date_time | The date and time at which the conversion occurred must be after the click time. The timezone must be specified. The format is "yyyy-mm-dd hh:mm:ss+ | -hh:mm," for example, "2019-01-01 12:32:45-08:00." | String |
| conversion_value | The value of the conversion for the advertiser. | Double | Yes |
| currency_code | Currency associated with the conversion value. This is the ISO 4217 3-character currency code. For example: USD, EUR. | String | Yes |
| order_id | The order ID associated with the conversion. An order ID can only be used for one conversion per conversion action. | String | No |
| consent | The explicit Ads consent declaration for the European Economic Area users. | String Accepted value: UNSPECIFIED, GRANTED, DENIED | No |
The user identifier fields: email, phone_number, phone_number_1, phone_number_2, phone_number_3, phone_number_4.
The minimum input is at least one user identifier (email or phone); the maximum is five user identifiers.
| Field Name (Output Schema) | Description | Data Type | Required? |
|---|---|---|---|
| custom_variables | The custom variables associated with this conversion. | String of serialized array JSON object [ { "conversion_custom_variable": 1, "value": "1" }] | No |
| cart_data | The cart data associated with this conversion. | String of serialized array JSON object { "merchant_id": 111, "feed_country_code": "US", "feed_language_code": "en", "local_transaction_cost": 1.2, "items": [{ "product_id": "123", "quantity": 2, "unit_price": 1.2 }]} | No |
| Support a maximum of 5 user identifiers (email and phone_number) | String (hashing requirement) | Yes - at least one of the two field names must have a value | |
| phone_number | Can support multiple phone numbers as prefix: phone_number, phone_number_1, phone_number_2, phone_number_3, phone_number_4 | String (hashing requirement) | |
| conversion_environment | The environment in which this conversion was recorded was an app or web. | String Accepted value: UNSPECIFIED, UNKNOWN, APP, WEB | No |
| gclid | The Google click ID (gclid) that is associated with this conversion. | String | No |
| conversion_action_id | The resource name of the conversion action associated with this conversion. | ||
| conversion_date_time | The date and and time at which the conversion occurred must be after the click time. The timezone must be specified. The format is "yyyy-mm-dd hh:mm:ss+ | -hh:mm," for example, "2019-01-01 12:32:45-08:00." | String |
| conversion_value | The value of the conversion for the advertiser. | Double | Yes |
| currency_code | Currency associated with the conversion value. This is the ISO 4217 3-character currency code. For example: USD, EUR. | String | Yes |
| order_id | The order ID that is associated with the conversion. An order ID can only be used for one conversion per conversion action. | String | No |
| consent | The explicit Ads consent declaration for the European Economic Area users. | String Accepted value: UNSPECIFIED, GRANTED, DENIED | No |
The user identifier fields: email, phone (phone_number, phone_number_1, phone_number_2, phone_number_3, phone_number_4), address (first_name, last_name, country_code, postal_code, street_address).
The minimum input is at least one user identifier (email, phone, address) with a maximum of five user identifiers.
| Field Name (Output Schema) | Description | Data Type | Required? |
|---|---|---|---|
| gclid_date_time_pair | String of serialized JSON object { "gclid": "gclid", "conversion_date_time": "2023-10-10 10:10:10+07:00"} | No | |
| Supports a maximum of five user identifiers (email, phone_number, and address) | String (hashing requirement) | Yes | |
| phone_number | Can support multiple phone numbers as prefix: phone_number_1, phone_number_2, phone_number_3, phone_number_4 | String (hashing requirement) | Yes |
| first_name | Address information | String (hashing requirement) | Yes |
| last_name | String (hashing requirement) | Yes - Required only when a first_name is included | |
| country_code | String | Yes - Required only when a first_name is included | |
| postal_code | String | Yes - Required only when a first_name is included | |
| street_address | String (hashing requirement) | No | |
| order_id | The order ID associated with the conversion. An order ID can only be used for one conversion per conversion action. | String | Yes |
| conversion_action_id | The resource name of the conversion action associated with this conversion. | ||
| adjustment_date_time | The date and time at which the adjustment occurred must be after the conversion_date_time. The timezone must be specified. The format is "yyyy-mm-dd hh:mm:ss+ | -hh:mm," for example, "2019-01-01 12:32:45-08:00." | String |
| user_agent | The user agent to enhance the original conversion. This can be found in your user's HTTP request header when they convert on your web page. Example "Mozilla/5.0 (iPhone; CPU iPhone OS 12_2 like Mac OS X)". Enhancements can only specify the user agent with user identifiers. This should match the user agent of the request that sent the original conversion, so the conversion and its enhancement are either both attributed as same-device or both attributed as cross-device. | String | No |
| Field Name (Output Schema) | Description | Data Type | Required? |
|---|---|---|---|
| custom_variables | The custom variables associated with this conversion. | String of a serialized array JSON object [ { "conversion_custom_variable": 1, "value": "1" }] | No |
| caller_id | The caller ID from which this call was placed. The caller ID is expected to be in E.164 format with a preceding '+' sign, for example, "+16502531234." | String | Yes |
| call_start_date_time | The date and time at which the call occurred. The timezone must be specified. The format is "yyyy-mm-dd hh:mm:ss+ | -hh:mm," for example, "2019-01-01 12:32:45-08:00". | String |
| conversion_action_id | The resource name of the conversion action associated with this conversion. | ||
| conversion_date_time | The date and time at which the conversion occurred must be after the click time. The timezone must be specified. The format is "yyyy-mm-dd hh:mm:ss+ | -hh:mm," for example, "2019-01-01 12:32:45-08:00." | String |
| conversion_value | The value of the conversion for the advertiser. | Double | No |
| currency_code | The currency associated with the conversion value is the ISO 4217 3-character currency code, such as USD or EUR. | String | No |
| consent | The explicit Ads consent declaration for the European Economic Area users. | String Accepted value: UNSPECIFIED, GRANTED, DENIED | No |
| Field Name (Output Schema) | Description | Data Type | Required? |
|---|---|---|---|
| String (hashing requirement) | Yes - email or phone number must have a value. Otherwise, the address information must have a value. | ||
| phone_number | Can support multiple phone numbers as prefix: phone_number, phone_number_1, phone_number_2, phone_number_3, phone_number_4 | String (hashing requirement) | |
| first_name | Address info When neither email or phone number has a value, all these fields are required. | String (hashing requirement) | |
| last_name | String (hashing requirement) | ||
| city | String | ||
| state | String | ||
| country_code | String | ||
| postal_code | String | ||
| tran_datetime | Timestamp when the transaction occurred. The format is "YYYY-MM-DD HH:MM:SS[+/-HH:MM]" | String | Yes |
| tran_amount | Transaction amount in micros. Transaction amount in micros needs to be greater than 1000 | Double | Yes |
| tran_currency | Transaction currency code. ISO 4217 three-letter code is used | String | Yes |
| conversion_action_id | The ID of the Store Sales conversion action | String | Yes |
| order_id | The transaction order id | String | No |
| custom_value | When a custom variable name is filled in the Configuration screen, this field must exist The value must be pre-defined in the Custom Variable for Store Sales on the Google Ads UI | String | No |
| consent_user_data | The explicit Ads consent declaration for the European Economic Area users | String Accepted value: UNSPECIFIED, GRANTED, DENIED | No |
| consent_personalize | The explicit Ads consent for personalized advertising | No |
custom object query
SELECT gclid, external_attribution_data, custom_variables, cart_data, conversion_action_id, conversion_date_time, conversion_value, currency_code, order_id, consent, email, phone_number, phone_number_1, first_name, last_name, city, state, country_code, postal_code, street_address, gclid_date_time_pair, adjustment_date_time, user_agent, caller_id, call_start_date_timeFROM tableYou can also send segment data to the target platform by creating an activation in the Audience Studio.
- Navigate to Audience Studio.
- Select a parent segment.
- Open the target segment, right-mouse click, and then select Create Activation.
- In the Details panel, enter an Activation name and configure the activation according to the previous section on Configuration Parameters.
- Customize the activation output in the Output Mapping panel.
- Attribute Columns
- Select Export All Columns to export all columns without making any changes.
- Select + Add Columns to add specific columns for the export. The Output Column Name pre-populates with the same Source column name. You can update the Output Column Name. Continue to select + Add Columnsto add new columns for your activation output.
- String Builder
- + Add string to create strings for export. Select from the following values:
- String: Choose any value; use text to create a custom value.
- Timestamp: The date and time of the export.
- Segment Id: The segment ID number.
- Segment Name: The segment name.
- Audience Id: The parent segment number.
- + Add string to create strings for export. Select from the following values:
- Set a Schedule.
- Select the values to define your schedule and optionally include email notifications.
- Select Create.
The TD Toolbelt can trigger the Query Result exporting from a CLI. You need to specify the parameters for the exporting job using the --result option of the td query command. For more information, please refer to this article.
The format of the option is JSON, and the general structure is as follows.
Case UPLOAD_OFFLINE_CLICK_CONVERSION{ "type": "google_enhanced_conversion_via_google_ads", "td_authentication_id": "td_authentication_id", "customer_id": 9491028710, "conversion_type": "upload_offline_click_conversion", "skipInvalid_records": true}Case UPLOAD_ENHANCED_FOR_LEAD{ "type": "google_enhanced_conversion_via_google_ads", "td_authentication_id": "td_authentication_id", "customer_id": 9491028710, "conversion_type": "upload_enhanced_for_lead", "skipInvalid_records": true}Case UPLOAD_ENHANCED_FOR_WEB{ "type": "google_enhanced_conversion_via_google_ads", "td_authentication_id": "td_authentication_id", "customer_id": 9491028710, "conversion_type": "upload_enhanced_for_web", "skipInvalid_records": true}Case UPLOAD_CALL_CONVERSION{ "type": "google_enhanced_conversion_via_google_ads", "td_authentication_id": "td_authentication_id", "customer_id": 9491028710, "conversion_type": "upload_enhanced_conversion_via_google_ads", "skipInvalid_records": true}Case UPLOAD_STORE_SALES{ "type": "google_enhanced_conversion_via_google_ads", "td_authentication_id": "td_authentication_id", "customer_id": 9491028710, "conversion_type": "upload_store_sales", "custom_variable": "custom_variable_name", "skipInvalid_records": true}| Name | Description | Value | Default Value | Required |
|---|---|---|---|---|
| type | ||||
| td_authentication_id | This is the ID of the existing Google Enhanced via Google Ads authentication on the TD console. | Number | Null | No |
| customer_id | The account ID of the customer. | String | Yes | |
| conversion_type | The type of conversion actions. The integration currently supports five types in this list: - upload_offline_click_conversion - upload_enhanced_for_lead - upload_enhanced_for_web - upload_call_conversion - upload_store_sales | String | Yes | |
| skipInvalid_records | Determine whether the invalid record should be ignored. | Boolean | True | No |
| custom_variable | The name of the existing custom variable on Googe Ads. It only applies when the conversion type is upload_store_sales. | String | Null | No |
| No | Step | Example |
|---|---|---|
| 1 | Prepare the config | { "type": "google_enhanced_conversion_via_google_ads", "td_authentication_id": "td_authentication_id", "customer_id": 1111111111, "conversion_type": "upload_store_sales", "skipInvalid_records": true, "oauth_warning_flag": null, "custom_variable": "custom_variable"} |
| Stringified JSON | {"type":"google_enhanced_conversion_via_google_ads","td_authentication_id":"td_authentication_id","customer_id":1111111111,"conversion_type":"upload_store_sales","skipInvalid_records":true,"oauth_warning_flag":null,"custom_variable":"custom_variable"} | |
| Prepare the query data | select 'test1@test.com' as email, '+1345876231' as phone_number, '+1345876231' as phone_number_1, '+1345876231' as phone_number_2, '+1345876231' as phone_number_3, '+1345876231' as phone_number_4, 'Test1' as first_name, 'Ng1' as last_name, 'HCM1' as city, 'HCM1' as state, 'VN' as country_code, '700000' as postal_code, '2024-07-04 14:34:30+03:00' as tran_datetime, amount_double as tran_amount, 'USD' as tran_currency, '' as custom_value, '486149275' as conversion_action_idfrom db.google_enhanced; Convert them to single line as below:select 'test1@test.com' as email, '+1345876231' as phone_number, '+1345876231' as phone_number_1, '+1345876231' as phone_number_2, '+1345876231' as phone_number_3, '+1345876231' as phone_number_4, 'Test1' as first_name, 'Ng1' as last_name, 'HCM1' as city, 'HCM1' as state, 'VN' as country_code, '700000' as postal_code, '2024-07-04 14:34:30+03:00' as tran_datetime, amount_double as tran_amount, 'USD' as tran_currency, '' as custom_value, '486149275' as conversion_action_id from luan_db.google_enhanced; | |
| Combine them and run them in terminal | td -c ./account.conf query \--database your_db --wait "select 'test1@test.com' as email, '+1345876231' as phone_number, '+1345876231' as phone_number_1, '+1345876231' as phone_number_2, '+1345876231' as phone_number_3, '+1345876231' as phone_number_4, 'Test1' as first_name, 'Ng1' as last_name, 'HCM1' as city, 'HCM1' as state, 'VN' as country_code, '700000' as postal_code, '2024-07-04 14:34:30+03:00' as tran_datetime, amount_double as tran_amount, 'USD' as tran_currency, '' as custom_value, '486149275' as conversion_action_id from db.google_enhanced;" \--type presto \--result '{"type":"google_enhanced_conversion_via_google_ads","td_authentication_id":"td_authentication_id","customer_id":1111111111,"conversion_type":"upload_store_sales","skipInvalid_records":true,"oauth_warning_flag":null,"custom_variable":"custom_variable"}' |
- The Result Export can be scheduled to upload data to a target destination periodically.
- All import and export integrations can be added to a TD Workflow. The td data operator can be used to export a query result to a specified connector. For more information, see Reference for Treasure Data Operators.