# Google Enhanced Conversion Via Google Ads Export Integration

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](https://support.google.com/google-ads/answer/1722022) 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)


## Prerequisites

- Basic knowledge of Treasure Data, including [TD Toolbelt](https://toolbelt.treasuredata.com/).
- Documentation: [Google Ads API](https://developers.google.com/google-ads/api/docs/get-started/introduction)
- Setup guide:
  - [Upload click conversions](https://developers.google.com/google-ads/api/docs/conversions/upload-clicks#setup).
  - [Upload enhanced conversions for Lead](https://developers.google.com/google-ads/api/docs/conversions/enhanced-conversions/leads-setup).
  - [Upload enhanced conversions for Web](https://developers.google.com/google-ads/api/docs/conversions/enhanced-conversions/web-setup).
  - [Upload call conversions.](https://developers.google.com/google-ads/api/docs/conversions/upload-calls)
  - [About Store Sales Implementation](https://support.google.com/google-ads/answer/9941109?hl=en&visit_id=638536958762470965-1063192925&ref_topic=9941535&rd=1)
- 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.


## Requirements and Limitations

- 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 transactions` error.
- 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.


## Create a New Connection

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.

![](/assets/google-enhanced-conversion-via-google-ads-export-integration-2024-07-15.bcab6b76301c8ff92f5ce6bfbc2b6ccfa2e4642ef56696bc9453107acef3d4b2.e9e2a149.png)

1. Open TD Console.
2. Navigate to **Integrations Hub > Catalog**.
3. Search for and select **Google Enhanced Conversion via Google Ads**.
4. Select **Create Authentication**and provide the OAuth of a Google account with access to the target Google Ads account.
5. Select **Continue,**enter a name for the Authentication, and then select **Done**.


## Configure a Query Result for Export

The TD Console supports multiple ways to export data. Complete the following steps to export data from the Data Workbench.

1. Navigate to **Data Workbench** > **Queries**.
2. Select **New Query** and define your query.
3. Select **Export Results** and configure the data exporting.
4. Select an existing Google Enhanced Conversion authentication or [create a new one](/int/google-enhanced-conversion-via-google-ads-export-integration#googadsconnection).
5. Configure the exporting parameters and select **Done**


![](/assets/google-enhanced-conversion-via-google-ads-export-integration-2024-07-15-1.eec8ef6f87bb4bf0c0fd4ec924042a311d8066ad2e56ae8ce67c5d7fbe4b7168.e9e2a149.png)

### Configuration Parameters

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


1. Select **Done**.


## Define your Query

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](https://developers.google.com/google-ads/api/reference/rpc/v15/Consent).)

### Common Data Requirements

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:
  - email
  - 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.


### Click Conversions

| **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 |


### Enhanced Conversions for Lead

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 |
| email | Support a maximum of 5 user identifiers (email and phone_number) | String ([hashing requirement](/int/google-enhanced-conversion-via-google-ads-export-integration#h3_1829032370)) | 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](/int/google-enhanced-conversion-via-google-ads-export-integration#h3_1829032370)) |  |
| 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 |


### Enhanced Conversion for Web

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 |
| email | Supports a maximum of five user identifiers (email, phone_number, and address) | String ([hashing requirement](/int/google-enhanced-conversion-via-google-ads-export-integration#h3_1829032370)) | 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](/int/google-enhanced-conversion-via-google-ads-export-integration#h3_1829032370)) | Yes |
| first_name | Address information | String ([hashing requirement](/int/google-enhanced-conversion-via-google-ads-export-integration#h3_1829032370)) | Yes |
| last_name | String ([hashing requirement](/int/google-enhanced-conversion-via-google-ads-export-integration#h3_1829032370)) | 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](/int/google-enhanced-conversion-via-google-ads-export-integration#h3_1829032370)) | 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 |


### Call Conversions

| **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 |


## 

### Store Sales Conversions

| **Field Name (Output Schema)** | **Description** | **Data Type** | **Required?** |
|  --- | --- | --- | --- |
| email |  | String ([hashing requirement](/int/google-enhanced-conversion-via-google-ads-export-integration#h3_1829032370)) | 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](/int/google-enhanced-conversion-via-google-ads-export-integration#h3_1829032370)) |  |
| first_name | Address info  When neither email or phone number has a value, all these fields are required. | String ([hashing requirement](/int/google-enhanced-conversion-via-google-ads-export-integration#h3_1829032370)) |  |
| last_name | String ([hashing requirement](/int/google-enhanced-conversion-via-google-ads-export-integration#h3_1829032370)) |  |  |
| 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 |  |


### Example Query

**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    table
```

# 

## Activate a Segment in Audience Studio

## 

You can also send segment data to the target platform by creating an activation in the Audience Studio.

1. Navigate to **Audience Studio**.
2. Select a parent segment.
3. Open the target segment, right-mouse click, and then select **Create Activation.**
4. In the **Details** panel, enter an Activation name and configure the activation according to the previous section on Configuration Parameters.
5. Customize the activation output in the **Output Mapping** panel.


![](/assets/ouput.b2c7f1d909c4f98ed10f5300df858a4b19f71a3b0834df952f5fb24018a5ea78.8ebdf569.png)

- 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 Columns**to 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.


1. Set a **Schedule**.


![](/assets/snippet-output-connector-on-audience-studio-2024-08-28.a99525173709da1eb537f839019fa7876ffae95045154c8f2941b030022f792c.8ebdf569.png)

- Select the values to define your schedule and optionally include email notifications.


1. Select **Create**.


## (Optional) Export Integration Using the CLI

The [TD Toolbelt](https://toolbelt.treasuredata.com/) 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](https://docs.treasuredata.com/articles/pd/querying-and-importing-data-to-treasure-data-from-the-command-line).

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}
```

### CLI Parameters

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


### Example Usage

| 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"}'` |


## Related articles

#### Other configurations

- The Result Export can be [scheduled](https://docs.treasuredata.com/articles/pd/scheduling-jobs-using-td-console) to upload data to a target destination periodically.
- All import and export integrations can be added to a [TD Workflow](https://docs.treasuredata.com/articles/pd/about-treasure-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](https://docs.treasuredata.com/articles/pd/reference-for-treasure-data-operators/a/h1_76525622).


#### External references

- [About conversion tracking](https://support.google.com/google-ads/answer/1722022)
- [Google Ads API](https://developers.google.com/google-ads/api/docs/get-started/introduction)
- [Upload click conversions](https://developers.google.com/google-ads/api/docs/conversions/upload-clicks#setup).
- [Upload enhanced conversions for Lead](https://developers.google.com/google-ads/api/docs/conversions/enhanced-conversions/leads-setup).
- [Upload enhanced conversions for Web](https://developers.google.com/google-ads/api/docs/conversions/enhanced-conversions/web-setup).
- [Upload call conversions.](https://developers.google.com/google-ads/api/docs/conversions/upload-calls)
- [About Store Sales Implementation](https://support.google.com/google-ads/answer/9941109?hl=en&visit_id=638536958762470965-1063192925&ref_topic=9941535&rd=1)