Google AdMob 集成方案
请注意，第三方数据集成产生的数据会被纳入集群的消耗数据量
概要
接口简介
| 接口名 | 类型 | 粒度 | 归因 | 成本 | 收益 | 展示 | 点击 | 转化 |
|---|---|---|---|---|---|---|---|---|
| Reporting API | API | 聚合指标 | ✅ | ✅ | ✅ |
Google AdMob Reporting API 接口回传聚合的变现广告数据，包含变现广告展示、点击和收入数据
集成流程
- 登录您的 AdMob 账号，获取 Publisher ID
- 登录 Google Cloud Platform 后台，创建带有 AdMob API 权限的项目，并生成 Client ID 与 Client Secret
- 登录 AE 后台，进入三方集成模块，新增 Google AdMob 方案，并完成相关配置
- 回到之前创建的 GCP 后台项目，配置正确的回调地址，并完成授权工作
- 查看 AE 系统是否成功接收数据，并完成报表搭建
一、集成前准备工作
1.1 获取 Publisher ID
登陆 AdMob 后台，以下图所示路径获取 Publisher ID
1.2 在 Google Cloud Platform 内创建一个项目
接下来，您需要创建一个 Google Cloud Platform 项目。如果您没有创建过 GCP 项目，可以登录 Google Cloud Platform，点击「CREATE PROJECT」创建一个项目。如果您已经创建过一个项目，可以跳过此步骤。
1.3 开启 AdMob API
接下来，您需要开启 AdMob API 权限。进入 GCP 项目中，在顶部搜索栏中搜索「AdMob API」，进入到介绍页面。如果页面中下图所示区域显示「ENABLE」，则说明项目未开启 AdMob API 权限，请点击「ENABLE」开启权限。
1.4 配置 Oauth consent screen
开启 AdMob API 权限后，您应该会跳转到以下页面。如果您没有跳转到此页面，也可以在页面左上角的菜单栏中，找到「APIs & Services」- 「Enabled APIs & services」，在 API 列表中找到 AdMob API，点击进入配置页。
- 在列表中寻找 AdMob API，点击也可以进入到下图页面。按下图箭头指示配置 Oauth consent screen。
- 接下来「User Type」处选择 External，选择「CREATE」进入下一步：
- 完成带 * 号的配置（邮箱使用您的 Google 帐号邮箱即可）后点击「SAVE AND CONTINUE」
- 在「Scopes」标签页，选择「ADD OR REMOVE SCOPES」，选中 AdMob API 的 scopes 中的 admob.readonly，点击「UPDATE」确认，点击「SAVE AND CONTINUE」继续
- 接下来在「Test users」标签页，请点击「ADD USERS」将您登录 AdMob 后台的 Google 帐号的邮箱加入到测试用户中，完成添加后，点击「SAVE AND CONTINUE」继续
- 最后的「Summary」标签页会展示您之前配置的内容，直接确定即可完成 Oauth consent screen 的配置
1.5 创建 Client ID 和 Client Secret
完成了 Oauth consent screen 的配置后，重新回到 AdMob API，进行 Client ID 和 Client Secret 的创建
如果您找不到本页面，请点击左上角的菜单栏中，找到「APIs & Services」- 「Enabled APIs & services」，在 API 列表中找到 AdMob API，点击进入配置页。
- 在「CREDENTIALS」标签页，点击「+ CREATE CREDENTIALS」，选择「Help me choose」，进入到创建 Client ID 和 Client Secret 的流程中。
- 在 Credential Type 页，依次选择 AdMob API、 User Data，点击「NEXT」
- 由于我们在创建 Oauth consent screen 时已经完成了 Scopes 的配置，此处可以直接「SAVE AND CONTINUE」继续
- 接下来，在 Application type 选择 Web application。在 Authorized redirect URIs 的红框标注处需要配置回调地址，由于目前我们还没有在 AE 系统中创建方案，因此授权地址请先填写「www.thinkingdata.cn」，等完成方案创建后再修改成正式的回调地址。
- 完成所有配置后，点击「CREATE」创建凭证。创建完毕后，页面中将展示 Client ID 与 Client Secret，请您妥善保管好这两个信息
- 最后，进入「OAuth consent screen」，在 Publishing status 栏目点击「PUBLISH APP」，将应用发布成正式版
1.6 总结
本章节主要介绍进行集成前需要在 Google 平台完成的各项工作，请确认您现在获得了以下信息：
- AdMob 的 Publisher ID
- 已经开启了 AdMob API 的 GCP 项目，并获得了该项目的 Client ID 和 Client Secret
二、方案配置
当您在 Google 平台的准备工作后，您可以登录 AE 系统，在「三方集成」模块中完成新方案的配置。下图是 Google AdMob 的配置界面，请您按照本章节内容完成方案的创建
2.1 授权信息配置
点击「授权信息」下的「配置授权信息」按钮，在弹出框内填写您在上一步中获得的信息：
2.2 定时拉取
您可以在「定时拉取」模块设置 AE 系统定时拉取 Google AdMob 数据的策略，可以选择在每天的某时拉取一段时间的数据。由于拉取的数据也会计入数据量，建议不要定时拉取太长时间的数据
2.3 入库设置
您可以控制数据是否以事件的形式写入，如果关闭，则数据将不会写入事件表，因此请不要关闭该配置。
2.4 集成配置
最后，您可以在集成配置模块对数据拉取的细节配置进行控制。包括数据的时间聚合粒度，拉取的指标字段与维度，以及入库后的事件名等。
集成配置中的内容是一个 JSON，您可以按照以下内容进行自定义配置：
| 模块 | 名称 | 含义 |
|---|---|---|
| sink_event | event_mapping | 入库后的事件名，可以自定义，JSON 类型。Key 对应 source.report_types，Value 为该报表类型的入库事件名。 |
| source | report_types | 拉取的报表类型，AdMob Reporting API 支持两种报表类型。列表类型，建议您只填入一个元素，即一次只拉取一个报表的数据 可选值: network_report、mediation_report，具体可查看接下来的内容 |
| metrics | 数据中的指标，列表类型，不同报表类型支持不同的 metrics，填写时需要注意 | |
| group_by | 数据中的分组维度，列表类型，不同报表类型支持不同的 group_by，填写时需要注意 |
由于不同报表类型的数据配置有较大区别，建议您直接使用各层级的配置模板，或对模板进行微调
2.4.1 Network Report 模板
Network Report 只包含 AdMob 变现广告的数据，以下是该接口的的模板，您可以直接全文复制到集成配置中。如需调整，请参照本小节的内容：
{
"sink_event": {
"event_mapping": {
"network_report": "admob_network_report",
"mediation_report": "admob_mediation_report"
}
},
"source": {
"report_types": [
"network_report"
],
"metrics": [
"AD_REQUESTS",
"CLICKS",
"ESTIMATED_EARNINGS",
"IMPRESSIONS",
"IMPRESSION_CTR",
"IMPRESSION_RPM",
"MATCHED_REQUESTS",
"MATCH_RATE",
"SHOW_RATE"
],
"group_by": [
"DATE",
"AD_UNIT",
"APP",
"COUNTRY",
"FORMAT",
"PLATFORM",
"MOBILE_OS_VERSION",
"GMA_SDK_VERSION",
"APP_VERSION_NAME",
"SERVING_RESTRICTION"
]
}
}
- 涵盖指标
AdMob API 的 Network Report 数据中可以获取以下指标，默认情况下我们会入库所有指标。如需调整，请将指标名加在 source.metrics 中：
| 指标 | 名称 | 备注 |
|---|---|---|
| AD_REQUESTS | 广告请求数 | 与分析维度 AD_TYPE 不兼容 |
| CLICKS | 广告点击次数 | |
| ESTIMATED_EARNINGS | 预估收入 | 预估的总收入，请注意该值被放大了 1000000 倍（比如 $6.50 的值为 6500000），在使用时需除以 1000000 |
| IMPRESSIONS | 广告展示次数 | 总展示次数 |
| IMPRESSION_CTR | 点击通过率 | |
IMPRESSION_RPM | 千次广告展示收入 | 预估的千次广告展示收入，对应后台的 eCPM。请注意该值被放大了 1000000 倍（比如 $1.03 的值为 1030000），在使用时需除以 1000000，与分析维度 AD_TYPE 不兼容 |
| MATCHED_REQUESTS | 广告请求成功数 | 请求广告后获得响应的次数 |
| MATCH_RATE | 请求成功率 | 等于 广告请求成功数 / 广告请求数，与分析维度 AD_TYPE 不兼容 |
| SHOW_RATE | 广告展示率 | 等于 广告展示次数 / 广告请求成功数 |
- 分析维度
以下是 AdMob API 的 Network Report 数据的分析维度。如需调整，请将维度名加在 source.group_by 中：
| 维度 | 含义 | 描述 | 是否默认 |
|---|---|---|---|
| DATE | 按天分组 | 按照 YYYYMMDD 格式 （如 "20210701"）进行时间分组，至少需要一个时间维度 | 是 |
| MONTH | 按月分组 | 按照 YYYYMM格式 （如 "202107"）进行时间分组，至少需要一个时间维度 | |
| WEEK | 按周分组 | 按照一周第一天的 YYYYMMDD 格式 （如 "20210701"）进行时间分组，至少需要一个时间维度 | |
| AD_UNIT | 按 ad unit 分组 | 取 ad unit 的 unique ID （如 "ca-app-pub-1234/1234"），使用该维度将自动添加 APP 维度 | 是 |
| APP | 按应用分组 | 取应用 ID （如 "ca-app-pub-1234~1234"） | 是 |
| AD_TYPE | 按广告类型分组 | 取值如 "text" or "image"，需要注意与指标 AD_REQUESTS、MATCH_RATE 和 IMPRESSION_RPM 不兼容 | |
| COUNTRY | 按国家（地区）分组 | 取 Unicode CLDR 规范的国家（地区）代号，如 "US"，"FR" | 是 |
| FORMAT | 以广告单元的类型进行分组 | 取 ad unit 的类型，如 "banner"，"native" | 是 |
| PLATFORM | 按平台进行分组 | 取值如 "Android"，"iOS" | 是 |
| MOBILE_OS_VERSION | 按操作系统版本进行分组 | 取值如 "iOS 13.5.1" | 是 |
| GMA_SDK_VERSION | 按 GoogleMobileAds SDK 版本进行分组 | 取值如 "iOS 7.62.0". | 是 |
| APP_VERSION_NAME | 按 APP 版本进行分组 | Android 取 PackageInfo 中的 versionName，iOS 取 CFBundleShortVersionString 中的 app version name | 是 |
| SERVING_RESTRICTION | 按广告投放的限制模式进行分组 | 取值如 "Non-personalized ads" | 是 |
- 入库规则
模板中使用数据中的 DATE 字段，即以天为聚合的时间，补零后作为该条数据的 #event_time
模板中使用的事件名为 -- admob_network_report
2.4.2 Mediation Report 模板
Mediation Report 包含 AdMob 变现广告以及其他第三方平台的广告数据，以下是该接口的的模板，您可以直接全文复制到集成配置中。如需调整，请参照本小节的内容：
{
"sink_event": {
"event_mapping": {
"network_report": "admob_network_report",
"mediation_report": "admob_mediation_report"
}
},
"source": {
"report_types": [
"mediation_report"
],
"metrics": [
"AD_REQUESTS",
"CLICKS",
"ESTIMATED_EARNINGS",
"IMPRESSIONS",
"IMPRESSION_CTR",
"MATCHED_REQUESTS",
"MATCH_RATE",
"OBSERVED_ECPM"
],
"group_by": [
"DATE",
"AD_SOURCE",
"AD_SOURCE_INSTANCE",
"AD_UNIT",
"APP",
"MEDIATION_GROUP",
"COUNTRY",
"FORMAT",
"PLATFORM"
]
}
}
- 涵盖指标
AdMob API 的 Mediation Report 数据中可以获取以下指标，默认情况下我们会入库所有指标。如需调整，请将指标名加在 source.metrics 中：
| 指标 | 名称 | 描述与备注 |
|---|---|---|
| AD_REQUESTS | 广告请求数 | |
| CLICKS | 广告点击次数 | |
ESTIMATED_EARNINGS | 预估收入 | AdMob 预估的总收入，请注意该值被放大了 1000000 倍（比如 $6.50 的值为 6500000），在使用时需除以 1000000 |
| IMPRESSIONS | 广告展示次数 | 总展示次数 |
| IMPRESSION_CTR | 点击通过率 | |
| MATCHED_REQUESTS | 广告请求成功数 | 请求广告后获得响应的次数 |
| MATCH_RATE | 请求成功率 | 等于 广告请求成功数 / 广告请求数 |
| OBSERVED_ECPM | 预估 eCPM | 第三方平台预估的 eCPM 值（由于第三方数据权限问题，目前该值可能为 0） |
- 分析维度
以下是 AdMob API 的 Mediation Report 数据的分析维度。如需调整，请将维度名加在 source.group_by 中：
| 维度 | 含义 | 描述 | 是否默认 |
|---|---|---|---|
| DATE | 按天分组 | 按照 YYYYMMDD 格式 （如 "20210701"）进行时间分组，至少需要一个时间维度，我们默认使用 DATE 作为时间分组 | 是 |
| MONTH | 按月分组 | 按照 YYYYMM格式 （如 "202107"）进行时间分组，至少需要一个时间维度 | |
| WEEK | 按周分组 | 按照一周第一天的 YYYYMMDD 格式 （如 "20210701"）进行时间分组，至少需要一个时间维度 | |
| AD_SOURCE | 按媒体渠道分组 | 按媒体渠道 ID 以及渠道名进行分组 | 是 |
| AD_SOURCE_INSTANCE | 按媒体渠道实例分组 | 按媒体渠道实例 ID 以及媒体渠道实例名进行分组 | 是 |
| AD_UNIT | 按 ad unit 分组 | 取 ad unit 的 unique ID （如 "ca-app-pub-1234/1234"），使用该维度将自动添加 APP 维度 | 是 |
| APP | 按应用分组 | 取应用 ID （如 "ca-app-pub-1234~1234"） | 是 |
| MEDIATION_GROUP | 按聚合组进行分组 | 按聚合组 ID 以及聚合组名进行分组 | 是 |
| COUNTRY | 按国家（地区）分组 | 取 Unicode CLDR 规范的国家（地区）代号，如 "US"，"FR" | 是 |
| FORMAT | 以广告单元的类型进行分组 | 取 ad unit 的类型，如 "banner"，"native" | 是 |
| PLATFORM | 按平台进行分组 | 取值如 "Android"，"iOS" | 是 |
| MOBILE_OS_VERSION | 按操作系统版本进行分组 | 取值如 "iOS 13.5.1"，需要注意与指标 ESTIMATED_EARNINGS、OBSERVED_ECPM 不兼容 | |
| GMA_SDK_VERSION | 按 GoogleMobileAds SDK 版本进行分组 | 取值如 "iOS 7.62.0"，需要注意与指标 ESTIMATED_EARNINGS、OBSERVED_ECPM 不兼容 | |
| APP_VERSION_NAME | 按 APP 版本进行分组 | Android 取 PackageInfo 中的 versionName，iOS 取 CFBundleShortVersionString 中的 app version name ，需要注意与指标 ESTIMATED_EARNINGS、OBSERVED_ECPM 不兼容 | |
| SERVING_RESTRICTION | 按广告投放的限制模式进行分组 | 取值如 "Non-personalized ads"，需要注意与指标 ESTIMATED_EARNINGS 不兼容 |
- 入库规则
模板中使用数据中的 DATE 字段，即以天为聚合的时间，补零后作为该条数据的 #event_time
模板中使用的事件名为 -- admob_mediation_report
2.4.3 按 App ID 过滤
如需仅拉取指定应用的数据，可以在集成配置的 extra_params.dimension_filters 中按 App ID 过滤。该配置使用 APP 维度，请将示例中的 App ID 替换为实际值：
{
"extra_params": {
"dimension_filters": [
{
"dimension": "APP",
"matches_any": {
"values": [
"ca-app-pub-XXXXXXXXXXXXXXXX~XXXXXXXXXX"
]
}
}
]
}
}
2.4.4 收益币种配置
如需按指定币种获取 AdMob 收益类指标，可以在集成配置的 extra_params.localization_settings 中设置 currency_code。该配置同时适用于 Network Report 和 Mediation Report：
{
"extra_params": {
"localization_settings": {
"currency_code": "JPY",
"language_code": "en-US"
}
}
}
currency_code使用 ISO 4217 三字母币种代码，例如JPY、USD。未配置时默认使用USD；使用无效代码会导致参数校验失败。language_code用于设置报告语言，未配置时默认使用en-US；如需日语，可设置为ja-JP。请勿将币种代码JPY填入该字段。- 配置生效后，后续拉取数据的收益币种与标准化字段
te_ads_object.currency保持一致；已入库的历史数据不会被改写。
2.5 标准化字段
如果数据中存在以下事件属性，我们会自动进行标准化处理：
| 原始字段 | 标准化字段 | 含义 |
|---|---|---|
| publisher_id | te_ads_object.ad_account_id | 广告账号 ID |
| ad_unit | te_ads_object.ad_group_id | 广告组 ID |
| ad_source | te_ads_object.media_source | 媒体渠道或变现渠道 |
| app | te_ads_object.app_id | 应用 ID |
| platform | te_ads_object.platform | 平台，即 Android、iOS 等 |
| country | te_ads_object.country | 国家地区编码 |
| localization_settings_currency_code | te_ads_object.currency | 收益币种；未配置时为 USD |
| impressions | te_ads_object.impressions | 曝光量 |
| clicks | te_ads_object.clicks | 点击量 |
| estimated_earnings（数据会除以 1000000） | te_ads_object.revenue | 变现收益 |
2.6 完成授权
完成配置后，您可以点击右上角的「保存并授权」将方案配置保存下来。接下来，您需要完成最后的授权工作：
首先，请在弹出的「授权信息」页面中，将第一步中的地址复制下来
其次，回到 Google Cloud Platform，编辑之前创建的 credentials（您可以在侧边栏「APIs & Services」-「Credentials」查看到之前创建的 Oauth 2.0 Client ID，点击后面的编辑按钮即可进入到编辑页面）。Authorized redirect URIs 处将刚刚复制的回调地址添加进去，点击「Save」完成修改。
最后，再回到 AE 界面，点击「前往授权」，此时将打开 Google AdMob 的授权页面
请您登录您在 AdMob 的 Google 账号，并按照 Google 的指示完成接下来的授权操作
当您完成了授权之后，请在「授权信息」中点击左下角的「我已完成以上两步操作」后点击右下角的「完成授权」结束配置。至此，您完成了 Google AdMob 的数据集成。