Google Ads integration plan

Last updated 10/03/2026

tip

Note that data generated by third-party data integration counts toward the cluster's data consumption

Summary

Interface overview

Interface	Type	Granularity	Attribution	Cost	Revenue	Impressions	Clicks	Conversions
Reporting API	API	Aggregated metrics		✅		✅	✅	✅

1. Preparation before integration

1.1 Apply for a Developer token

Log in to the Google Ads dashboard with a Google Ads Manager Account, select TOOLS & SETTINGS - SETUP - API Center in the upper-right menu, and fill in the Google Ads API Token Application to apply for a Developer token.

You must provide a Developer Token with Basic Level access, that is, a Developer Token whose application has been approved. A Developer Token with Test Account access can't be used.

To help you complete the application faster, we've compiled answers to some of the questions in the application form, which you can view in this document. You can also see the official documentation for more information about Developer tokens:

After you fill in the application form, wait for the Token Review Team to approve your Developer Token. Most reviews are completed within 1 business day and usually take no more than 3 days.

1.2 Generate the Client ID and Client Secret

While you're getting the Developer Token, you also need to create API access credentials, that is, the Client ID and Client Secret. Before you create API credentials, you need a project in Google Cloud Platform with the Google Ads API enabled. Follow the instructions in this section to create the Client ID and Client Secret.

1.2.1 Create a project in Google Cloud Platform

If you haven't created a project in Google Cloud Platform yet, log in to Google Cloud Platform and click CREATE PROJECT to create one. If you have already created a project, skip this step.

Figure 1. Creating a new project

1.2.2 Enable Google Ads API access

After creating the project, enable Google Ads API access. Search for Google Ads API in the top search bar of the Google Cloud Platform console to open its introduction page. If the area shown in the image below displays ENABLE, the project hasn't enabled Google Ads API access yet. Click ENABLE to enable it.

Figure 2. Google Ads API introduction page

1.2.3 Create API credentials and get the Client ID and Client Secret

After enabling Google Ads API access, create API credentials with Google Ads API access, that is, the Client ID and Client Secret required to pull data.

• When you enable Google Ads API access, you should be redirected to the following page. Click CREATE CREDENTIALS in the red box in the image below to start creating credentials.

• If you can't find this page, you can also go to APIs & Services - Enabled APIs & services from the menu in the upper-left corner of the page. Find Google Ads API in the list and click it to open the page shown below. Select the CREDENTIALS tab, click + CREATE CREDENTIALS, and select Help me choose. This also starts the credential creation process.

After you start creating credentials, complete the configuration as follows

1. On the Credential Type page, select Google Ads API and then User Data, and click NEXT

1. On the Scopes page, click ADD OR REMOVE SCOPES, then find and select Google Ads API in the list to add it to the scope list. Click SAVE AND CONTINUE

1. On the OAuth Client ID page, select Web application for Application type

1. Still on the OAuth Client ID page, configure the callback URL in Authorized redirect URIs. Because you haven't created a plan in the AE system yet, enter "https://www.example.com" as the authorization URL for now, and change it to the actual callback URL after you create the plan.

1. After completing all settings, click CREATE to create the credentials. After they are created, the page shows the Client ID and Client Secret. Keep both of them safe
2. Finally, go to OAuth consent screen and click PUBLISH APP under Publishing status to publish the app to production

1.3 Get the Customer ID and Login Customer ID

Finally, prepare the Customer ID of the ad account from which you want to pull data, and the Customer ID of that user's manager account (the Login Customer ID in subsequent calls). You can find these IDs as follows.

1. In the Google Ads dashboard, log in to the ad account from which you want to pull data
2. Click the help icon in the upper-right corner
3. Find the Customer ID at the bottom of the menu
4. Switch to the manager account and get its Customer ID in the same way. This is the Login Customer ID (you can also get the Customer ID directly from the admin of the manager account)

1.4 Summary

You have now completed the preparation on the Google platform. Make sure you have the following information:

• Develop Token
• Client ID
• Client Secret
• Login Customer ID, that is, the Customer ID of the manager account
• The Customer IDs of all ad accounts from which you want to pull data

2. Plan configuration

After completing the preparation on the Google platform, you can log in to the AE system and configure the new plan in the Third-party Integration module. The image below shows the Google Ads configuration page. Follow this section to create the plan

