Ads Activity Report Alpha API

گزارش فعالیت تبلیغات یک نمای متمرکز از عملکرد تبلیغات شما است. این داده ها، معیارها و ابعاد API گزارش شبکه و API گزارش میانجی و همچنین داده های پیشنهادی را در یک گزارش واحد ترکیب می کند.

Ads Activity Report API پیشرفت‌های بیشتری را از Mediation Report و Network Report API همانطور که در جدول زیر مشاهده می‌کنید ارائه می‌کند:

API گزارش شبکه Mediation Report API API گزارش فعالیت تبلیغات
عملکرد شبکه ✅ ✅ ✅
عملکرد آبشار ✅ ✅
عملکرد مناقصه ✅
میانجی A/B عملکرد آزمایش ✅
گزارش ساعتی ✅
اندازه گزارش 100 هزار 100 هزار 500 هزار

متریک ها، ابعاد و فیلترهای ابعاد

معیارهای زیر علاوه بر بسیاری از معیارهای موجود در Network Report API و Mediation Report API به API گزارش فعالیت تبلیغات اضافه شده است.

متریک توضیحات
BID_REQUEST تعداد درخواست های ارائه شده به منبع آگهی مناقصه.
BIDS_IN_AUCTION تعداد پیشنهادات ارسال شده توسط منبع آگهی که در مزایده مناقصه شرکت کرده است.
WINNING_BIDS تعداد پیشنهاداتی که برنده مزایده مناقصه شدند.

ابعاد جدید زیر در API گزارش فعالیت تبلیغات گنجانده شده است.

