Method: accounts.mediationReport.generate

הסקריפט הזה יוצר דוח של מנגנון בחירת הרשת ב-AdMob על סמך הגדרות הדוח שצוינו. מחזירה את התוצאה של RPC להזרמת נתונים בצד השרת. התוצאה מוחזרת ברצף של תגובות.

בקשת HTTP

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

כתובת ה-URL כתובה בתחביר של gRPC Transcoding.

פרמטרים של נתיב

פרמטרים
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 Overview.

MediationReportSpec

המפרט ליצירת דוח על תהליך בחירת הרשת ב-AdMob. לדוגמה, המפרט לקבלת נתוני eCPM שנמדדו, מפולחים לפי מקור תנועה ממודעות ואפליקציה, עבור המדינות '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 מחזיר כמה שיותר שורות, עד 100,000. הערכים הקבילים הם 1 עד 100, 000 כולל. ערכים שגדולים מ-100,000 מחזירים שגיאה.
timeZone

string

אזור זמן לדיווח. הפונקציה מקבלת ערכים של שמות אזורי זמן של IANA, כמו America/Los_Angeles. אם לא מוגדר אזור זמן, ברירת המחדל של החשבון נכנסת לתוקף. בודקים את ערך ברירת המחדל באמצעות הפעולה get account.

אזהרה: בשלב הזה, הערך הנתמך היחיד הוא America/Los_Angeles.

מאפיין

המאפיינים של דוח תהליך בחירת הרשת. מאפיינים הם תכונות של נתונים שמאפשרות לפרק או לחדד את המדידות הכמותיות (מדדים) לפי תכונות מסוימות, כמו פורמט המודעה או הפלטפורמה שבה צפו במודעה.

טיפוסים בני מנייה (enum)
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). מדדים הם מדידות כמותיות שמצביעות על הביצועים של העסק של בעל התוכן הדיגיטלי. הם מצטברים מאירועי המודעות הבודדים ומקובצים לפי המאפיינים של הדוח. ערך המדד הוא מספר שלם או מספר עשרוני (ללא עיגול).

טיפוסים בני מנייה (enum)
METRIC_UNSPECIFIED ערך ברירת המחדל של שדה שלא הוגדר. אין להשתמש בו.
AD_REQUESTS מספר הבקשות. הערך הוא מספר שלם.
CLICKS מספר הפעמים שמשתמש לחץ על מודעה. הערך הוא מספר שלם.
ESTIMATED_EARNINGS

הרווחים המשוערים של בעל האפליקציה ב-AdMob. יחידת המטבע (USD,‏ EUR או אחר) של מדדי הרווח נקבעת לפי הגדרת הלוקליזציה של המטבע. הסכום מצוין במיליוניות. לדוגמה, הסכום 6.50$ ייוצג כ-6500000.

המדד 'רווחים משוערים' ברמת הקבוצה לבחירת רשת וברמת המופע של מקור המודעות נתמך החל מ-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),

  // 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)

מיון לפי המדד שצוין.