Method: accounts.networkReport.generate

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

בקשת HTTP

POST https://admob.googleapis.com/v1beta/{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". אם לא הוגדר אזור זמן, ברירת המחדל של החשבון תיכנס לתוקף. בודקים את ערך ברירת המחדל לפי הפעולה 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. יחידת המטבע (דולר ארה"ב, אירו או מטבע אחר) של מדדי הרווחים נקבעים לפי הגדרת ההתאמה לשוק המקומי של המטבע. הסכום הוא במיליוניות השנייה. לדוגמה, $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)

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