Method: accounts.mediationReport.generate

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

طلب 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

الحد الأقصى لعدد صفوف بيانات التقرير المطلوب عرضها. في حال عدم ضبط القيمة، تعرِض واجهة برمجة التطبيقات أكبر عدد ممكن من الصفوف، بما يصل إلى 100000. القيم المقبولة هي 1-100000، ضمنًا. تعرض القيم الأكبر من 100000 خطأ.
timeZone

string

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

تحذير: القيمة "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)

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