Method: accounts.mediationReport.generate

یک گزارش میانجیگری AdMob بر اساس مشخصات گزارش ارائه شده تولید می‌کند. نتیجه یک RPC استریمینگ سمت سرور را برمی‌گرداند. نتیجه به صورت دنباله‌ای از پاسخ‌ها برگردانده می‌شود.

درخواست HTTP

POST https://admob.googleapis.com/v1/{parent=accounts/*}/mediationReport:generate

این URL از سینتکس Transcoding در gRPC استفاده می‌کند.

پارامترهای مسیر

پارامترها
parent

string

نام منبع حسابی که گزارش برای آن تولید می‌شود. مثال: accounts/pub-9876543210987654

درخواست بدنه

بدنه درخواست شامل داده‌هایی با ساختار زیر است:

نمایش JSON 
{
  "reportSpec": {
    object (MediationReportSpec)
  }
}
فیلدها
reportSpec

object ( MediationReportSpec )

مشخصات گزارش شبکه.

بدنه پاسخ

پاسخ استریمینگ برای گزارش AdMob Mediation که در آن اولین پاسخ شامل سربرگ گزارش، سپس جریانی از پاسخ‌های ردیفی و در نهایت یک پاورقی به عنوان آخرین پیام پاسخ است.

برای مثال:

