廣告活動報表 Alpha 版 API

「廣告活動」報表是一套 集中查看廣告成效。這項工具結合了資料、指標 加入聯播網報表 API 和中介服務報表 API 將出價資料彙整成一份整合式報表

廣告活動報表 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 時間維度
小時 太平洋標準時間 HH 格式的小時值。例如「05」早上 5 點 (太平洋標準時間)，「13」 下午 1 點 (太平洋標準時間)。您也必須在請求中指定 DATE 維度。A 罩杯 指定 時段 維度時，最多會傳回 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_GROUP1 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 發布商的預估收益。貨幣單位 (USD、 歐元等) 的收益指標取決於本地化內容 貨幣設定。金額以微量為單位。舉例來說，$6.50 會是 以 6500000 表示

每個中介服務群組和廣告來源例項層級的預估收益為 支援的版本最早可回溯至 2019 年 10 月 20 日。第三方預估收益將 顯示 0，日期早於 2019 年 10 月 20 日。

AdMob 發布商的預估收益。貨幣單位 (USD、 歐元等) 的收益指標取決於本地化內容 貨幣設定。
OBSERVED_ECPM 第三方廣告聯播網的預估平均有效千次曝光出價。貨幣單位 收益指標 (美元、歐元或其他) 取決於本地化 貨幣設定。金額以微量為單位。舉例來說，$2.30 美元會是 以 2300000 表示

每個中介服務群組和廣告來源例項層級的預估平均有效千次曝光出價 支援的服務日期可追溯至 2019 年 10 月 20 日第三方預估平均值 在 2019 年 10 月 20 日之前，有效千次曝光出價會顯示為 0。

所有廣告的平均有效千次曝光出價。貨幣單位 (美元、歐元或其他) 收益指標取決於貨幣的本地化設定。

每個中介服務群組和每個廣告來源例項層級的平均有效千次曝光出價為 支援的版本最早可回溯至 2019 年 10 月 20 日。在日期的 OBSERVED_ECPM 會顯示為 0 2019 年 10 月 20 日前的資料

純量

廣告活動報表 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 天的資料 。日期範圍開始日期和開始日前的 28 天以上 目前日期傳回錯誤。

報表大小較大

廣告活動報表 API 可讓您擷取總計 500,000 列資料。適用對象 詳情請參閱配額指南。

提出要求

請按照下列步驟提出要求。

curl (指令列)

使用 curl 的要求

  1. 載入用戶端密鑰檔案並產生授權憑證。

    系統會在您第一次執行這個步驟時，要求您接受 在瀏覽器中輸入授權提示接受前，請務必確認 使用可存取 AdMob API 的 Google 帳戶登入。您的 應用程式將有權代表 目前登入的帳戶。

    如要進行驗證和授權，建議您使用 oauth2l 是簡便的指令列工具 才能使用 Google OAuth 2.0安裝 OAuth2l 並執行 指令，將 path_to_credentials_json 換成路徑 連結至您在註冊 SDK 時下載的 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
      }
    }
  }
]}