Method: accounts.networkReport.generate

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

درخواست HTTP

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

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

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

پارامترها
parent

string

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

درخواست بدنه

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

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

object ( NetworkReportSpec )

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

بدنه پاسخ

پاسخ استریمینگ برای گزارش شبکه 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 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. به عنوان مثال، مشخصات لازم برای دریافت کلیک‌ها و درآمد تخمینی فقط برای کشورهای «ایالات متحده» و «چین» می‌تواند مانند مثال زیر باشد:

{
  '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": [
    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_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 مکانی که نمایش/کلیک‌های تبلیغ در آن رخ می‌دهد (برای مثال، "ایالات متحده" یا "فرانسه"). این یک بُعد جغرافیایی است.
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

تعداد درخواست‌های تبلیغ. مقدار آن یک عدد صحیح است.

هشدار: این معیار با بُعد AD_TYPE سازگار نیست.

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

درآمد تخمینی به ازای هر هزار نمایش تبلیغ. این مقدار به صورت میکرو است. برای مثال، ۱.۰۳ دلار به صورت ۱۰۳۰۰۰۰ نمایش داده می‌شود. معادل eCPM در رابط کاربری AdMob.

هشدار: این معیار با بُعد AD_TYPE سازگار نیست.

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

نسبت درخواست‌های تبلیغ منطبق بر کل درخواست‌های تبلیغ. این مقدار، یک مقدار اعشاری با دقت دو برابر (تقریبی) است.

هشدار: این معیار با بُعد AD_TYPE سازگار نیست.

SHOW_RATE نسبت تبلیغاتی که نمایش داده می‌شوند به تبلیغاتی که بازگردانده می‌شوند، که به عنوان تعداد نمایش/درخواست‌های منطبق تعریف می‌شود. این مقدار، یک مقدار اعشاری با دقت دو برابر (تقریبی) است.

فیلتر ابعاد

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

نمایش 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 )

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