广告活动报告 Alpha 版 API

“广告活动”报告是一种 集中查看广告效果它会将数据、指标 来自广告联盟报告 API 和中介报告 API 以及中介报告 API 的维度， 出价数据整合到一个统一报告中。

Ads Activity Report API 通过中介功能提供了更多改进 Report API 和 Network Report API，如下表所示：

网络报告 API 中介报告 API 广告活动报告 API
网络性能 ✅ ✅ ✅
广告瀑布流效果 ✅ ✅
出价效果 ✅
中介 A/B 实验效果 ✅
每小时报告 ✅
报告大小 10 万 10 万 50 万

指标、维度和维度过滤条件

Ads Activity Report API 新增了以下指标： 以及 Network Report API 和 Mediation Report API。

指标 说明
BID_REQUEST 向出价广告来源发出的请求数。
BIDS_IN_AUCTION 广告来源提交的参与了出价竞价的出价数。
WINNING_BIDS 在出价竞价中胜出的出价数。

Ads Activity Report API 中包含以下新维度。

维度 说明
周 一周第一天的日期（以当地语言 本地化设置中提到的代码），并采用 YYYYMMDD 格式（ 例如“20210701”）。请求只能指定 DATE、WEEK 或 MONTH 之一 时间维度。
小时 以 PST 时间为单位的 HH 格式小时。例如，"05"太平洋标准时间早上 5 点，“13” 太平洋标准时间下午 1 点。还必须在请求中指定 DATE 维度。答 当指定了“时段”维度时，系统将返回最多 28 天的数据。 日期范围的开始日期超过当前日期 28 天前 返回错误。
MEDIATION_AB_TEST（实验名称） 按中介 A/B 测试查看效果。您必须指定 如果指定了 VARIANT 维度。
MEDIATION_AB_TEST_VARIANT（变体 A、变体 B） 按中介 A/B 测试变体查看效果。
Mediation Report API 中的维度名称 Ads Activity Report API 中的维度名称 说明
AD_UNIT1 AD_UNIT_ID 广告单元的唯一 ID（例如“123456789”）。
AD_UNIT_NAME 广告单元的名称。
应用1 APP_ID 移动应用的唯一 ID（例如“1234567890”）。
APP_NAME 应用的名称。
AD_SOURCE1 AD_SOURCE_ID 广告来源的唯一 ID（例如“1234567890123456789”）。
AD_SOURCE_NAME 广告来源的名称（例如“AdMob 广告联盟”）。
AD_SOURCE_INSTANCE1 AD_SOURCE_INSTANCE_ID 广告来源实例的唯一 ID（例如“123456789012”）。
AD_SOURCE_INSTANCE_NAME 广告来源实例的名称（例如“AdMob（默认）”）。
MEDIATION_GROUP MEDIATION_GROUP_ID 中介组的唯一 ID（例如“1234567890”）。
MEDIATION_GROUP_NAME 中介组的唯一 ID（例如“AdMob（默认）”）。

1：如需了解详情，请参阅Scalars。

以下维度的格式已更新。

Mediation Report API 中的维度名称 Mediation Report API 中的说明 Ads Activity Report API 中的说明
ESTIMATED_EARNINGS AdMob 发布商的估算收入。货币单位（美元、 欧元或其他）的收入指标由本地化版本确定 货币设置。金额以微单位表示。例如，6.50 美元就是 以 6500000 的形式表示。

每个中介组和每个广告来源实例级别的估算收入现为 最早可追溯至 2019 年 10 月 20 日。第三方估算收入将 针对 2019 年 10 月 20 日之前的日期显示 0。

AdMob 发布商的估算收入。货币单位（美元、 欧元或其他）的收入指标由本地化版本确定 货币设置。
OBSERVED_ECPM 第三方广告联盟的平均有效每千次展示费用估算值。货币单位 （美元、欧元或其他）收入指标由本地化版本确定 货币设置。金额以微单位表示。例如，2.30 美元将是 表示为 2300000

每个中介组和每个广告来源实例级的平均有效每千次展示费用估算值 自 2019 年 10 月 20 日起才受支持。第三方估算的平均值 对于 2019 年 10 月 20 日之前的日期，eCPM 将显示为 0。

所有广告的平均有效每千次展示费用。以下列的货币单位（美元、欧元或其他） 收入指标取决于币种的本地化设置。

每个中介组和每个广告来源实例级别的平均有效每千次展示费用为 最早可追溯至 2019 年 10 月 20 日。对于日期，OBSERVED_ECPM 将显示为 0 2019 年 10 月 20 日之前的数据。

标量

Ads Activity Report API 中的以下维度已更新为 标量值，而不是对象。这样可以简化回答并减少 复杂性。

Mediation Report API 和 Network Report API 中受影响的维度：

  • AD_UNIT
  • APP
  • AD_SOURCE
  • AD_SOURCE_INSTANCE
  • MEDIATION_GROUP