2.1 Authorization information configuration

Click the Configure authorization information button under Authorization Information and enter the information you obtained in the previous step in the pop-up:

2.2 Sync Schedule

In the Sync Schedule module, you can set the policy for the AE system to pull Google Ads Reporting API data on a schedule. You can choose to pull data for a period of time at a specific time every day. Because pulled data also counts toward the data volume, avoid pulling data for overly long periods on a schedule

2.3 Receive Settings

You can control whether the data is written as events. If you turn this off, the data is not written to the event table, so do not turn off this setting.

2.4 Configuration

Finally, in the Configuration module, you can control the detailed settings of data pulling, including the time aggregation granularity of the data, the metric fields and dimensions to pull, and the event name after ingestion.

The content of the configuration is a JSON, which you can customize as follows:

Module	Name	Description
sink_event	event_mapping	Event name after ingestion; customizable; JSON type. The key corresponds to source.report_types, and the value is the event name for that resource's data. Mutually exclusive with sink_event.event_name
	event_name	Event name after ingestion; customizable; string type. All received data uses this name as the event name. Mutually exclusive with sink_event.event_mapping
source	report_types	The resource to pull, that is, the name of the report to pull. List type. We recommend that you enter only one element, that is, pull data from only one report at a time Valid values: ad_group_ad_asset_view, ad_group_ad, conversion_action, campaign, geographic_view, and other resources. See the following sections for details
	metrics	Metrics in the data; list type. Different levels support different metrics, so fill this in carefully
	group_by	Grouping dimensions in the data; list type. Different levels support different group_by values, so fill this in carefully
extra_params	date_key	Time field in the data
	where	Additional filter conditions, written in GAQL syntax

Because data configurations differ considerably between levels, we recommend that you use the configuration template for each level directly, or fine-tune the templates

2.4.1 Ad Group Ad Asset View template

Ad Group Ad Asset View is a report that combines the ad group level and the asset level. The following is the template for this API, which you can copy in full into the integration configuration. To make changes, see the official documentation, add the metrics that start with metrics to source.metrics, and add other dimension fields to source.group_by:

{
    "extra_params":
    {
        "date_key": "segments.date"
    },
    "sink_event":
    {
        "event_mapping":
        {
            "ad_group_ad_asset_view": "google_ads_ad_group_ad_asset_view",
            "ad_group_ad": "google_ads_ad_group_ad",
            "conversion_action": "google_ads_conversion_action",
            "campaign": "google_ads_campaign",
            "geographic_view": "google_ads_geographic_view"
        }
    },
    "source":
    {
        "report_types":
        [
            "ad_group_ad_asset_view"
        ],
        "metrics":
        [
            "metrics.all_conversions",
            "metrics.all_conversions_value",
            "metrics.all_conversions_value_per_cost",
            "metrics.average_cpc",
            "metrics.clicks",
            "metrics.conversions",
            "metrics.conversions_value",
            "metrics.conversions_value_per_cost",
            "metrics.cost_micros",
            "metrics.cost_per_all_conversions",
            "metrics.cost_per_conversion",
            "metrics.ctr",
            "metrics.impressions",
            "metrics.value_per_all_conversions",
            "metrics.value_per_conversion",
            "metrics.view_through_conversions",
            "metrics.biddable_app_install_conversions"
        ],
        "group_by":
        [
            "customer.id",
            "customer.currency_code",
            "segments.date",
            "segments.ad_network_type",
            "campaign.id",
            "campaign.name",
            "ad_group.id",
            "ad_group.name",
            "ad_group_ad.ad.id",
            "ad_group_ad.ad.name",
            "asset.id",
            "asset.name",
            "campaign.advertising_channel_type",
            "campaign.advertising_channel_sub_type",
            "ad_group_ad.action_items",
            "asset.youtube_video_asset.youtube_video_title",
            "asset.youtube_video_asset.youtube_video_id"
        ]
    }
}

• The template uses the segments.date field in the data, that is, the date of the data, as the data time
• The event name used in the template is: google_ads_ad_group_ad_asset_view

2.4.2 Ad Group Ad template

