- طلب 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 تلقائيًا. |
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 |
الترتيب حسب المقياس المحدَّد. |