Method: accounts.mediationReport.generate

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

طلب HTTP

POST https://admob.googleapis.com/v1beta/{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 Overview.

MediationReportSpec

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

{
  "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، مثل "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"). في حال تحديد السمة "الوحدة الإعلانية"، يتم تضمين التطبيق تلقائيًا.
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)

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