Ad Group Ad shows Ad-level data and can use dimensions at the ad group and campaign levels. The following is the template for this API, which you can copy in full into the integration configuration. To make changes, see the official documentation, add the metrics that start with metrics to source.metrics, and add other dimension fields to source.group_by:

代码块

{
    "extra_params":
    {
        "date_key": "segments.date"
    },
    "sink_event":
    {
        "event_mapping":
        {
            "ad_group_ad_asset_view": "google_ads_ad_group_ad_asset_view",
            "ad_group_ad": "google_ads_ad_group_ad",
            "conversion_action": "google_ads_conversion_action",
            "campaign": "google_ads_campaign",
            "geographic_view": "google_ads_geographic_view"
        }
    },
    "source":
    {
        "report_types":
        [
            "ad_group_ad"
        ],
        "metrics":
        [
            "metrics.impressions",
            "metrics.clicks",
            "metrics.conversions",
            "metrics.ctr",
            "metrics.average_cpm",
            "metrics.average_cpe",
            "metrics.average_cpc",
            "metrics.trueview_average_cpv",
            "metrics.average_cost",
            "metrics.all_conversions",
            "metrics.conversions_value",
            "metrics.cost_micros",
            "metrics.cost_per_all_conversions",
            "metrics.cost_per_conversion",
            "metrics.value_per_all_conversions",
            "metrics.value_per_conversion",
            "metrics.view_through_conversions",
            "metrics.active_view_cpm",
            "metrics.active_view_ctr",
            "metrics.video_trueview_views",
            "metrics.video_trueview_view_rate",
            "metrics.video_quartile_p25_rate",
            "metrics.video_quartile_p50_rate",
            "metrics.video_quartile_p75_rate",
            "metrics.video_quartile_p100_rate"
        ],
        "group_by":
        [
            "customer.id",
            "customer.currency_code",
            "segments.date",
            "segments.ad_network_type",
            "campaign.id",
            "campaign.name",
            "ad_group.id",
            "ad_group.name",
            "ad_group_ad.ad.id",
            "ad_group_ad.ad.name",
            "campaign.bidding_strategy",
            "campaign.bidding_strategy_type",
            "campaign.advertising_channel_type",
            "campaign.advertising_channel_sub_type",
            "campaign.app_campaign_setting.bidding_strategy_goal_type",
            "ad_group_ad.action_items"
        ]
    }
}

• The template uses the segments.date field in the data, that is, the date of the data, as the data time
• The event name used in the template is: google_ads_ad_group_ad

2.4.3 Conversion Action template

Conversion Action is a report focused on analyzing conversion action data. The following is the template for this API, which you can copy in full into the integration configuration. To make changes, see the official documentation, add the metrics that start with metrics to source.metrics, and add other dimension fields to source.group_by:

{
    "extra_params":
    {
        "date_key": "segments.date"
    },
    "sink_event":
    {
        "event_mapping":
        {
            "ad_group_ad_asset_view": "google_ads_ad_group_ad_asset_view",
            "ad_group_ad": "google_ads_ad_group_ad",
            "conversion_action": "google_ads_conversion_action",
            "campaign": "google_ads_campaign",
            "geographic_view": "google_ads_geographic_view"
        }
    },
    "source":
    {
        "report_types":
        [
            "conversion_action"
        ],
        "metrics":
        [
            "metrics.all_conversions",
            "metrics.all_conversions_value"
        ],
        "group_by":
        [
            "customer.id",
            "segments.date",
            "customer.manager",
            "customer.time_zone",
            "customer.tracking_url_template",
            "customer.auto_tagging_enabled",
            "customer.conversion_tracking_setting.conversion_tracking_id",
            "customer.conversion_tracking_setting.cross_account_conversion_tracking_id",
            "customer.currency_code",
            "customer.descriptive_name",
            "conversion_action.app_id",
            "conversion_action.attribution_model_settings.attribution_model",
            "conversion_action.attribution_model_settings.data_driven_model_status",
            "conversion_action.category",
            "conversion_action.click_through_lookback_window_days",
            "conversion_action.counting_type",
            "conversion_action.id",
            "conversion_action.include_in_conversions_metric",
            "conversion_action.mobile_app_vendor",
            "conversion_action.name",
            "conversion_action.owner_customer",
            "conversion_action.phone_call_duration_seconds",
            "conversion_action.resource_name",
            "conversion_action.status"
        ]
    }
}

