Method: accounts.mediationReport.generate

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

طلب HTTP

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

يستخدِم عنوان URL بنية تحويل ترميز gRPC.

مَعلمات المسار

المعلمات
parent

string

اسم المورد للحساب الذي سيتم إنشاء التقرير له. مثال: accounts/pub-9876543210987654

نص الطلب

يحتوي نص الطلب على بيانات بالبنية التالية:

تمثيل JSON 
{
  "reportSpec": {
    object (MediationReportSpec)
  }
}
الحقول
reportSpec

object (MediationReportSpec)

مواصفات تقارير الشبكة

نص الاستجابة

استجابة البث لتقرير توسط 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": {"decimal_value": "1324746"}
    }
  }
},
{
  "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.

MediationReportSpec

مواصفات إنشاء تقرير توسّط AdMob. على سبيل المثال، مواصفات الحصول على التكلفة الفعلية لكل ألف ظهور المرصودة مقسَّمة حسب مصدر الإعلان والتطبيق لـ "الولايات المتحدة" و"CN" البلدان على النحو التالي:

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

لفهم أفضل، يمكنك معالجة المواصفات السابقة مثل لغة SQL الزائفة التالية:

SELECT AD_SOURCE, APP, COUNTRY, OBSERVED_ECPM
FROM MEDIATION_REPORT
WHERE DATE >= '2021-09-01' AND DATE <= '2021-09-30'
    AND COUNTRY IN ('US', 'CN')
GROUP BY AD_SOURCE, APP, COUNTRY
ORDER BY APP ASC;
تمثيل 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_SOURCE المعرّف الفريد لمصدر الإعلان (مثل "5450213213286189855" و"شبكة AdMob" كقيمة للتصنيف).
AD_SOURCE_INSTANCE المعرّف الفريد لمثيل مصدر الإعلان (مثل "ca-app-pub-1234:asi:5678" و"AdMob (تلقائي)" كقيمة تصنيف).
AD_UNIT المعرّف الفريد للوحدة الإعلانية (مثل "ca-app-pub-1234/8790"). إذا تم تحديد سمة AD_UNIT، يتم تضمين APP تلقائيًا.
APP المعرّف الفريد لتطبيق الأجهزة الجوّالة (على سبيل المثال، "ca-app-pub-1234~1234").
MEDIATION_GROUP المعرّف الفريد لمجموعة التوسط (على سبيل المثال، "ca-app-pub-1234:mg:1234" و"AdMob (تلقائي)" كقيمة تصنيف).
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 عدد الطلبات القيمة هي عدد صحيح.
CLICKS عدد المرّات التي ينقر فيها المستخدِم على إعلان القيمة هي عدد صحيح.
ESTIMATED_EARNINGS

الأرباح المقدّرة لناشر AdMob. يتمّ تحديد وحدة العملة (الدولار الأمريكي أو اليورو أو غيرها) في مقاييس الأرباح وفقًا لإعداد أقلمة العملة. يكون المبلغ بالمايكرو. على سبيل المثال، سيتم تمثيل 6.50 دولار أمريكي على هذا النحو: 6500000.

تعود الأرباح المقدّرة لكل مجموعة توسّط ولكل مستوى مثيل لمصدر إعلان إلى 20 تشرين الأول (أكتوبر) 2019. وستظهر الأرباح المقدّرة للجهات الخارجية القيمة 0 للتواريخ التي تسبق 20 تشرين الأول (أكتوبر) 2019.
IMPRESSIONS إجمالي عدد الإعلانات المعروضة للمستخدمين. القيمة هي عدد صحيح.
IMPRESSION_CTR نسبة النقرات إلى مرات الظهور. القيمة هي قيمة عشرية بدقة مزدوجة (تقريبية).
MATCHED_REQUESTS عدد المرّات التي يتم فيها عرض الإعلانات استجابةً لأحد الطلبات. القيمة هي عدد صحيح.
MATCH_RATE نسبة طلبات الإعلان المُطابِقة مقارنةً بإجمالي طلبات الإعلان. القيمة هي قيمة عشرية بدقة مزدوجة (تقريبية).
OBSERVED_ECPM

متوسّط التكلفة الفعلية المقدّرة لكلّ ألف ظهور على شبكة الإعلانات التابعة لجهات خارجية يتمّ تحديد وحدة العملة (الدولار الأمريكي أو اليورو أو غيرها) في مقاييس الأرباح وفقًا لإعداد أقلمة العملة. يكون المبلغ بالمايكرو. على سبيل المثال، سيتم تمثيل 2.30 دولار أمريكي على هذا النحو: 2300000.

يتوفّر متوسط التكلفة الفعلية المقدّرة لكلّ ألف ظهور لكل مجموعة توسّط ولكل مستوى مثيل لمصدر إعلان يعود تاريخه إلى 20 تشرين الأول (أكتوبر) 2019. سيعرض متوسط التكلفة الفعلية المقدّرة لكل ألف ظهور من جهة خارجية القيمة 0 للتواريخ التي تسبق 20 تشرين الأول (أكتوبر) 2019.

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)

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