- طلب HTTP
- مَعلمات المسار
- نص الطلب
- نص الاستجابة
- نطاقات التفويض
- MediationReportSpec
- السمة
- المقياس
- DimensionFilter
- SortCondition
- أمثلة
- جرِّبه الآن
تُنشئ تقرير توسّط AdMob استنادًا إلى مواصفات التقرير المقدَّمة. لعرض نتيجة RPC للبث من جهة الخادم. ويتم عرض النتيجة في تسلسل من الردود.
طلب HTTP
POST https://admob.googleapis.com/v1/{parent=accounts/*}/mediationReport:generate
يستخدم عنوان URL بنية تحويل الترميز gRPC.
معلمات المسار
المَعلمات | |
---|---|
parent |
اسم مورد الحساب لإنشاء التقرير له. مثال: accounts/pub-9876543210987654 |
نص الطلب
يحتوي نص الطلب على بيانات بالبنية التالية:
تمثيل JSON |
---|
{
"reportSpec": {
object ( |
الحقول | |
---|---|
reportSpec |
مواصفات تقرير الشبكة. |
نص الاستجابة
استجابة البث لتقرير "توسّط 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 تحتوي كل رسالة استجابة للبث على نوع واحد من الحمولة. يمكن أن يكون الحقل "payload " واحدًا فقط مما يلي: |
|
header |
إعدادات إنشاء التقرير التي تصف محتوى التقرير، مثل النطاق الزمني للتقرير وإعدادات الأقلمة |
row |
بيانات التقرير الفعلية. |
footer |
معلومات إضافية عن التقرير الذي تمّ إنشاؤه، مثل التحذيرات المتعلّقة بالبيانات |
نطاقات التفويض
يتطلب استخدام أحد نطاقات 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[] |
قائمة أبعاد التقرير. وتحدِّد مجموعة قيم هذه السمات الصفّ في التقرير. إذا لم يتم تحديد أي سمات، يعرض التقرير صفًا واحدًا من المقاييس المطلوبة للحساب بالكامل. |
metrics[] |
تمثّل هذه السمة قائمة بمقاييس التقرير. يجب أن يحدّد التقرير مقياسًا واحدًا على الأقل. |
dimensionFilters[] |
يصف صفوف التقرير المطلوب مطابقتها استنادًا إلى قيم السمات. |
sortConditions[] |
تصف طريقة ترتيب صفوف التقرير. يحدّد ترتيب الشرط في القائمة أسبقيته، وكلما كان الشرط في وقت مبكر، زادت أسبقته. وإذا لم يتم تحديد شروط ترتيب، سيكون ترتيب الصفوف غير محدد. |
localizationSettings |
إعدادات الأقلمة للتقرير |
maxReportRows |
الحد الأقصى لعدد صفوف بيانات التقرير المطلوب عرضها. إذا لم يتم ضبط القيمة، ستعرض واجهة برمجة التطبيقات أكبر عدد ممكن من الصفوف، بما يصل إلى 100000. القيم المقبولة هي 1-100000، شاملة. القيم الأكبر من 100000 تعرض خطأ. |
timeZone |
منطقة زمنية للتقرير تقبل قيم اسم 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 |
يتم تطبيق معيار الفلتر على السمة المحدّدة. |
حقل الاتحاد operator عامل تشغيل الفلتر الذي سيتم تطبيقه يمكن أن يكون الحقل "operator " واحدًا فقط مما يلي: |
|
matchesAny |
يطابق صفًا إذا كانت قيمته للبُعد المحدّد تقع في إحدى القيم المحدّدة في هذا الشرط. |
SortCondition
اتجاه الترتيب الذي ستسري على إحدى السمات أو المقاييس.
تمثيل JSON |
---|
{ "order": enum ( |
الحقول | |
---|---|
order |
ترتيب الترتيب للسمة أو المقياس |
حقل الاتحاد sort_on يحدد القيم التي يجب الترتيب عليها. يمكن أن يكون الحقل "sort_on " واحدًا فقط مما يلي: |
|
dimension |
الترتيب حسب البُعد المحدَّد. |
metric |
الترتيب حسب المقياس المحدَّد |