الإصدار الأولي من تقرير نشاط الإعلانات

تقرير نشاط الإعلانات هو عرض مركزي لأداء إعلاناتك وهي تجمع بين البيانات والمقاييس من واجهة برمجة تطبيقات تقارير الشبكة وواجهة برمجة تطبيقات تقرير التوسّط وكذلك بيانات عروض الأسعار في تقرير واحد موحّد

توفّر واجهة برمجة التطبيقات لتقرير نشاط الإعلانات تحسينات إضافية من ميزة التوسّط الإبلاغ عن واجهة برمجة التطبيقات وواجهة برمجة التطبيقات لتقرير الشبكة كما هو موضّح في الجدول أدناه:

واجهة برمجة تطبيقات تقارير الشبكة واجهة برمجة تطبيقات تقرير التوسّط واجهة برمجة التطبيقات لتقرير نشاط الإعلانات
أداء الشبكة ✅ ✅ ✅
أداء العرض الإعلاني بدون انقطاع ✅ ✅
أداء عروض الأسعار ✅
أداء تجربة أ/ب للتوسّط ✅
تقارير كل ساعة ✅
حجم التقرير 100,000 100,000 500,000

المقاييس والسمات وفلاتر السمات

تمت إضافة المقاييس التالية في Ads Activity Report API في بالإضافة إلى العديد من المقاييس المتوفرة في Network Report API واجهة برمجة تطبيقات تقرير التوسّط

المقياس الوصف
BID_REQUEST عدد الطلبات المقدَّمة إلى مصدر الإعلان المستند إلى عروض الأسعار.
BIDS_IN_AUCTION عدد عروض الأسعار التي أرسلها مصدر الإعلان والتي شاركت في المزادات المستندة إلى عروض الأسعار.
WINNING_BIDS عدد عروض الأسعار التي فازت بأحد المزادات المستندة إلى عروض الأسعار.

يتم تضمين السمات الجديدة التالية في واجهة برمجة التطبيقات لتقرير نشاط الإعلانات.

