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 إحدى القيم التالية فقط:
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" على سبيل المثال، يمكن أن تبدو المواصفات للحصول على النقرات والأرباح المقدّرة للبلدين "الولايات المتحدة" و"الصين" فقط على النحو التالي:

{
  '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، مثل "America/Los_Angeles". في حال عدم تحديد منطقة زمنية، سيتم تطبيق الإعداد التلقائي للحساب. تحقَّق من القيمة التلقائية من خلال إجراء الحصول على الحساب.

تحذير: "America/Los_Angeles" هي القيمة الوحيدة المتاحة حاليًا.

السمة

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

عمليات التعداد
DIMENSION_UNSPECIFIED القيمة التلقائية لحقل لم يتم ضبطه لا تستخدم هذه السمة.
DATE تاريخ بالتنسيق YYYYMMDD (مثلاً "20210701"). يمكن أن تحدّد الطلبات سمة وقت واحدة كحدّ أقصى.
MONTH شهر بالتنسيق YYYYMM (مثلاً، "202107"). يمكن أن تحدّد الطلبات سمة وقت واحدة كحدّ أقصى.
WEEK تاريخ اليوم الأول من الأسبوع بالتنسيق YYYYMMDD (مثلاً، "20210701"). يمكن أن تحدّد الطلبات سمة وقت واحدة كحدّ أقصى.
AD_UNIT المعرّف الفريد للوحدة الإعلانية (على سبيل المثال، "ca-app-pub-1234/1234"). في حال تحديد السمة "الوحدة الإعلانية"، يتم تضمين التطبيق تلقائيًا.
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)

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