• The template uses the segments.date field in the data, that is, the date of the data, as the data time
• The event name used in the template is: google_ads_conversion_action

2.4.4 Campaign template

The Campaign report shows campaign-level data. The following is the template for this API, which you can copy in full into the integration configuration. To make changes, see the official documentation, add the metrics that start with metrics to source.metrics, and add other dimension fields to source.group_by:

代码块

{
    "extra_params":
    {
        "date_key": "segments.date"
    },
    "sink_event":
    {
        "event_mapping":
        {
            "ad_group_ad_asset_view": "google_ads_ad_group_ad_asset_view",
            "ad_group_ad": "google_ads_ad_group_ad",
            "conversion_action": "google_ads_conversion_action",
            "campaign": "google_ads_campaign",
            "geographic_view": "google_ads_geographic_view"
        }
    },
    "source":
    {
        "report_types":
        [
            "campaign"
        ],
        "metrics":
        [
            "metrics.impressions",
            "metrics.clicks",
            "metrics.conversions",
            "metrics.ctr",
            "metrics.average_cpm",
            "metrics.average_cpe",
            "metrics.average_cpc",
            "metrics.trueview_average_cpv",
            "metrics.average_cost",
            "metrics.all_conversions",
            "metrics.conversions_value",
            "metrics.cost_micros",
            "metrics.cost_per_all_conversions",
            "metrics.cost_per_conversion",
            "metrics.value_per_all_conversions",
            "metrics.value_per_conversion",
            "metrics.view_through_conversions",
            "metrics.active_view_cpm",
            "metrics.active_view_ctr",
            "metrics.current_model_attributed_conversions",
            "metrics.current_model_attributed_conversions_value",
            "metrics.engagement_rate",
            "metrics.engagements",
            "metrics.cost_per_current_model_attributed_conversion",
            "metrics.cross_device_conversions",
            "metrics.conversions_value_by_conversion_date",
            "metrics.absolute_top_impression_percentage",
            "metrics.active_view_impressions",
            "metrics.active_view_measurability",
            "metrics.active_view_measurable_impressions",
            "metrics.active_view_measurable_cost_micros",
            "metrics.active_view_viewability",
            "metrics.all_conversions_by_conversion_date",
            "metrics.all_conversions_from_interactions_rate",
            "metrics.all_conversions_value",
            "metrics.all_conversions_value_by_conversion_date",
            "metrics.average_page_views",
            "metrics.average_time_on_site",
            "metrics.bounce_rate",
            "metrics.conversions_by_conversion_date",
            "metrics.conversions_from_interactions_rate",
            "metrics.interactions",
            "metrics.interaction_event_types",
            "metrics.interaction_rate",
            "metrics.percent_new_visitors",
            "metrics.top_impression_percentage",
            "metrics.value_per_all_conversions_by_conversion_date",
            "metrics.value_per_conversions_by_conversion_date",
            "metrics.value_per_current_model_attributed_conversion"
        ],
        "group_by":
        [
            "customer.id",
            "customer.currency_code",
            "segments.date",
            "segments.ad_network_type",
            "campaign.id",
            "campaign.name",
            "campaign.bidding_strategy",
            "campaign.bidding_strategy_type",
            "campaign.advertising_channel_type",
            "campaign.advertising_channel_sub_type",
            "campaign.app_campaign_setting.bidding_strategy_goal_type"
        ]
    }
}

• The template uses the segments.date field in the data, that is, the date of the data, as the data time
• The event name used in the template is: google_ads_campaign

2.4.5 Geographic View template

The Geographic View report shows data at the geographic location level. The following is the template for this API, which you can copy in full into the integration configuration. To make changes, see the official documentation, add the metrics that start with metrics to source.metrics, and add other dimension fields to source.group_by:

代码块

