Method: accounts.networkReport.generate

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

בקשת HTTP

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

בכתובת ה-URL נעשה שימוש בתחביר המרת gRPC.

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

פרמטרים
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). הערך של 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.

NetworkReportSpec

המפרט ליצירת דוח של רשת AdMob. לדוגמה, המפרט לקבלת קליקים ורווחים משוערים רק במדינות 'ארה"ב' ו-'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 TZ, כמו "America/Los_Angeles". אם לא הוגדר אזור זמן, ברירת המחדל של החשבון תיכנס לתוקף. יש לבדוק את ערך ברירת המחדל לפי הפעולה 'קבלת חשבון'.

אזהרה: הערך "America/Los_Angeles" הוא הערך היחיד שנתמך כרגע.

המאפיין

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

טיפוסים בני מנייה (enums)
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 מצב הגבלה על הצגת מודעות (למשל, "מודעות ללא התאמה אישית").

המדד

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

טיפוסים בני מנייה (enums)
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)

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