[{
  "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 can be only one of the following:
  "header": {
    object (ReportHeader)
  },
  "row": {
    object (ReportRow)
  },
  "footer": {
    object (ReportFooter)
  }
  // End of list of possible types for union field payload.
}
فیلدها
payload فیلد Union. هر پیام پاسخ جریان شامل یک نوع بار مفید است. payload فقط می‌تواند یکی از موارد زیر باشد:
header

object ( ReportHeader )

تنظیمات تولید گزارش که محتوای گزارش، مانند محدوده تاریخ گزارش و تنظیمات محلی‌سازی را توصیف می‌کند.

row

object ( ReportRow )

داده‌های گزارش واقعی

footer

object ( ReportFooter )

اطلاعات تکمیلی در مورد گزارش تولید شده، مانند هشدارها در مورد داده‌ها.

دامنه‌های مجوز

به یکی از حوزه‌های OAuth زیر نیاز دارد:

  • https://www.googleapis.com/auth/admob.readonly
  • https://www.googleapis.com/auth/admob.report

برای اطلاعات بیشتر، بهOAuth 2.0 Overview .

مشخصات گزارش میانجیگری

مشخصات لازم برای تولید گزارش میانجیگری AdMob. به عنوان مثال، مشخصات لازم برای دریافت ECPM مشاهده شده به تفکیک منبع تبلیغ و برنامه برای کشورهای «ایالات متحده» و «چین» می‌تواند مانند مثال زیر باشد:

{
  "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": [
    enum (Dimension)
  ],
  "metrics": [
    enum (Metric)
  ],
  "dimensionFilters": [
    {
      object (DimensionFilter)
    }
  ],
  "sortConditions": [
    {
      object (SortCondition)
    }
  ],
  "localizationSettings": {
    object (LocalizationSettings)
  },
  "maxReportRows": integer,
  "timeZone": string
}
فیلدها
dateRange

object ( DateRange )

محدوده تاریخی که گزارش برای آن تولید می‌شود.

dimensions[]

enum ( Dimension )

فهرست ابعاد گزارش. ترکیب مقادیر این ابعاد، ردیف گزارش را تعیین می‌کند. اگر هیچ بعدی مشخص نشده باشد، گزارش یک ردیف از معیارهای درخواستی را برای کل حساب برمی‌گرداند.

metrics[]

enum ( Metric )

فهرست معیارهای گزارش. یک گزارش باید حداقل یک معیار را مشخص کند.

dimensionFilters[]

object ( DimensionFilter )

توضیح می‌دهد که کدام ردیف‌های گزارش بر اساس مقادیر بُعدشان باید مطابقت داده شوند.

sortConditions[]

object ( SortCondition )

مرتب‌سازی ردیف‌های گزارش را شرح می‌دهد. ترتیب شرط در لیست، اولویت آن را مشخص می‌کند؛ هرچه شرط قبلی‌تر باشد، اولویت آن بالاتر است. اگر هیچ شرط مرتب‌سازی مشخص نشده باشد، ترتیب ردیف تعریف نشده است.

localizationSettings

object ( LocalizationSettings )

تنظیمات محلی‌سازی گزارش

maxReportRows

integer

حداکثر تعداد ردیف‌های داده‌های گزارش برای بازگشت. اگر مقداری تنظیم نشود، API تا حد امکان ردیف‌ها را برمی‌گرداند، تا سقف ۱۰۰۰۰۰. مقادیر قابل قبول ۱-۱۰۰۰۰۰ هستند. مقادیر بزرگتر از ۱۰۰۰۰۰ خطا برمی‌گردانند.

timeZone

string

یک منطقه زمانی گزارش. مقادیر نام IANA TZ مانند "America/Los_Angeles" را می‌پذیرد. اگر هیچ منطقه زمانی تعریف نشده باشد، پیش‌فرض حساب اعمال می‌شود. مقدار پیش‌فرض را با اقدام دریافت حساب بررسی کنید.

هشدار: در حال حاضر تنها مقدار پشتیبانی‌شده «America/Los_Angeles» است.

ابعاد

ابعاد گزارش میانجیگری. ابعاد، ویژگی‌های داده‌ای هستند که برای تجزیه یا اصلاح اندازه‌گیری‌های کمی (معیارها) بر اساس ویژگی‌های خاص، مانند قالب تبلیغ یا پلتفرمی که تبلیغ در آن مشاهده شده است، استفاده می‌شوند.

انوم‌ها
DIMENSION_UNSPECIFIED مقدار پیش‌فرض برای فیلد تنظیم نشده. استفاده نکنید.
DATE یک تاریخ با فرمت YYYYMMDD (برای مثال، "20210701"). درخواست‌ها می‌توانند حداکثر یک بُعد زمانی را مشخص کنند.
MONTH یک ماه با فرمت YYYYMM (برای مثال، "202107"). درخواست‌ها می‌توانند حداکثر یک بُعد زمانی را مشخص کنند.
WEEK تاریخ اولین روز هفته با فرمت YYYYMMDD (برای مثال، "20210701"). درخواست‌ها می‌توانند حداکثر یک بُعد زمانی را مشخص کنند.
AD_SOURCE شناسه منحصر به فرد منبع تبلیغ (برای مثال، "5450213213286189855" و "AdMob Network" به عنوان مقدار برچسب).
AD_SOURCE_INSTANCE شناسه منحصر به فرد نمونه منبع تبلیغ (برای مثال، "ca-app-pub-1234:asi:5678" و "AdMob (default)" به عنوان مقدار برچسب).
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 (default)" به عنوان مقدار برچسب).
COUNTRY کد کشور CLDR مکانی که نمایش/کلیک‌های تبلیغ در آن رخ می‌دهد (برای مثال، "ایالات متحده" یا "فرانسه"). این یک بُعد جغرافیایی است.
FORMAT قالب واحد تبلیغاتی (برای مثال، «بنر»، «بومی»)، بُعد ارائه تبلیغ.
PLATFORM پلتفرم سیستم عامل موبایل برنامه (برای مثال، "اندروید" یا "آی‌او‌اس").
MOBILE_OS_VERSION نسخه سیستم عامل موبایل، مثلاً «iOS 13.5.1».
GMA_SDK_VERSION نسخه GMA SDK، مثلاً "iOS 7.62.0".
APP_VERSION_NAME برای اندروید، نام نسخه برنامه را می‌توان در versionName در PackageInfo یافت. برای iOS، نام نسخه برنامه را می‌توان در CFBundleShortVersionString یافت.
SERVING_RESTRICTION حالت محدودسازی برای نمایش تبلیغات (مثلاً «تبلیغات شخصی‌سازی‌نشده»).

متریک

معیارهای گزارش میانجیگری. معیارها، اندازه‌گیری‌های کمی هستند که نشان می‌دهند کسب‌وکار ناشر چگونه عمل می‌کند. آن‌ها از رویدادهای تبلیغاتی منفرد جمع‌آوری شده و بر اساس ابعاد گزارش گروه‌بندی می‌شوند. مقدار معیار یا عدد صحیح است یا اعشاری (بدون گرد کردن).

انوم‌ها
METRIC_UNSPECIFIED مقدار پیش‌فرض برای فیلد تنظیم نشده. استفاده نکنید.
AD_REQUESTS تعداد درخواست‌ها. مقدار آن یک عدد صحیح است.
CLICKS تعداد دفعاتی که کاربر روی یک تبلیغ کلیک می‌کند. مقدار آن یک عدد صحیح است.
ESTIMATED_EARNINGS

درآمد تخمینی ناشر AdMob. واحد ارز (USD، EUR یا سایر) معیارهای درآمد توسط تنظیمات محلی‌سازی ارز تعیین می‌شود. مبلغ به صورت میکرو است. به عنوان مثال، 6.50 دلار به صورت 6500000 نمایش داده می‌شود.

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

IMPRESSIONS تعداد کل تبلیغات نمایش داده شده به کاربران. مقدار آن یک عدد صحیح است.
IMPRESSION_CTR نسبت کلیک‌ها به تعداد نمایش‌ها. این مقدار، یک مقدار اعشاری با دقت دو برابر (تقریبی) است.
MATCHED_REQUESTS تعداد دفعاتی که تبلیغات در پاسخ به یک درخواست برگردانده می‌شوند. مقدار آن یک عدد صحیح است.
MATCH_RATE نسبت درخواست‌های تبلیغ منطبق بر کل درخواست‌های تبلیغ. این مقدار، یک مقدار اعشاری با دقت دو برابر (تقریبی) است.
OBSERVED_ECPM

میانگین تخمینی eCPM شبکه تبلیغاتی شخص ثالث. واحد پول (دلار آمریکا، یورو یا سایر) معیارهای درآمد با تنظیم محلی‌سازی ارز تعیین می‌شود. مبلغ به صورت میکرو است. برای مثال، ۲.۳۰ دلار به صورت ۲۳۰۰۰۰۰ نمایش داده می‌شود.

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

فیلتر ابعاد

توضیح می‌دهد که کدام ردیف‌های گزارش بر اساس مقادیر بُعدشان باید مطابقت داده شوند.

نمایش JSON 
{
  "dimension": enum (Dimension),

  // Union field operator can be only one of the following:
  "matchesAny": {
    object (StringList)
  }
  // End of list of possible types for union field operator.
}
فیلدها
dimension

enum ( Dimension )

معیار فیلتر را روی بُعد مشخص شده اعمال می‌کند.

operator فیلد اتحادیه. عملگر فیلتر که باید اعمال شود. operator می‌تواند فقط یکی از موارد زیر باشد:
matchesAny

object ( StringList )

با سطری تطبیق می‌یابد که مقدار آن برای بُعد مشخص‌شده، در یکی از مقادیر مشخص‌شده در این شرط باشد.

شرط مرتب‌سازی

جهت مرتب‌سازی که باید روی یک بُعد یا یک متریک اعمال شود.

نمایش JSON 
{
  "order": enum (SortOrder),

  // Union field sort_on can be only one of the following:
  "dimension": enum (Dimension),
  "metric": enum (Metric)
  // End of list of possible types for union field sort_on.
}
فیلدها
order

enum ( SortOrder )

ترتیب مرتب‌سازی بُعد یا متریک.

فیلد یونیون sort_on . مشخص می‌کند که کدام مقادیر باید بر اساس آن مرتب شوند. sort_on فقط می‌تواند یکی از موارد زیر باشد:
dimension

enum ( Dimension )

بر اساس ابعاد مشخص شده مرتب کنید.

metric

enum ( Metric )

بر اساس معیار مشخص شده مرتب کنید.