{
    "extra_params":
    {
        "date_key": "segments.date"
    },
    "sink_event":
    {
        "event_mapping":
        {
            "ad_group_ad_asset_view": "google_ads_ad_group_ad_asset_view",
            "ad_group_ad": "google_ads_ad_group_ad",
            "conversion_action": "google_ads_conversion_action",
            "campaign": "google_ads_campaign",
            "geographic_view": "google_ads_geographic_view"
        }
    },
    "source":
    {
        "report_types":
        [
            "geographic_view"
        ],
        "metrics":
        [
            "metrics.all_conversions",
            "metrics.average_cpc",
            "metrics.average_cpm",
            "metrics.clicks",
            "metrics.conversions",
            "metrics.conversions_value",
            "metrics.cost_micros",
            "metrics.cost_per_all_conversions",
            "metrics.cost_per_conversion",
            "metrics.ctr",
            "metrics.impressions",
            "metrics.interaction_event_types",
            "metrics.interaction_rate",
            "metrics.interactions",
            "metrics.value_per_conversion",
            "metrics.video_trueview_views"
        ],
        "group_by":
        [
            "customer.id",
            "customer.currency_code",
            "campaign.id",
            "campaign.name",
            "ad_group.id",
            "ad_group.name",
            "geographic_view.country_criterion_id",
            "geographic_view.location_type",
            "geographic_view.resource_name",
            "segments.ad_network_type",
            "segments.date",
            "segments.device"
        ]
    }
}

• The template uses the segments.date field in the data, that is, the date of the data, as the data time
• The event name used in the template is: google_ads_geographic_view

2.4.6 Write a custom template

The above are templates for several commonly used resources. If you want to connect data from other resources, follow this section.

First, go to the Google Ads API official documentation. We recommend that you look for the resource under Resource with metrics. A resource is a report, and different resources have different analysis dimensions and metrics. You can see a brief introduction to the resource on the right. If you decide to connect this resource, note the resource name on the right, such as ad_group in the image below, and add it to source.report_types

Next, continue down the page, and you'll see three columns of fields: Resource fields, Segments, and Metrics. These three columns are the metrics and dimensions supported by the selected resource. Click a field name to see its full name, such as ad_group.id. Note the full names of the fields you're interested in, record the fields that start with metrics. in source.metrics, and record the other fields in source.group_by

In addition, you can use the Resource fields of the resources listed in Attributed resources.

The image below shows the Attributed resources of ad_group, which include the campaign resource. Click the campaign hyperlink, and all the Resource fields of campaign shown on the page that opens are dimensions you can use in ad group. For example, campaign.id can be used in the ad_group resource. Record these fields in source.group_by

Finally, you need to decide the event name and the data time for ingestion.

First, the event name. We recommend that you delete the existing sink_event.event_mapping, add sink_event.event_name, and enter the event name in it. If you don't enter an event name, the data can't be ingested.

Next, the data time. In general, we recommend that you use segments.date as the data time. In that case, you must add segments.date to source.group_by and also add segments.date to extra_params.date_key. If you need to use another field as the data time, add the original name of that field in both places as well.

You have now finished writing a custom template. You can refer to the following configuration to create your own custom template:

{
    "extra_params":
    {
        "date_key": "segments.date"
    },
    "sink_event":
    {
        "event_name": "google_ads_ad_group"
    },
    "source":
    {
        "report_types":
        [
            "ad_group"
        ],
        "metrics":
        [
            "metrics.impressions",
            "metrics.clicks"
        ],
        "group_by":
        [
            "customer.id",
            "segments.date",
            "campaign.id",
            "campaign.name",
            "ad_group.id",
            "ad_group.name"
        ]
    }
}

2.4.7 How to use extra_params.where

The integration parameter extra_params.where is an advanced parameter that corresponds to the filtering feature of the Reporting API. Because this feature corresponds to GAQL statements (the query statements of the Reporting API, similar to SQL), we recommend that you write it as follows:

First, go to the page of the resource you want to connect, and click Help me build a query at the top to open the GAQL query builder page

Next, click the WHERE tab shown in the image below to see which filter fields are available for the resource:

Select the fields you need and complete the filter conditions as prompted on the page

After you finish writing all the filter conditions, check the editing area at the top, copy the content after Where, and enter it in extra_params.where

{
    "extra_params":
    {
        "date_key": "segments.date",
        "where": "ad_group.name = 'abc' AND ad_group.type = 'TRAVEL_ADS'"
    }
    //...... other params
}

2.4.8 Google Ads query timeout configuration

The total Google Ads query timeout can be configured in the integration plan or in the database, in milliseconds. Only positive integers are valid. If it isn't configured or the configuration is invalid, the value at the next priority level is used.

