根據提供的報表規格產生「AdMob 中介服務」報表。傳回伺服器端串流 RPC 的結果。結果會依一連串的回應傳回。
HTTP 要求
POST https://admob.googleapis.com/v1beta/{parent=accounts/*}/mediationReport:generate
這個網址使用 gRPC 轉碼語法。
路徑參數
參數 | |
---|---|
parent |
要產生報表的帳戶資源名稱。範例:accounts/pub-9876543210987654 |
要求主體
要求主體的資料會採用以下結構:
JSON 表示法 |
---|
{
"reportSpec": {
object ( |
欄位 | |
---|---|
reportSpec |
網路報表規格。 |
回應主體
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 。每個串流回應訊息都包含一種酬載。payload 只能是下列其中一項: |
|
header |
說明報表內容的報表產生設定,例如報表日期範圍和本地化設定。 |
row |
實際報表資料。 |
footer |
已產生報表的其他資訊,例如關於資料的警告。 |
授權範圍
需要下列其中一種 OAuth 範圍:
https://www.googleapis.com/auth/admob.readonly
https://www.googleapis.com/auth/admob.report
詳情請參閱 OAuth 2.0 總覽。
MediationReportSpec
產生 AdMob 中介服務報表的規格。舉例來說,要按照廣告來源和應用程式區分「美國」和「中國」國家/地區的 ECPM 規格,範例看起來就會像這樣:
{
"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[] |
報表維度清單。這些維度的組合會決定報表列。如果沒有指定維度,報表只會為整個帳戶傳回一列所要求的指標。 |
metrics[] |
報表指標清單。報表必須指定至少一個指標。 |
dimensionFilters[] |
說明要根據維度值比對哪些報表列。 |
sortConditions[] |
說明報表列的排序方式。清單中的條件順序會決定優先順序;如果條件越早,則優先順序越高。如果沒有指定排序條件,則不會定義資料列順序。 |
localizationSettings |
報表的本地化設定。 |
maxReportRows |
要傳回的報表資料列數量上限。如未設定這個值,API 會盡可能傳回最多 10,0000 列。可接受的值為 1-100000 (含頭尾)。大於 100000 的值會傳回錯誤。 |
timeZone |
報表時區。接受 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 |
將篩選器條件套用至指定維度。 |
聯集欄位 operator 。要套用的篩選器運算子。operator 只能是下列其中一項: |
|
matchesAny |
如果指定維度的值屬於此條件的其中一個指定值,則比對資料列。 |
SortCondition
要套用至維度或指標的排序方向。
JSON 表示法 |
---|
{ "order": enum ( |
欄位 | |
---|---|
order |
維度或指標的排序順序。 |
聯集欄位 sort_on 。找出要排序的值。sort_on 只能是下列其中一項: |
|
dimension |
按照指定的維度排序。 |
metric |
按照指定指標排序。 |