Method: accounts.networkReport.generate

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

בקשת HTTP

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

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

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

פרמטרים
parent

string

שם המקור של החשבון שעבורו נוצר הדוח. לדוגמה: accounts/pub-9876543210987654

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג ב-JSON 
{
  "reportSpec": {
    object (NetworkReportSpec)
  }
}
שדות
reportSpec

object (NetworkReportSpec)

מפרט דוח הרשת.

גוף התשובה

התגובה שמוחזרת בסטרימינג לדוח של רשת 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": {"microsValue": 6500000}
    }
  }
},
{
  "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.

NetworkReportSpec

המפרט ליצירת דוח רשת AdMob. לדוגמה, כדי לקבל נתונים של קליקים ורווחים משוערים רק לגבי המדינות 'US' ו-'CN', אפשר להשתמש במפרט שמופיע בדוגמה הבאה:

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

כדי להבין טוב יותר, אפשר להתייחס למפרט הקודם כמו אל פסאודו SQL הבא:

SELECT DATE, APP, COUNTRY, CLICKS, ESTIMATED_EARNINGS
FROM NETWORK_REPORT
WHERE DATE >= '2021-09-01' AND DATE <= '2021-09-30'
    AND COUNTRY IN ('US', 'CN')
GROUP BY DATE, APP, COUNTRY
ORDER BY APP ASC, CLICKS DESC;
ייצוג ב-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_UNIT המזהה הייחודי של יחידת המודעות (לדוגמה, ca-app-pub-1234/1234). אם מציינים את המאפיין AD_UNIT, המאפיין APP נכלל אוטומטית.
APP המזהה הייחודי של האפליקציה לנייד (לדוגמה, ca-app-pub-1234~1234).
AD_TYPE

סוג המודעה (לדוגמה, 'טקסט' או 'תמונה'), מאפיין של הצגת מודעות.

אזהרה: המאפיין לא תואם למדדים AD_REQUESTS, ‏ MATCH_RATE ו-IMPRESSION_RPM.
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 מצב הגבלה על הצגת מודעות (לדוגמה, 'מודעות ללא התאמה אישית').

מדד

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

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

מספר הבקשות להצגת מודעות. הערך הוא מספר שלם.

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

הרווחים המשוערים על כל אלף חשיפות של מודעה. הערך מופיע במיליוניות. לדוגמה, 1.03$‎ מיוצג כ-1030000. שווה לעלות בפועל לאלף חשיפות בממשק המשתמש של AdMob.

אזהרה: המדד לא תואם למאפיין AD_TYPE.
MATCHED_REQUESTS מספר הפעמים שהמודעות מוחזרות בתגובה לבקשה. הערך הוא מספר שלם.
MATCH_RATE

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

אזהרה: המדד לא תואם למאפיין AD_TYPE.
SHOW_RATE היחס בין המודעות שמוצגות לבין המודעות שמוחזרות, מוגדר כחשיפות חלקי בקשות שמולאו. הערך הוא מספר עשרוני (משוער) עם דיוק כפול.

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)

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