- طلب HTTP
- مَعلمات المسار
- نص الطلب
- نص الاستجابة
- نطاقات التفويض
- NetworkReportSpec:
- السمة
- المقياس
- DimensionFilter
- SortCondition
- أمثلة
- جرِّبه الآن
تُنشئ تقرير "شبكة AdMob" استنادًا إلى مواصفات التقرير المقدَّمة. لعرض نتيجة RPC للبث من جهة الخادم. ويتم عرض النتيجة في تسلسل من الردود.
طلب HTTP
POST https://admob.googleapis.com/v1beta/{parent=accounts/*}/networkReport: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": {"microsValue": 6500000}
}
}
},
{
"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.
NetworkReportSpec
مواصفات إنشاء تقرير شبكة AdMob. على سبيل المثال، يمكن أن تظهر مواصفات الحصول على النقرات والأرباح المقدَّرة للبلدان "الولايات المتحدة" و"الصين" فقط على النحو التالي:
{
'dateRange': {
'startDate': {'year': 2021, 'month': 9, 'day': 1},
'endDate': {'year': 2021, 'month': 9, 'day': 30}
},
'dimensions': ['DATE', 'APP', 'COUNTRY'],
'metrics': ['CLICKS', 'ESTIMATED_EARNINGS'],
'dimensionFilters': [
{
'dimension': 'COUNTRY',
'matchesAny': {'values': [{'value': 'US', 'value': 'CN'}]}
}
],
'sortConditions': [
{'dimension':'APP', order: 'ASCENDING'},
{'metric':'CLICKS', order: 'DESCENDING'}
],
'localizationSettings': {
'currencyCode': 'USD',
'languageCode': 'en-US'
}
}
لفهم الأمر بشكل أفضل، يمكنك معالجة المواصفات السابقة مثل لغة الاستعلامات البنيوية (SQL) الزائفة التالية:
SELECT DATE, APP, COUNTRY, CLICKS, ESTIMATED_EARNINGS
FROM NETWORK_REPORT
WHERE DATE >= '2021-09-01' AND DATE <= '2021-09-30'
AND COUNTRY IN ('US', 'CN')
GROUP BY DATE, APP, COUNTRY
ORDER BY APP ASC, CLICKS DESC;
تمثيل 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_UNIT |
المعرّف الفريد للوحدة الإعلانية (على سبيل المثال، "ca-app-pub-1234/1234"). إذا تم تحديد بُعد AD_UNIT، يتم تضمين APP تلقائيًا. |
APP |
المعرّف الفريد لتطبيق متوافق مع الأجهزة الجوّالة (على سبيل المثال، "ca-app-pub-1234~1234"). |
AD_TYPE |
نوع الإعلان (على سبيل المثال، "نص" أو "صورة")، إحدى سمات عرض الإعلان. تحذير: السمة غير متوافقة مع مقاييس AD_REQUESTS وMATCH_RATE وIMPRESSION_RPM. |
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 |
عدد طلبات الإعلان. يجب أن تكون القيمة عددًا صحيحًا. تحذير: المقياس غير متوافق مع السمة AD_TYPE. |
CLICKS |
عدد المرات التي ينقر فيها المستخدم على إعلان. يجب أن تكون القيمة عددًا صحيحًا. |
ESTIMATED_EARNINGS |
الأرباح المقدّرة لناشر AdMob. يتم تحديد وحدة العملة (الدولار الأمريكي أو اليورو أو غير ذلك) الخاصة بمقاييس الأرباح من خلال إعدادات الأقلمة. المبلغ بالمايكرو. على سبيل المثال، سيتم تمثيل 6.50 دولار أمريكي على النحو التالي: 6500000. |
IMPRESSIONS |
إجمالي عدد الإعلانات المعروضة للمستخدمين. يجب أن تكون القيمة عددًا صحيحًا. |
IMPRESSION_CTR |
نسبة النقرات إلى مرات الظهور. القيمة هي قيمة عشرية بدقة مزدوجة (تقريبية). |
IMPRESSION_RPM |
الأرباح المقدَّرة لكل ألف مرة ظهور للإعلان. يجب أن تكون القيمة بالمايكرو. على سبيل المثال، سيتم تمثيل 1.03 دولار أمريكي على النحو التالي: 1030000. يعادل التكلفة الفعلية لكل ألف ظهور في واجهة مستخدم AdMob. تحذير: المقياس غير متوافق مع السمة AD_TYPE. |
MATCHED_REQUESTS |
عدد مرّات عرض الإعلانات استجابةً للطلب. يجب أن تكون القيمة عددًا صحيحًا. |
MATCH_RATE |
نسبة طلبات الإعلان المطابقة مقارنةً بإجمالي طلبات الإعلان. القيمة هي قيمة عشرية بدقة مزدوجة (تقريبية). تحذير: المقياس غير متوافق مع السمة AD_TYPE. |
SHOW_RATE |
نسبة الإعلانات المعروضة مقابل الإعلانات التي تم عرضها، وتُعرف باسم مرات الظهور / الطلبات المطابقة. القيمة هي قيمة عشرية بدقة مزدوجة (تقريبية). |
DimensionFilter
تصف صفوف التقرير المطلوب مطابقتها استنادًا إلى قيم أبعادها.
تمثيل JSON |
---|
{ "dimension": enum ( |
الحقول | |
---|---|
dimension |
يتيح هذا الخيار معيار الفلتر على السمة المحدّدة. |
حقل الاتحاد operator عامل تشغيل الفلتر الذي سيتم تطبيقه. يمكن أن تكون السمة "operator " واحدة فقط مما يلي: |
|
matchesAny |
يطابق صفًا إذا كانت قيمته للسمة المحدّدة تقع في إحدى القيم المحدّدة في هذا الشرط. |
SortCondition
اتجاه الفرز الذي سيتم تطبيقه على سمة أو مقياس.
تمثيل JSON |
---|
{ "order": enum ( |
الحقول | |
---|---|
order |
ترتيب ترتيب السمة أو المقياس |
حقل الاتحاد sort_on تحدد القيم التي يجب الترتيب عليها. يمكن أن تكون السمة "sort_on " واحدة فقط مما يلي: |
|
dimension |
الترتيب حسب السمة المحدّدة |
metric |
الترتيب حسب المقياس المحدَّد. |