# Google Ads 集成方案
TIP
请注意,第三方数据集成产生的数据会被纳入集群的消耗数据量
# 概要
# 接口简介
接口名 | 类型 | 粒度 | 归因 | 成本 | 收益 | 展示 | 点击 | 转化 |
---|---|---|---|---|---|---|---|---|
Reporting API | API | 聚合指标 | ✅ | ✅ | ✅ | ✅ |
# 一、集成前准备工作
# 1.1 申请 Developer token
使用 Google Ads Manager Account 登录 Google Ads (opens new window) 后台,在右上角菜单选中「TOOLS & SETTINGS」- 「SETUP」-「API Center」,填写 Google Ads API Token Application 完成 Developer token 的申请。
您必须提供访问权限为 Basic Level 的 Developer Token,即完成申请后的 Developer Token,不能使用权限为 Test Account 的 Developer Token。
为了方便您更为快速地完成申请,我们整理了申请表单中的一些问题解答,你可以访问本文档 (opens new window)进行查看。另外,您还可以参考官方文档 (opens new window)获取更多 Developer token 的信息:
填完申请表格之后,需等待 Token Review Team 批准你的 Developer Token。审核大多数会在 1 个工作日内完成,一般不会超过 3 天。
# 1.2 生成 Client ID 与 Client Secret
在您获取 Developer Token 的同时,您还需要创建 API 的访问凭据,即 Client ID 与 Client Secret。在创建 API 凭据之前,您需要在 Google Cloud Platform 中拥有一个项目,并且该项目开启了 Google Ads API。您可以跟随本节的指引,完成 Client ID 与 Client Secret 的创建。
# 1.2.1 在 Google Cloud Platform 内创建一个项目
如果您在 Google Cloud Platform 中还没有创建过项目,则可以登录 Google Cloud Platform (opens new window),点击「CREATE PROJECT」创建项目。如果您已经创建过一个项目,可以跳过此步骤。
图1、新建项目示意图
# 1.2.2 开启 Google Ads API 权限
完成项目的创建后,接下来就需要开启 Google Ads API 权限。在 Google Cloud Platform 后台的顶部搜索栏中搜索「Google Ads API」,进入到介绍页面。如果页面中下图所示区域显示「ENABLE」,则说明项目尚未开启 Google Ads API 权限。点击「ENABLE」开启权限即可。
图2、Google AdsAPI 介绍页面
# 1.2.3 创建 API 凭据,获取 Client ID 与 Client Secret
开启 Google Ads API 权限后,接下来需要创建一个具备 Google Ads API 权限的 API 凭据,即拉取数据时所需的 Client ID 与 Client Secret。
开启 Google Ads API 权限时,您应该会跳转到以下页面。此时点击下图红框处「CREATE CREDENTIALS」即可进入到创建凭据的流程中。
如果您没有找到上述页面,也可以在页面左上角的菜单栏中,找到「APIs & Services」- 「Enabled APIs & services」并进入。在列表中寻找 Google Ads API,点击进入到下图页面。此时选中「CREDENTIALS」标签页,点击「+ CREATE CREDENTIALS」,选择「Help me choose」,亦可进入到创建凭据的流程中。
进入到创建凭据流程,请按照以下步骤完成配置
在 Credential Type 页,依次选择 Google Ads API、 User Data,点击「NEXT」
在 Scopes 页,点击「ADD OR REMOVE SCOPES」,在列表中寻找 Google Ads API 并勾选,将其加入到 Scope 列表。点击「SAVE AND CONTINUE」
OAuth Client ID 页,Application type 处选择 Web application
仍然在 OAuth Client ID 页,Authorized redirect URIs 处配置回调地址。由于目前我们还没有在 TE 系统中创建方案,因此授权地址请先填写「www.thinkingdata.cn」,等完成方案创建后再修改成正式的回调地址。
完成所有配置后,点击「CREATE」创建凭证。创建完毕后,页面中将展示 Client ID 与 Client Secret,请您妥善保管好这两个信息
最后,进入「OAuth consent screen」,在 Publishing status 栏目点击「PUBLISH APP」,将应用发布成正式版
# 1.3 获取 Customer ID 和 Login Customer ID
最后,请您将要拉取数据的广告账户的 Customer ID,以及该用户的广告经理账号的 Customer ID(即后续调用中的 Login Customer ID)。您可以按照以下流程查看这些 ID。
- 在 Google Ads 后台 (opens new window) 登录将要拉取数据的广告账户
- 单击右上角的帮助图标
- 在菜单底部找到 Customer ID
- 切换到广告经理账号,按照上述流程获得 Customer ID,即为 Login Customer ID(您也可以直接从广告经理账号的管理员获得其 Customer ID)
# 1.4 总结
至此,您完成了在 Google 平台的接入前准备工作,请确认您获得了以下信息:
- Develop Token
- Client ID
- Client Secret
- Login Customer ID,即广告经理的 Customer ID
- 所有需要拉取数据的广告账号的 Customer ID
# 二、方案配置
当您在 Google 平台的准备工作后,您可以登录 TE 系统,在「三方集成」模块中完成新方案的配置。下图是 Google Ads 的配置界面,请您按照本章节内容完成方案的创建
# 2.1 授权信息配置
点击「授权信息」按钮,在弹出框内填写您在上一步中获得的信息:
# 2.2 定时拉取
您可以在「定时拉取」模块设置 TE 系统定时拉取 Google Ads Reporting API 数据的策略,可以选择在每天的某时拉取一段时间的数据。由于拉取的数据也会计算再数据量中,建议您在不要定时拉取太长时间的数据
# 2.3 入库设置
您可以控制数据是否以事件的形式写入,如果关闭,则数据将不会写入事件表,因此请不要关闭该配置。
# 2.4 集成配置
最后,您可以在集成配置模块对数据拉取的细节配置进行控制。包括数据的时间聚合粒度,拉取的指标字段与维度,以及入库后的事件名等。
集成配置中的内容是一个 JSON,您可以按照以下内容进行自定义配置:
模块 | 名称 | 含义 |
---|---|---|
sink_event | event_mapping | 入库后的事件名,可以自定义,JSON 类型。Key 对应 source.report_types,Value 为该 resource 数据的事件名。与 source.event_name 互斥 |
event_name | 入库后的事件名,可以自定义,字符串类型。接收到的数据均将以该名称作为事件名。与 source.event_mapping 互斥 | |
source | report_types | 拉取的 resource,即拉取的报表的名称。列表类型,建议您只填入一个元素,即一次只拉取一个报表的数据 可选值: ad_group_ad_asset_view、ad_group_ad、conversion_action、campaign、geographic_view 以及其他 resources,具体可查看接下来的内容 |
metrics | 数据中的指标,列表类型,不同层级支持不同的 metrics,填写时需要注意 | |
group_by | 数据中的分组维度,列表类型,不同层级支持不同的 group_by,填写时需要注意 | |
extra_params | date_key | 数据中的时间字段 |
where | 额外的筛选条件,需要使用 GAQL 的语法 |
由于不同层级的数据配置有较大区别,建议您直接使用各层级的配置模板,或对模板进行微调
# 2.4.1 Ad Group Ad Asset View 模板
Ad Group Ad Asset View 是一种合并了 ad group 层级与 asset 层级的报表,以下是该接口的的模板,您可以直接全文复制到集成配置中。如需调整,请查看官网文档 (opens new window),将 metrics 开头的指标加在 source.metrics,其他维度字段加在 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"
]
}
}
- 模板中使用数据中的 segments.date 字段,即数据的日期,作为数据的时间
- 模板中使用的事件名为 -- google_ads_ad_group_ad_asset_view
# 2.4.2 Ad Group Ad 模板
Ad Group Ad 可以查看 Ad 层级的数据,并能使用 ad group、campaign 层级的维度,以下是该接口的的模板,您可以直接全文复制到集成配置中。如需调整,请查看官网文档 (opens new window),将 metrics 开头的指标加在 source.metrics,其他维度字段加在 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.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_views",
"metrics.video_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"
]
}
}
- 模板中使用数据中的 segments.date 字段,即数据的日期,作为数据的时间
- 模板中使用的事件名为 -- google_ads_ad_group_ad
# 2.4.3 Conversion Action 模板
Conversion Action 是专注于分析转化行为数据的报表,以下是该接口的的模板,您可以直接全文复制到集成配置中。如需调整,请查看官网文档 (opens new window),将 metrics 开头的指标加在 source.metrics,其他维度字段加在 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"
]
}
}
- 模板中使用数据中的 segments.date 字段,即数据的日期,作为数据的时间
- 模板中使用的事件名为 -- google_ads_conversion_action
# 2.4.4 Campaign 模板
Campaign 报表可以查看 campaign 层级的数据,以下是该接口的的模板,您可以直接全文复制到集成配置中。如需调整,请查看官网文档 (opens new window),将 metrics 开头的指标加在 source.metrics,其他维度字段加在 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.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"
]
}
}
- 模板中使用数据中的 segments.date 字段,即数据的日期,作为数据的时间
- 模板中使用的事件名为 -- google_ads_campaign
# 2.4.5 Geographic View 模板
Geographic View 报表可以地理位置层级的数据,以下是该接口的的模板,您可以直接全文复制到集成配置中。如需调整,请查看官网文档 (opens new window),将 metrics 开头的指标加在 source.metrics,其他维度字段加在 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_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"
]
}
}
- 模板中使用数据中的 segments.date 字段,即数据的日期,作为数据的时间
- 模板中使用的事件名为 -- google_ads_geographic_view
# 2.4.6 自定义模板的编写方式
以上展示的是几个常用的 Resource 的模板,如果您希望获取接入其他 Resource 的数据,您可以按照本章节的内容来进行操作。
首先,请您进入到 Google Ads API 的官网文档 (opens new window),我们建议您在「Resource with metrics」中查找相应的资源。资源即报表,不同资源有不同分析维度与指标,您可以在右侧查看到该资源的简介。如果您确定要接入这种资源,请记录下右侧的资源名,比如下图的 ad_group,将其加入到 source.report_types
中
接下来,继续查看该页面,可以看到三列字段,分别是 Resource fields、Segments 以及 Metrics。这三列就是所选资源支持的指标与维度,您可以点击所需的字段名,查看字段的全名,比如 ad_group.id。请将您感兴趣的字段的全名记录下来,并将以 metrics. 开头的字段记录在source.metrics
中,其他字段记录在source.group_by
中
除此之外,您还可以使用 Attributed resources 中列出的资源的 Resource fields。
下图展示的 ad_group 的 Attributed resources,可以看到 campaign 这个 resource,那么您可以点击「campaign」超链接,在弹出页面中展示的 campaign 的 Resource fields 都是您可以在 ad group 中使用的维度,比如 campaign.id 可以在 ad_group 资源中使用,请将这些字段记录在source.group_by
中
最后,您需要决定入库的事件名以及数据入库时间。
首先是入库名,我们建议您删除原有的 source.event_mapping
,加入source.event_name
,并在其中加入入库的事件名,如果您不填写事件名,则数据无法入库。
接下来是数据入库时间,一般来说,我们建议您使用 segments.date 作为数据时间,那么您必须在source.group_by
中添加 segments.date,并且在 extra_params.date_key
中同样加入 segments.date。如果您需要使用其他字段作为数据时间,那么您也需要在这两个地方加入该字段的原名。
至此,您就完成了一个自定义模板的编写,您可以参考以下配置创建您的自定义模板:
{
"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 extra_params.where 的使用方法
集成参数extra_params.where
是一个高级参数,对应了 Reporting API 的筛选功能。由于该功能对应了 GAQL 语句(即 Reporting API 的查询语句,类似 SQL),因此我们建议您按照以下方式编写:
首先,进入到您需要接入的 Resource 页面,点击顶部的「Help me build a query」进入到 GAQL 编写辅助页面
接下来,点击下图的「WHERE」标签,查看该 resource 可用的筛选字段有哪些:
您可以选择需要的字段,并按照界面提示完成筛选条件的选择
当您完成了所有筛选条件的编写后,查看顶部的编写区域,并将 Where 之后的内容复制下来,填写到 extra_params.where 中
{
"extra_params":
{
"date_key": "segments.date",
"where": "ad_group.name = 'abc' AND ad_group.type = 'TRAVEL_ADS'"
}
//...... other params
}
# 2.5 数据入库规则
默认情况下,我们会将拉取的数据以事件形式写入 TE 项目中:
- 由于 Google Ads Reporting API 返回的是聚合数据,因此我们将使用一个固定值作为其用户标识,您可以认为所有数据挂载在一个虚拟用户上
- 使用 extra_params 中的 date_key 对应的字段,一般为 segment.date 字段,作为事件的 #event_time
- 使用 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
- 其他字段将全数入库
# 2.6 标准化字段
如果数据中存在以下事件属性,我们会自动进行标准化处理:
原始字段 | 标准化字段 | 含义 |
---|---|---|
customer_id | te_ads_object.ad_account_id | 广告账号 ID |
campaign_name | te_ads_object.campaign_name | 广告计划名 |
campaign_id | te_ads_object.campaign_id | 广告计划 ID |
ad_group_name | te_ads_object.ad_group_name | 广告组名 |
ad_group_id | te_ads_object.ad_group_id | 广告组 ID |
ad_group_ad_ad_name | te_ads_object.ad_name | 广告名 |
ad_group_ad_ad_id | te_ads_object.ad_id | 广告 ID |
segment_slot | te_ads_object.placement | 广告位置 |
geographic_view_country_criterion_id | te_ads_object.country | 国家地区编码 |
customer_currency_code | te_ads_object.currency | 成本或收益的币种 |
metrics_impressions | te_ads_object.impressions | 曝光量 |
metrics_clicks | te_ads_object.clicks | 点击量 |
metrics_biddable_app_install_conversions | te_ads_object.installs | 转化量(安装) |
metrics_cost_micros(除以 1000000) | te_ads_object.cost | 买量成本 |
# 2.7 完成授权
完成配置后,您可以点击右上角的「保存并授权」将方案配置保存下来。接下来,您需要完成最后的授权工作:
首先,请在弹出的「授权信息」页面中,将第一步中的地址复制下来
其次,回到 Google Cloud Platform (opens new window),编辑之前创建的 credentials(您可以在侧边栏「APIs & Services」-「Credentials」查看到之前创建的 Oauth 2.0 Client ID,点击后面的编辑按钮即可进入到编辑页面)。Authorized redirect URIs 处将刚刚复制的回调地址添加进去,点击「Save」完成修改。
最后,再回到 TE 界面,点击「前往授权」,此时将打开 Google Ads 的授权页面
请登录您的广告经理账号关联的 Google 账号,并按照 Google 的指示完成接下来的授权操作
当您完成了授权之后,请在「授权信息」中点击左下角的「我已完成以上两步操作」后点击右下角的「完成授权」结束配置。至此,您完成了 Google Ads 的数据集成。