بعد توضیحات
هفته تاریخ اولین روز هفته (مطابق با کد زبان ذکر شده در تنظیمات بومی سازی) در قالب YYYYMMDD (به عنوان مثال، "20210701"). درخواست‌ها می‌توانند تنها یکی از ابعاد زمانی DATE، WEEK یا MONTH را مشخص کنند.
ساعت ساعت با فرمت HH در زمان PST. برای مثال، «05» برای ساعت 5 صبح به وقت PST، «13» برای ساعت 13:00 PST. بعد DATE نیز باید در درخواست مشخص شود. زمانی که بعد HOUR مشخص شده باشد حداکثر 28 روز داده برگردانده می شود. تاریخ های شروع محدوده تاریخی که بیش از 28 روز قبل از تاریخ فعلی هستند، خطا را نشان می دهند.
MEDIATION_AB_TEST (نام آزمایش) مشاهده عملکرد با واسطه آزمون A/B. اگر بعد VARIANT مشخص شده باشد، مشخص کردن آن الزامی است.
MEDIATION_AB_TEST_VARIANT (نوع A، نوع B) مشاهده عملکرد با واسطه نوع آزمون A/B.
نام ابعاد در Mediation Report API نام ابعاد در API گزارش فعالیت تبلیغات توضیحات
AD_UNIT 1 AD_UNIT_ID شناسه منحصر به فرد واحد تبلیغات (به عنوان مثال، "123456789").
AD_UNIT_NAME نام واحد تبلیغات.
برنامه 1 APP_ID شناسه منحصر به فرد برنامه تلفن همراه (به عنوان مثال، "1234567890").
APP_NAME نام برنامه.
AD_SOURCE 1 AD_SOURCE_ID شناسه منحصر به فرد منبع آگهی (به عنوان مثال، "1234567890123456789".
AD_SOURCE_NAME نام منبع تبلیغ (به عنوان مثال، "شبکه AdMob").
AD_SOURCE_INSTANCE 1 AD_SOURCE_INSTANCE_ID شناسه منحصربه‌فرد نمونه منبع آگهی (به عنوان مثال، "123456789012").
AD_SOURCE_INSTANCE_NAME نام نمونه منبع تبلیغ (به عنوان مثال، "AdMob (پیش فرض)").
MEDIATION_GROUP 1 MEDIATION_GROUP_ID شناسه منحصر به فرد گروه میانجی (به عنوان مثال، "1234567890").
MEDIATION_GROUP_NAME شناسه منحصر به فرد گروه میانجی (به عنوان مثال، "AdMob (پیش فرض)").

1 : برای اطلاعات بیشتر به Scalars مراجعه کنید.

ابعاد زیر دارای فرمت به روز شده است.

نام ابعاد در Mediation Report API توضیحات در Mediation Report API توضیحات در API گزارش فعالیت تبلیغات
ESTIMATED_EARNINGS درآمد تخمینی ناشر AdMob. واحد ارز (USD، EUR، یا موارد دیگر) معیارهای درآمد توسط تنظیمات محلی سازی برای ارز تعیین می شود. مقدار بر حسب میکرو می باشد. به عنوان مثال، 6.50 دلار به عنوان 6500000 نشان داده می شود.

درآمد تخمینی به ازای هر گروه میانجی و به ازای هر سطح نمونه منبع آگهی پشتیبانی می‌شود که به تاریخ 20 اکتبر 2019 بازمی‌گردد. درآمد تخمینی شخص ثالث برای تاریخ‌های قبل از 20 اکتبر 2019 0 نشان داده می‌شود.

 درآمد تخمینی ناشر AdMob. واحد ارز (USD، EUR، یا موارد دیگر) معیارهای درآمد توسط تنظیمات محلی سازی برای ارز تعیین می شود.
OBSERVED_ECPM میانگین eCPM تخمینی شبکه تبلیغاتی شخص ثالث. واحد ارز (USD، EUR، یا موارد دیگر) معیارهای درآمد توسط تنظیمات محلی سازی برای ارز تعیین می شود. مقدار بر حسب میکرو می باشد. به عنوان مثال، 2.30 دلار به عنوان 2300000 نشان داده می شود.

میانگین eCPM تخمینی برای هر گروه میانجی و هر سطح نمونه منبع تبلیغ پشتیبانی می‌شود که به ۲۰ اکتبر ۲۰۱۹ بازمی‌گردد. میانگین eCPM تخمینی شخص ثالث برای تاریخ‌های قبل از ۲۰ اکتبر ۲۰۱۹ ۰ نشان می‌دهد.

 میانگین eCPM برای همه تبلیغات. واحد ارز (USD، EUR، یا موارد دیگر) معیارهای درآمد توسط تنظیمات محلی سازی برای ارز تعیین می شود.

میانگین eCPM برای هر گروه میانجی و هر سطح نمونه منبع آگهی پشتیبانی می‌شود که به تاریخ 20 اکتبر 2019 بازمی‌گردد. OBSERVED_ECPM 0 را برای تاریخ‌های قبل از 20 اکتبر 2019 نشان می‌دهد.

اسکالرها

ابعاد زیر در Ads Activity Report API به‌روزرسانی شده‌اند تا به جای اشیاء، مقادیر اسکالر باشند. این پاسخ را ساده می کند و پیچیدگی را کاهش می دهد.

ابعادی که در Mediation Report API و Network Report API تحت تاثیر قرار گرفته است:

  • AD_UNIT
  • APP
  • AD_SOURCE
  • AD_SOURCE_INSTANCE
  • MEDIATION_GROUP
نمونه داده های پاسخ گزارش
قالب بعد میانجیگری / شبکه API 
"AD_UNIT": {
   "value":"ca-app-pub-XXXXXXXXXXXXXXXXX/YYYYYYYYYY",
   "displayLabel": "Test ad unit name"
   }
فرمت ابعاد AAR API 
"AD_UNIT_NAME": "Test ad unit name",
"AD_UNIT_ID": "ca-app-pub-XXXXXXXXXXXXXXXXX/YYYYYYYYYY"

گزارش ساعتی

اکنون می‌توانید عملکرد را بر حسب ساعت در AdMob API مشاهده کنید. گزارش ساعتی تا 28 روز در دسترس است.

بعد DATE نیز باید در درخواست برای بازیابی داده های ساعتی مشخص شود. زمانی که بعد HOUR مشخص شده باشد حداکثر 28 روز داده برگردانده می شود. تاریخ های شروع محدوده تاریخی که بیش از 28 روز قبل از تاریخ فعلی هستند، خطا را نشان می دهند.

اندازه گزارش بزرگتر

Ads Activity Report API به شما امکان می دهد در مجموع 500000 ردیف را بازیابی کنید. برای اطلاعات بیشتر، راهنمای سهمیه بندی را ببینید.

درخواست بدهید

برای درخواست این مراحل را دنبال کنید.

حلقه (خط فرمان)

درخواست با استفاده از curl

  1. فایل اسرار مشتری را بارگیری کنید و اعتبارنامه مجوز ایجاد کنید.

    اولین باری که این مرحله را انجام می‌دهید، از شما خواسته می‌شود که درخواست مجوز را در مرورگر خود بپذیرید. قبل از پذیرش، مطمئن شوید که با یک حساب Google وارد سیستم شده اید که به AdMob API دسترسی دارد. برنامه شما مجاز به دسترسی به داده ها از طرف هر حسابی که در حال حاضر وارد شده است خواهد بود.

    برای احراز هویت و مجوز، توصیه می کنیم از oauth2l ، یک ابزار خط فرمان ساده برای کار با Google OAuth 2.0 استفاده کنید. oauth2l را نصب کنید و دستور زیر را اجرا کنید و مسیری به فایل credentials.json که هنگام ثبت برنامه ابری خود دانلود می کنید جایگزین path_to_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
      }
    }
  }
]}