السمة الوصف
الأسبوع تاريخ أول يوم من الأسبوع (وفقًا للغة مذكور في إعدادات الترجمة) بالتنسيق YYYYMMDD (لـ على سبيل المثال، "20210701"). يمكن أن تحدد الطلبات حقلاً واحدًا فقط من DATE أو WEEK أو MONTH الوقت.
الساعة الساعة بتنسيق HH بتوقيت المحيط الهادئ. على سبيل المثال: "05" للساعة 5 صباحًا بتوقيت المحيط الهادئ، "13" للساعة 1 مساءً بتوقيت المحيط الهادئ. يجب أيضًا تحديد بُعد DATE في الطلب. حاسمة يتم عرض 28 يومًا من البيانات بحد أقصى عند تحديد البُعد AREA. تواريخ بدء النطاق الزمني التي تسبق التاريخ الحالي بأكثر من 28 يومًا بإرجاع خطأ.
MEDIATION_AB_TEST (اسم التجربة) عرض مستوى الأداء حسب اختبار أ/ب للتوسّط. يلزم تحديد ذلك إذا تم تحديد بُعد VARIANT.
MEDIATION_AB_TEST_VARIANT (السعر المتغير "أ"، الصيغة "ب") عرض مستوى الأداء حسب صيغة اختبار أ/ب للتوسّط.
اسم البُعد في واجهة برمجة تطبيقات تقرير التوسّط اسم السمة في واجهة برمجة التطبيقات لتقرير نشاط الإعلانات الوصف
الوحدة الإعلانية1 AD_UNIT_ID المعرّف الفريد للوحدة الإعلانية (على سبيل المثال، "123456789").
AD_UNIT_NAME اسم الوحدة الإعلانية.
التطبيق1 APP_ID المعرّف الفريد لتطبيق الأجهزة الجوّالة (على سبيل المثال، "1234567890").
APP_NAME اسم التطبيق
AD_SOURCE1 AD_SOURCE_ID المعرّف الفريد لمصدر الإعلان (مثل "1234567890123456789".
AD_SOURCE_NAME اسم مصدر الإعلان (مثل "شبكة AdMob").
AD_SOURCE_INSTANCE1 AD_SOURCE_INSTANCE_ID المعرّف الفريد لمثيل مصدر الإعلان (مثل "123456789012").
AD_SOURCE_INSTANCE_NAME اسم مثيل مصدر الإعلان (مثل "AdMob (تلقائي)").
MEDIATION_GROUP1 MEDIATION_GROUP_ID المعرّف الفريد لمجموعة التوسّط (على سبيل المثال، "1234567890").
MEDIATION_GROUP_NAME المعرّف الفريد لمجموعة التوسّط (على سبيل المثال، "AdMob (تلقائي)").

1: يُرجى الاطّلاع على Scalars للحصول على معلومات إضافية.

تم تعديل تنسيق السمات التالية.

اسم البُعد في واجهة برمجة تطبيقات تقرير التوسّط الوصف في واجهة برمجة تطبيقات تقرير التوسّط الوصف في واجهة برمجة التطبيقات لتقرير نشاط الإعلانات
ESTIMATED_EARNINGS الأرباح المقدّرة لناشر AdMob. تستخدم وحدة العملة (USD، اليورو أو غير ذلك) من مقاييس الأرباح يتم تحديدها حسب الترجمة لإعداد العملة. يكون المبلغ بالمايكرو. على سبيل المثال، 6.50 دولارات ستكون يمثلها 6500000.

الأرباح المقدّرة لكل مجموعة توسّط ولكل مستوى مثيل لمصدر إعلان يعود تاريخها إلى 20 تشرين الأول (أكتوبر) 2019. ستثمر الأرباح المقدّرة من الطرف الثالث وإظهار القيمة 0 للتواريخ التي تسبق 20 تشرين الأول (أكتوبر) 2019.

الأرباح المقدّرة لناشر AdMob. تستخدم وحدة العملة (USD، اليورو أو غير ذلك) من مقاييس الأرباح يتم تحديدها حسب الترجمة لإعداد العملة.
OBSERVED_ECPM متوسّط التكلفة الفعلية المقدّرة لكلّ ألف ظهور على شبكة الإعلانات التابعة لجهات خارجية وحدة العملة (بالدولار الأمريكي أو اليورو أو غير ذلك) يتم تحديد مقاييس الأرباح وفقًا للأقلمة. لإعداد العملة. يكون المبلغ بالمايكرو. على سبيل المثال، يجب أن تكون 2.30 دولار يمثلها 2300000.

المتوسط المقدَّر للتكلفة الفعلية لكل ألف ظهور لكل مجموعة توسّط ولكل مستوى مثيل لمصدر الإعلان يعود تاريخها إلى 20 تشرين الأول (أكتوبر) 2019. المتوسط المقدَّر التابع لجهة خارجية ستعرض التكلفة الفعلية لكل ألف ظهور القيمة 0 للتواريخ التي تسبق 20 تشرين الأول (أكتوبر) 2019.

متوسط التكلفة الفعلية لكل ألف ظهور لجميع الإعلانات. وحدة العملة (دولار أمريكي أو يورو أو غير ذلك) يتم تحديد مقاييس الأرباح من خلال إعداد الأقلمة للعملة.

متوسّط التكلفة الفعلية لكلّ ألف ظهور لكلّ مجموعة توسّط ومستوى مثيل مصدر الإعلان هو يعود تاريخها إلى 20 تشرين الأول (أكتوبر) 2019. ستعرض OBSERVED_ECPM القيمة 0 للتواريخ قبل 20 تشرين الأول (أكتوبر) 2019.

Scalars

تم تعديل السمات التالية في واجهة برمجة التطبيقات لتقرير النشاط الإعلاني القيم العددية بدلاً من الكائنات. سيؤدي هذا إلى تبسيط الاستجابة وتقليل والتعقيد.

السمات المتأثرة في Mediation Report API وNetwork Report API:

  • AD_UNIT
  • APP
  • AD_SOURCE
  • AD_SOURCE_INSTANCE
  • MEDIATION_GROUP
نموذج بيانات الاستجابة للتقرير
تنسيق سمة واجهة برمجة تطبيقات الشبكة أو التوسّط 
"AD_UNIT": {
   "value":"ca-app-pub-XXXXXXXXXXXXXXXXX/YYYYYYYYYY",
   "displayLabel": "Test ad unit name"
   }
تنسيق سمة واجهة برمجة التطبيقات AAR 
"AD_UNIT_NAME": "Test ad unit name",
"AD_UNIT_ID": "ca-app-pub-XXXXXXXXXXXXXXXXX/YYYYYYYYYY"

تقارير كل ساعة

يمكنك الآن عرض الأداء حسب الساعة في واجهة برمجة تطبيقات AdMob. إعداد التقارير كل ساعة متاحة لمدة تصل إلى 28 يومًا

يجب أيضًا تحديد البُعد DATE في الطلب لاسترداد كل ساعة. البيانات. يتم عرض 28 يومًا من البيانات بحد أقصى عندما يكون بُعد PERSON المحددة. تواريخ بدء النطاق الزمني أكبر من 28 يومًا قبل بنتائج التاريخ الحالي خطأ.

حجم تقرير أكبر

تسمح لك واجهة برمجة التطبيقات لتقرير نشاط الإعلانات باسترداد إجمالي 500,000 صف. بالنسبة معلومات إضافية، راجِع دليل عروض الأسعار التقديرية.

تقديم طلب

اتّبِع الخطوات التالية لتقديم طلب.

curl (سطر الأوامر)

الطلبات باستخدام ضفيرة

  1. حمِّل ملف أسرار العميل وأنشِئ بيانات اعتماد التفويض.

    سيُطلب منك في المرة الأولى التي تُجري فيها هذه الخطوة قبول طلب التفويض في متصفحك. قبل القبول، تأكد من أنك سجّلت الدخول باستخدام حساب Google لديه إمكانية الوصول إلى واجهة برمجة تطبيقات AdMob. المصرّح له بالوصول إلى البيانات نيابةً عن تم تسجيل الدخول إلى حساب مسجِّل الدخول إليه حاليًا.

    للمصادقة والترخيص، نوصي باستخدام oauth2l، وهي أداة بسيطة سطر أوامر تعمل مع Google OAuth 2.0. تثبيت oauth2l وتشغيل الأمر أدناه، مع استبدال path_to_credentials_json بمسار إلى ملف credentials.json يمكنك تنزيله عند تسجيل تطبيق السحابة الإلكترونية. عند التشغيل لأول مرة، يوجهك الأمر خلال مسار تفويض OAuth 2.0. وتتم بعد ذلك إعادة تحميل الرمز المميّز. تلقائيًا.

    ~/go/bin/oauth2l header --json path_to_credentials_json \
        https://www.googleapis.com/auth/admob.readonly

  2. إنشاء تقرير نشاط إعلاني

    curl -X POST https://admob.googleapis.com/v1alpha/accounts/pub-XXXXXXXXXXXXXXXX/adsActivityReport:generate \
     -H "Content-Type: application/json" \
     -H "$(~/go/bin/oauth2l header --json path_to_credentials_json https://www.googleapis.com/auth/admob.readonly)"  --data @- << EOF
      {
        "report_spec": {
        "date_range": {
          "start_date": {"year": 2023, "month": 1, "day": 1},
          "end_date": {"year": 2023, "month": 1, "day": 2}
        },
        "dimensions": ["DATE", "HOUR", "MEDIATION_AB_TEST", "VARIANT", "AD_SOURCE_ID", "AD_SOURCE_NAME"],
        "metrics": ["CLICKS", "BID_REQUEST","WINNING_BIDS", "IMPRESSIONS", "ESTIMATED_EARNINGS" ],
        "dimension_filters": [{"dimension": "COUNTRY", "matches_any": {"values": ["US"]}}],
        "sort_conditions": [{"metric":"CLICKS", "order": "DESCENDING"}],
        "localization_settings": {"currency_code": "USD", "language_code": "en-US"}
        }
      }
EOF

    نموذج الرد:

    {
"rows": [
  {
    "dimensionValues": {
      "DATE": {
        "value": "20221102"
      },
      "HOUR": {
        "value": "23"
      },
      "MEDIATION_AB_TEST": {
        "value": "Mediation AB Test"
      },
      "VARIANT": {
        "value": "Variant A"
      },
      "AD_SOURCE_ID": {
        "value": "5450213213286189855"
      },
      "AD_SOURCE_NAME": {
        "value": "AdMob Network"
      }
    },
    "metricValues": {
      "CLICKS": {
        "doubleValue": 0
      },
      "BID_REQUEST": {
        "integerValue": "27"
      },
      "WINNING_BIDS": {
        "doubleValue": 0.1111111111111111
      },
      "IMPRESSIONS": {
        "integerValue": "2"
      },
      "ESTIMATED_EARNINGS": {
        "doubleValue": 0
      }
    }
  },
{
    "dimensionValues": {
      "DATE": {
        "value": "20221102"
      },
      "HOUR": {
        "value": "23"
      },
      "MEDIATION_AB_TEST": {
        "value": "Mediation AB Test"
      },
      "VARIANT": {
        "value": "Variant B"
      },
      "AD_SOURCE_ID": {
        "value": "5450213213286189855"
      },
      "AD_SOURCE_NAME": {
        "value": "AdMob Network"
      }
    },
    "metricValues": {
      "CLICKS": {
        "doubleValue": 1
      },
      "BID_REQUEST": {
        "integerValue": "6"
      },
      "WINNING_BIDS": {
        "doubleValue": 1
      },
      "IMPRESSIONS": {
        "integerValue": "3"
      },
      "ESTIMATED_EARNINGS": {
        "doubleValue": 0.000427519
      }
    }
  }
]}