Method: accounts.networkReport.generate

تُنشئ تقريرًا لشبكة AdMob استنادًا إلى مواصفات التقارير المقدَّمة. يعرض نتيجة استدعاء إجراء عن بُعد للبث من جهة الخادم. ويتم عرض النتيجة في تسلسل من الردود.

طلب 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 واحدًا فقط مما يلي:
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

الحد الأقصى لعدد صفوف بيانات التقرير المطلوب عرضها. وفي حال ترك هذه السياسة بدون ضبط، ستعرض واجهة برمجة التطبيقات أكبر عدد ممكن من الصفوف، بما يصل إلى 100,000 صف. القيم المقبولة هي 1-100000 بشكل شامل. تعرض القيم الأكبر من 100000 خطأ.
timeZone

string

منطقة زمنية للتقرير. يتم قبول قيم اسم IANA TZ، مثل "America/Los_Angeles". إذا لم يتم تحديد منطقة زمنية، سيتم تطبيق الإعداد التلقائي للحساب. تحقّق من القيمة التلقائية عن طريق إجراء الحصول على الحساب.

تحذير: The "America/Los_Angeles" هي القيمة الوحيدة المسموح بها في الوقت الحالي.

السمة

أبعاد تقرير الشبكة. السمات هي سمات بيانات لتقسيم أو تحسين القياسات الكمية (المقاييس) الكمية حسب سمات معيّنة، مثل شكل الإعلان أو المنصّة التي تمت مشاهدة الإعلان عليها.

عمليات التعداد
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 إصدار حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" مثلاً "iOS 7.62.0".
APP_VERSION_NAME بالنسبة إلى نظام التشغيل Android، يمكن العثور على اسم إصدار التطبيق في versionName في PackageInfo. بالنسبة إلى نظام التشغيل iOS، يمكن العثور على اسم إصدار التطبيق في CFBundleShortVersionString.
SERVING_RESTRICTION وضع تقييد المحتوى لعرض الإعلانات (مثل "الإعلانات غير المخصّصة")

المقياس

مقاييس تقرير الشبكة. المقاييس هي مقاييس كمّية تشير إلى مستوى أداء النشاط التجاري للناشر. ويتم تجميعها من أحداث الإعلانات الفردية وتجميعها حسب سمات التقرير. تكون قيمة المقياس إما عددًا صحيحًا أو عددًا عشريًا (بدون التقريب).

عمليات التعداد
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)

الترتيب حسب المقياس المحدّد