报告响应数据示例
中介 / 广告联盟 API 维度格式 
"AD_UNIT": {
   "value":"ca-app-pub-XXXXXXXXXXXXXXXXX/YYYYYYYYYY",
   "displayLabel": "Test ad unit name"
   }
AAR API 维度格式 
"AD_UNIT_NAME": "Test ad unit name",
"AD_UNIT_ID": "ca-app-pub-XXXXXXXXXXXXXXXXX/YYYYYYYYYY"

每小时报告

现在，您可以在 AdMob API 中按小时查看效果。“每小时报告”现为 您的有效期为 28 天。

在检索每小时数据的请求中还必须指定 DATE 维度 数据。当“时段”维度设置为“小时”时，系统最多会返回 28 天的数据 。日期范围的开始日期超过 返回错误。

放大报告

借助 Ads Activity Report API，您总共可以检索 500,000 行数据。对于 如需了解更多信息，请参阅配额指南。

发出请求

请按照以下步骤提出请求。

curl（命令行）

使用 curl 的请求

  1. 加载客户端密钥文件并生成授权凭据。

    首次执行此步骤时，系统会提示您接受 授权提示。在接受之前，请确保您已 使用有权访问 AdMob API 的 Google 账号登录。您的 获得授权后，应用才能访问数据，具体取决于 账号目前已登录。

    对于身份验证和授权，我们建议使用 oauth2l，一种用于 与 Google OAuth 2.0 搭配使用安装 oauth2l 并运行 命令，将 path_to_credentials_json 替换为路径 保存到您的 credentials.json 文件中。 云应用首次运行时，此命令将引导您逐步完成 OAuth 2.0 授权流程。后续运行会刷新令牌 。

    ~/go/bin/oauth2l header --json path_to_credentials_json \
        https://www.googleapis.com/auth/admob.readonly

  2. 生成“广告活动”报告。

    curl -X POST https://admob.googleapis.com/v1alpha/accounts/pub-XXXXXXXXXXXXXXXX/adsActivityReport:generate \
     -H "Content-Type: application/json" \
     -H "$(~/go/bin/oauth2l header --json path_to_credentials_json https://www.googleapis.com/auth/admob.readonly)"  --data @- << EOF
      {
        "report_spec": {
        "date_range": {
          "start_date": {"year": 2023, "month": 1, "day": 1},
          "end_date": {"year": 2023, "month": 1, "day": 2}
        },
        "dimensions": ["DATE", "HOUR", "MEDIATION_AB_TEST", "VARIANT", "AD_SOURCE_ID", "AD_SOURCE_NAME"],
        "metrics": ["CLICKS", "BID_REQUEST","WINNING_BIDS", "IMPRESSIONS", "ESTIMATED_EARNINGS" ],
        "dimension_filters": [{"dimension": "COUNTRY", "matches_any": {"values": ["US"]}}],
        "sort_conditions": [{"metric":"CLICKS", "order": "DESCENDING"}],
        "localization_settings": {"currency_code": "USD", "language_code": "en-US"}
        }
      }
EOF

    示例响应：

    {
"rows": [
  {
    "dimensionValues": {
      "DATE": {
        "value": "20221102"
      },
      "HOUR": {
        "value": "23"
      },
      "MEDIATION_AB_TEST": {
        "value": "Mediation AB Test"
      },
      "VARIANT": {
        "value": "Variant A"
      },
      "AD_SOURCE_ID": {
        "value": "5450213213286189855"
      },
      "AD_SOURCE_NAME": {
        "value": "AdMob Network"
      }
    },
    "metricValues": {
      "CLICKS": {
        "doubleValue": 0
      },
      "BID_REQUEST": {
        "integerValue": "27"
      },
      "WINNING_BIDS": {
        "doubleValue": 0.1111111111111111
      },
      "IMPRESSIONS": {
        "integerValue": "2"
      },
      "ESTIMATED_EARNINGS": {
        "doubleValue": 0
      }
    }
  },
{
    "dimensionValues": {
      "DATE": {
        "value": "20221102"
      },
      "HOUR": {
        "value": "23"
      },
      "MEDIATION_AB_TEST": {
        "value": "Mediation AB Test"
      },
      "VARIANT": {
        "value": "Variant B"
      },
      "AD_SOURCE_ID": {
        "value": "5450213213286189855"
      },
      "AD_SOURCE_NAME": {
        "value": "AdMob Network"
      }
    },
    "metricValues": {
      "CLICKS": {
        "doubleValue": 1
      },
      "BID_REQUEST": {
        "integerValue": "6"
      },
      "WINNING_BIDS": {
        "doubleValue": 1
      },
      "IMPRESSIONS": {
        "integerValue": "3"
      },
      "ESTIMATED_EARNINGS": {
        "doubleValue": 0.000427519
      }
    }
  }
]}