Method: accounts.mediationReport.generate

根據提供的報表規格產生 AdMob 中介服務報表。傳回伺服器端串流 RPC 的結果。系統會透過回應序列傳回結果。

HTTP 要求

POST https://admob.googleapis.com/v1beta/{parent=accounts/*}/mediationReport:generate

這個網址使用 gRPC 轉碼語法。

路徑參數

參數
parent

string

要產生報表的帳戶資源名稱。範例:accounts/pub-9876543210987654

要求主體

要求主體的資料會採用以下結構:

JSON 表示法
{
  "reportSpec": {
    object (MediationReportSpec)
  }
}
欄位
reportSpec

object (MediationReportSpec)

網路報告規格。

回應主體

AdMob 中介服務報表的串流回應,第一個回應包含報表標頭,然後是一列回應,最後以頁尾做為最後一個回應訊息。

例如:

[{
  "header": {
    "dateRange": {
      "startDate": {"year": 2018, "month": 9, "day": 1},
      "endDate": {"year": 2018, "month": 9, "day": 1}
    },
    "localizationSettings": {
      "currencyCode": "USD",
      "languageCode": "en-US"
    }
  }
},
{
  "row": {
    "dimensionValues": {
      "DATE": {"value": "20180918"},
      "APP": {
        "value": "ca-app-pub-8123415297019784~1001342552",
         "displayLabel": "My app name!"
      }
    },
    "metricValues": {
      "ESTIMATED_EARNINGS": {"decimal_value": "1324746"}
    }
  }
},
{
  "footer": {"matchingRowCount": 1}
}]

如果成功,回應主體會含有以下結構的資料:

JSON 表示法
{

  // Union field payload can be only one of the following:
  "header": {
    object (ReportHeader)
  },
  "row": {
    object (ReportRow)
  },
  "footer": {
    object (ReportFooter)
  }
  // End of list of possible types for union field payload.
}
欄位
聯集欄位 payload。每個串流回應訊息都包含一種酬載。payload 只能是下列其中一項:
header

object (ReportHeader)

說明報表內容的報表產生設定,例如報表日期範圍和本地化設定。

row

object (ReportRow)

實際報表資料。

footer

object (ReportFooter)

所產生報表的其他相關資訊,例如資料警告。

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/admob.readonly
  • https://www.googleapis.com/auth/admob.report

詳情請參閱 OAuth 2.0 總覽

MediationReportSpec

產生 AdMob 中介服務報表的規格。舉例來說,針對「US」的廣告來源和應用程式,取得觀察到的有效千次曝光出價 (按照廣告來源和應用程式劃分)和「CN」國家/地區如以下範例所示:

{
  "dateRange": {
    "startDate": {"year": 2021, "month": 9, "day": 1},
    "endDate": {"year": 2021, "month": 9, "day": 30}
  },
  "dimensions": ["AD_SOURCE", "APP", "COUNTRY"],
  "metrics": ["OBSERVED_ECPM"],
  "dimensionFilters": [
    {
      "dimension": "COUNTRY",
      "matchesAny": {"values": [{"value": "US", "value": "CN"}]}
    }
  ],
  "sortConditions": [
    {"dimension":"APP", order: "ASCENDING"}
  ],
  "localizationSettings": {
    "currencyCode": "USD",
    "languageCode": "en-US"
  }
}

為了深入瞭解,您可以將上述規格視為下列虛擬 SQL:

SELECT AD_SOURCE, APP, COUNTRY, OBSERVED_ECPM
FROM MEDIATION_REPORT
WHERE DATE >= '2021-09-01' AND DATE <= '2021-09-30'
    AND COUNTRY IN ('US', 'CN')
GROUP BY AD_SOURCE, APP, COUNTRY
ORDER BY APP ASC;
JSON 表示法
{
  "dateRange": {
    object (DateRange)
  },
  "dimensions": [
    enum (Dimension)
  ],
  "metrics": [
    enum (Metric)
  ],
  "dimensionFilters": [
    {
      object (DimensionFilter)
    }
  ],
  "sortConditions": [
    {
      object (SortCondition)
    }
  ],
  "localizationSettings": {
    object (LocalizationSettings)
  },
  "maxReportRows": integer,
  "timeZone": string
}
欄位
dateRange

object (DateRange)

產生報表的日期範圍。

dimensions[]

enum (Dimension)

報表維度清單。系統會根據這些維度的值組合,決定報表中的資料列。如果沒有指定維度,報表就會把整個帳戶的請求指標資料列成一列。

metrics[]

enum (Metric)

報表的指標清單。報表必須至少指定一個指標。

dimensionFilters[]

object (DimensionFilter)

說明要根據維度值比對哪些報表列。

sortConditions[]

object (SortCondition)

說明報表列的排序。清單中的條件順序定義了其優先順序;條件的值越早,優先順序就越高。如果沒有指定排序條件,資料列的順序就不會定義。

localizationSettings

object (LocalizationSettings)

報表的本地化設定。

maxReportRows

integer

