- בקשת HTTP
- פרמטרים של נתיב
- גוף הבקשה
- גוף התשובה
- היקפי ההרשאות
- MediationReportSpec
- מאפיין
- מדד
- DimensionFilter
- SortCondition
- דוגמאות
- רוצים לנסות?
יוצר דוח של תהליך בחירת הרשת ב-AdMob על סמך מפרט הדוח שסופק. מחזירה תוצאה של RPC בסטרימינג בצד השרת. התוצאה מוחזרת לפי רצף של תגובות.
בקשת HTTP
POST https://admob.googleapis.com/v1beta/{parent=accounts/*}/mediationReport:generate
בכתובת ה-URL נעשה שימוש בתחביר המרת קידוד של 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). payload יכול להיות רק אחד מהבאים: |
|
header |
הגדרות של יצירת דוח שמתארות את תוכן הדוח, כגון טווח התאריכים של הדוח והגדרות הלוקליזציה. |
row |
נתוני הדוח בפועל. |
footer |
מידע נוסף לגבי הדוח שנוצר, כמו אזהרות לגבי הנתונים. |
היקפי הרשאות
נדרש אחד מהיקפי ההרשאות הבאים של 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[] |
רשימת המאפיינים של הדוח. שילוב הערכים של המאפיינים האלה קובע את השורה בדוח. אם לא צוינו מאפיינים, הדוח יחזיר שורה אחת של המדדים המבוקשים לחשבון כולו. |
metrics[] |
רשימת המדדים של הדוח. דוח צריך לציין לפחות מדד אחד. |
dimensionFilters[] |
מתאר לאילו שורות בדוח יש להתאים על סמך ערכי המאפיינים שלהן. |
sortConditions[] |
מתאר את המיון של שורות הדוח. הסדר של התנאי ברשימה מגדיר את הקדימות שלו. ככל שהתנאי מוקדם יותר, כך הקדימות שלו גבוהה יותר. אם לא מציינים תנאי מיון, סדר השורות לא מוגדר. |
localizationSettings |
הגדרות הלוקליזציה של הדוח. |
maxReportRows |
המספר המקסימלי של שורות נתוני הדוח שיש להחזיר. אם הערך לא מוגדר, ה-API מחזיר כמה שיותר שורות, עד 100,000. הערכים הקבילים הם 1-100000, כולל. ערכים גדולים מ-100000 מחזירים שגיאה. |
timeZone |
אזור זמן לדיווח. מקבל ערכי שמות של IANA TZ, כמו "America/Los_Angeles". אם לא הוגדר אזור זמן, ברירת המחדל של החשבון תיכנס לתוקף. יש לבדוק את ערך ברירת המחדל לפי הפעולה 'קבלת חשבון'. אזהרה: הערך "America/Los_Angeles" הוא הערך היחיד שנתמך כרגע. |
המאפיין
המאפיינים של דוח תהליך בחירת הרשת. מאפיינים הם מאפייני נתונים שמאפשרים להציג פירוט או לצמצם את המדדים הכמותיים (מדדים) לפי מאפיינים מסוימים, כמו פורמט המודעה או הפלטפורמה שבה צפו במודעה.
טיפוסים בני מנייה (enums) | |
---|---|
DIMENSION_UNSPECIFIED |
ערך ברירת המחדל בשדה לא מוגדר. אין להשתמש בו. |
DATE |
תאריך בפורמט YYYYMMDD (לדוגמה, '20210701'). בבקשות ניתן לציין מאפיין זמן אחד לכל היותר. |
MONTH |
חודש בפורמט YYYYMM (לדוגמה, '202107'). בבקשות ניתן לציין מאפיין זמן אחד לכל היותר. |
WEEK |
התאריך של היום הראשון בשבוע בפורמט YYYYMMDD (לדוגמה, '20210701'). בבקשות ניתן לציין מאפיין זמן אחד לכל היותר. |
AD_SOURCE |
המזהה הייחודי של מקור המודעות (לדוגמה, '5450213213286189855' ו'רשת AdMob' כערך התווית). |
AD_SOURCE_INSTANCE |
המזהה הייחודי של המופע של מקור המודעות (לדוגמה, ערך התווית 'ca-app-pub-1234:asi:5678' ו-'AdMob (ברירת מחדל)'). |
AD_UNIT |
המזהה הייחודי של יחידת המודעות (לדוגמה, 'ca-app-pub-1234/8790'). אם תציינו ממד AD_UNIT, אז APP נכלל באופן אוטומטי. |
APP |
המזהה הייחודי של האפליקציה לנייד (לדוגמה, 'ca-app-pub-1234~1234'). |
MEDIATION_GROUP |
המזהה הייחודי של הקבוצה לבחירת רשת (למשל, '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, שם הגרסה של האפליקציה נמצא בקטע versionName ב-PackageInfo. ב-iOS, השם של גרסת האפליקציה מופיע ב-CFBundleShortVersionString. |
SERVING_RESTRICTION |
מצב הגבלה על הצגת מודעות (למשל, "מודעות ללא התאמה אישית"). |
המדד
המדדים בדוח של תהליך בחירת הרשת. מדדים הם אומדנים כמותיים שמציינים את הביצועים של העסק של בעל התוכן הדיגיטלי. הם נצברים מאירועי המודעות הבודדים ומקובצים לפי מאפייני הדוח. הערך המספרי יכול להיות מספר שלם או עשרוני (ללא עיגול).
טיפוסים בני מנייה (enums) | |
---|---|
METRIC_UNSPECIFIED |
ערך ברירת המחדל בשדה לא מוגדר. אין להשתמש בו. |
AD_REQUESTS |
מספר הבקשות. הערך הוא מספר שלם. |
CLICKS |
מספר הפעמים שבהן משתמש לחץ על מודעה. הערך הוא מספר שלם. |
ESTIMATED_EARNINGS |
הרווחים המשוערים של בעל האפליקציה ב-AdMob. יחידת המטבע (USD, EUR או אחר) של מדדי הרווחים נקבעים על ידי הגדרת הלוקליזציה של המטבע. הסכום הוא במיליוניות השנייה. לדוגמה, $6.50 מיוצג כ-6500000. רווחים משוערים לכל קבוצה לבחירת רשת (Mediation) ולכל מופע של מקור מודעות נתמכים החל מ-20 באוקטובר 2019. הרווחים המשוערים של צד שלישי יופיעו כ-0 בתאריכים שלפני 20 באוקטובר 2019. |
IMPRESSIONS |
המספר הכולל של המודעות שמוצגות למשתמשים. הערך הוא מספר שלם. |
IMPRESSION_CTR |
היחס בין קליקים לחשיפות. הערך הוא ערך עשרוני בדיוק כפול (בקירוב). |
MATCHED_REQUESTS |
מספר הפעמים שמודעות מוחזרות בתגובה לבקשה. הערך הוא מספר שלם. |
MATCH_RATE |
היחס של הבקשות למודעות שמולאו מתוך סך הבקשות להצגת מודעות. הערך הוא ערך עשרוני בדיוק כפול (בקירוב). |
OBSERVED_ECPM |
אומדן של העלות הממוצעת בפועל לאלף חשיפות של רשת המודעות של צד שלישי. יחידת המטבע (USD, EUR או אחר) של מדדי הרווחים נקבעים על ידי הגדרת הלוקליזציה של המטבע. הסכום הוא במיליוניות השנייה. לדוגמה, $2.30 מיוצג כ-2300000. העלות הממוצעת המשוערת בפועל לאלף חשיפות לכל קבוצה לבחירת רשת ולכל מופע של מקור מודעות נתמכת החל מ-20 באוקטובר 2019. העלות הממוצעת המשוערת בפועל לאלף חשיפות של צד שלישי תוצג כ-0 בתאריכים שלפני 20 באוקטובר 2019. |
DimensionFilter
מתאר לאילו שורות בדוח יש להתאים על סמך ערכי המאפיינים שלהן.
ייצוג JSON |
---|
{ "dimension": enum ( |
שדות | |
---|---|
dimension |
החלת הקריטריון של המסנן על המאפיין שצוין. |
שדה איחוד operator . אופרטור המסנן שיוחל. operator יכול להיות רק אחד מהבאים: |
|
matchesAny |
תואמת שורה אם הערך של המאפיין שצוין נמצא באחד מהערכים שצוינו בתנאי הזה. |
SortCondition
כיוון המיון שיוחל על מאפיין או על מדד.
ייצוג JSON |
---|
{ "order": enum ( |
שדות | |
---|---|
order |
סדר המיון של המאפיין או המדד. |
שדה איחוד sort_on . לפי אילו ערכים למיין. sort_on יכול להיות רק אחד מהבאים: |
|
dimension |
מיון לפי המאפיין שצוין. |
metric |
מיון לפי המדד שצוין. |