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 رقم التعريف الفريد لتطبيق الأجهزة الجوّالة (على سبيل المثال، "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)

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