- בקשת HTTP
- פרמטרים של נתיב
- גוף הבקשה
- גוף התשובה
- היקפי הרשאות
- MediationReportSpec
- מאפיין
- מדד
- DimensionFilter
- SortCondition
- דוגמאות
- רוצים לנסות?
יוצר דוח של תהליך בחירת הרשת ב-AdMob על סמך מפרט הדוח שצוין. מחזירה תוצאה של RPC בסטרימינג בצד השרת. התוצאה מוחזרת ברצף של תגובות.
בקשת HTTP
POST https://admob.googleapis.com/v1/{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. לדוגמה, המפרט לחישוב עלות בפועל שדווחה לאלף חשיפות (ECPM) בפילוח לפי מקור מודעות ואפליקציה במדינות 'ארה"ב' ו-'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-100,000, כולל. ערכים גדולים מ-100,000 מחזירים שגיאה. |
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 |
מצב הגבלה על הצגת מודעות (למשל, "מודעות ללא התאמה אישית"). |
המדד
המדדים בדוח של תהליך בחירת הרשת (Mediation). מדדים הם אומדנים כמותיים שמציינים את הביצועים של העסק של בעל התוכן הדיגיטלי. הם נצברים לפי אירועי המודעות הבודדים ומקובצים לפי מאפייני הדוח. הערך המדדי יכול להיות מספר שלם או עשרוני (ללא עיגול).
טיפוסים בני מנייה (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 |
מיון לפי המדד שצוין. |