要傳回的報表資料列數量上限。如未設定這個值,API 會盡可能傳回最多 100000 列。可接受的值為 1-100000 (含首尾)。大於 100000 的值會傳回錯誤。

timeZone

string

報表時區。接受 IANA TZ 名稱值,例如「America/Los_Angeles」。如果沒有定義時區,帳戶預設設定就會生效。依據「取得帳戶」動作檢查預設值。

警告:「America/Los_Angeles」是目前唯一支援的值。

維度

中介服務報表的維度。維度是一種資料屬性,可根據特定屬性 (例如廣告格式或廣告放送平台) 細分或修正量化評估 (指標)。

列舉
DIMENSION_UNSPECIFIED 未設定欄位的預設值。請勿使用。
DATE 採用 YYYYMMDD 格式的日期 (例如「20210701」)。請求最多只能指定一個維度。
MONTH 採用 YYYYMM 格式的月份 (例如「202107」)。請求最多只能指定一個維度。
WEEK 一週的第一天,以 YYYYMMDD 格式表示 (例如「20210701」)。請求最多只能指定一個維度。
AD_SOURCE 廣告來源的專屬 ID (例如「5450213213286189855」和「AdMob 聯播網」做為標籤值)。
AD_SOURCE_INSTANCE 廣告來源執行個體的專屬 ID (例如「ca-app-pub-1234:asi:5678」和「AdMob (預設)」) 做為標籤值。
AD_UNIT 廣告單元的專屬 ID (例如「ca-app-pub-1234/8790」)。如果指定 AD_UNIT 維度,系統會自動加入 APP。
APP 行動應用程式的專屬 ID (例如「ca-app-pub-1234~1234」)。
MEDIATION_GROUP 中介服務群組的專屬 ID (例如「ca-app-pub-1234:mg:1234」和「AdMob (預設)」) 做為標籤值。
COUNTRY 廣告瀏覽/點擊位置的 CLDR 國家/地區代碼 (例如「US」或「FR」)。這是地理位置維度。
FORMAT 廣告單元的格式 (例如「橫幅」、「原生」),廣告放送維度。
PLATFORM 應用程式的行動作業系統平台 (例如「Android」或「iOS」)。
MOBILE_OS_VERSION 行動作業系統版本,例如「iOS 13.5.1」。
GMA_SDK_VERSION GMA SDK 版本,例如「iOS 7.62.0」。
APP_VERSION_NAME 如果是 Android 應用程式,您可以在 PackageInfo 的 versionName 中找到應用程式版本名稱。如果是 iOS,您可以在 CFBundleShortVersionString 中找到應用程式版本名稱。
SERVING_RESTRICTION 廣告放送的限制模式 (例如「非個人化廣告」)。

指標

中介服務報表的指標。指標是量化衡量值,可以顯示發布商業務成效。這些資料是從個別廣告事件匯總而來,並按報表維度分組。指標值可以是整數或小數 (無四捨五入)。

列舉
METRIC_UNSPECIFIED 未設定欄位的預設值。請勿使用。
AD_REQUESTS 要求數。這個值為整數。
CLICKS 使用者點按廣告的次數。這個值為整數。
ESTIMATED_EARNINGS

AdMob 發布商的預估收益。收益指標的貨幣單位 (美元、歐元或其他) 取決於貨幣的本地化設定。金額以微量為單位。例如 $6.50 美元會以 6500000 表示。

系統支援每個中介服務群組和每個廣告來源執行個體層級的預估收益自 2019 年 10 月 20 日起,凡是 2019 年 10 月 20 日之前的第三方預估收益,都會顯示為 0。

IMPRESSIONS 廣告向使用者顯示的總次數。這個值為整數。
IMPRESSION_CTR 點擊次數除以曝光次數的比率。這個值是雙精度 (近似) 小數值。
MATCHED_REQUESTS 回應請求而傳回廣告的次數。這個值為整數。
MATCH_RATE 比對成功的廣告請求數在廣告請求總數的比率。這個值是雙精度 (近似) 小數值。
OBSERVED_ECPM

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

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

DimensionFilter

說明要根據維度值比對哪些報表列。

JSON 表示法
{
  "dimension": enum (Dimension),

  // Union field operator can be only one of the following:
  "matchesAny": {
    object (StringList)
  }
  // End of list of possible types for union field operator.
}
欄位
dimension

enum (Dimension)

將篩選條件套用至指定維度。

聯集欄位 operator。要套用的篩選器運算子。operator 只能是下列其中一項:
matchesAny

object (StringList)

如果指定維度的值位於這個條件中指定的其中一個值,系統就會比對資料列。

SortCondition

要套用至維度或指標的排序方向。

JSON 表示法
{
  "order": enum (SortOrder),

  // Union field sort_on can be only one of the following:
  "dimension": enum (Dimension),
  "metric": enum (Metric)
  // End of list of possible types for union field sort_on.
}
欄位
order

enum (SortOrder)

維度或指標的排序順序。

聯集欄位 sort_on。識別要排序的值。sort_on 只能是下列其中一項:
dimension

enum (Dimension)

按指定維度排序。

metric

enum (Metric)

按指定指標排序。