Integration plan configuration

{
  "extra_params": {
    "ta_options": {
      "search_total_timeout_ms": 300000
    }
  }
}

In the example, 300000 means 5 minutes.

Database configuration

INSERT INTO ta.ta_software_config (namespace, config_key, config_val)
VALUES ('ta-thirdparty', 'google_ads_search_total_timeout_ms', '300000');

Configuration priority

1. extra_params.ta_options.search_total_timeout_ms in the integration plan
2. google_ads_search_total_timeout_ms in the database
3. Google Ads SDK default value (currently 4 hours)

2.5 Data ingestion rules

By default, we write the pulled data to the AE project as events:

• Because the Google Ads Reporting API returns aggregated data, we use a fixed value as the user identifier. You can think of all the data as attached to one virtual user

• The field corresponding to date_key in extra_params, usually the segments.date field, is used as the event's #event_time

• Based on the settings in sink_event.event_mapping, the event names of the data are:

  • ad_group_ad_asset_view：google_ads_ad_group_ad_asset_view
  • ad_group_ad：google_ads_ad_group_ad
  • conversion_action：google_ads_conversion_action
  • campaign：google_ads_campaign
  • geographic_view：google_ads_geographic_view

• All other fields are ingested

2.6 Standardized fields

If the following event properties exist in the data, we standardize them automatically:

Original field	Standardized field	Description
customer_id	te_ads_object.ad_account_id	Ad account ID
campaign_name	te_ads_object.campaign_name	Campaign name
campaign_id	te_ads_object.campaign_id	Campaign ID
ad_group_name	te_ads_object.ad_group_name	Ad group name
ad_group_id	te_ads_object.ad_group_id	Ad group ID
ad_group_ad_ad_name	te_ads_object.ad_name	Ad name
ad_group_ad_ad_id	te_ads_object.ad_id	Ad ID
segment_slot	te_ads_object.placement	Ad placement
geographic_view_country_criterion_id	te_ads_object.country	Country or region code
customer_currency_code	te_ads_object.currency	Currency of the cost or revenue
metrics_impressions	te_ads_object.impressions	Impressions
metrics_clicks	te_ads_object.clicks	Clicks
metrics_conversions	te_ads_object.conversions	Conversions
metrics_biddable_app_install_conversions	te_ads_object.installs	Conversions (installs)
metrics_cost_micros (divided by 1000000)	te_ads_object.cost	User acquisition cost

2.7 Complete authorization

After completing the configuration, click Save and authorize in the upper right corner to save the plan configuration. Next, you need to complete the final authorization:

First, in the Authorization Information page that pops up, copy the URL in the first step

Then, go back to Google Cloud Platform and edit the credentials you created earlier (you can find the OAuth 2.0 Client ID you created under APIs & Services > Credentials in the sidebar, and click the edit button next to it to open the edit page). Add the callback URL you just copied under Authorized redirect URIs and click Save to save the change.

Finally, go back to the AE interface and click Go to authorization. The Google Ads authorization page opens

Log in to the Google account associated with your manager account, and follow Google's instructions to complete the authorization

After completing authorization, in Authorization Information, click I have completed the above two steps in the lower-left corner, and then click Complete Authorization in the lower-right corner to finish the configuration. You have now completed the Google Ads data integration.

3. Version update history

2026-01-29 version update

Changes: The Google Ads API version is updated from V19 to V22, and some properties are renamed

Official link: https://developers.google.com/google-ads/api/docs/upgrade

Original field in V19	Current field in V22	Field description
average_cpv	trueview_average_cpv	The average amount you pay each time someone views your ad. Average cost-per-view (CPV) is defined as the total cost of all ad views divided by the number of TrueView views.
video_view_rate	video_trueview_view_rate	The number of views your TrueView video ad receives divided by its number of impressions, including thumbnail impressions for TrueView in-display ads.
video_views	video_trueview_views	The number of TrueView views your video ads receive.

How the TE Google Ads third-party integration plan handles the API change:

Existing plans	If changed fields are involved	After the 2026-01-29 version update, data is double-written to both the old and new fields so you can choose which to use
	If no changed fields are involved	No impact
New plans	If changed fields are involved	All use the updated V22 API template
	If no changed fields are involved