Method: customers.generateReachForecast

یک پیش‌بینی دسترسی برای یک ترکیب هدف/محصول معین ایجاد می‌کند.

فهرست خطاهای پرتاب شده: AuthenticationError AuthorizationError FieldError HeaderError داخلی خطا QuotaError RangeError ReachPlanError RequestError

درخواست HTTP

POST https://googleads.googleapis.com/v14/customers/{customerId}:generateReachForecast

URL از دستور GRPC Transcoding استفاده می کند.

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

مولفه های
customerId

string

ضروری. شناسه مشتری.

درخواست بدن

بدنه درخواست حاوی داده هایی با ساختار زیر است:

نمایندگی JSON
{
  "campaignDuration": {
    object (CampaignDuration)
  },
  "cookieFrequencyCapSetting": {
    object (FrequencyCap)
  },
  "targeting": {
    object (Targeting)
  },
  "plannedProducts": [
    {
      object (PlannedProduct)
    }
  ],
  "forecastMetricOptions": {
    object (ForecastMetricOptions)
  },
  "currencyCode": string,
  "cookieFrequencyCap": integer,
  "minEffectiveFrequency": integer,
  "effectiveFrequencyLimit": {
    object (EffectiveFrequencyLimit)
  },
  "customerReachGroup": string
}
زمینه های
campaignDuration

object ( CampaignDuration )

ضروری. مدت زمان کمپین

cookieFrequencyCapSetting

object ( FrequencyCap )

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

این فیلد جایگزین فیلد CookieFrequencyCap منسوخ شده می شود.

targeting

object ( Targeting )

هدف گذاری برای همه محصولات انتخاب شده در ترکیب محصول اعمال شود.

این هدف گذاری برنامه ریزی شده است: جزئیات اجرا ممکن است بر اساس محصول تبلیغاتی متفاوت باشد، با یک متخصص پیاده سازی مشورت کنید.

برای جزئیات بیشتر در مورد اینکه چگونه هدف گذاری روی آنها تأثیر می گذارد، به معیارهای خاص مراجعه کنید.

plannedProducts[]

object ( PlannedProduct )

ضروری. محصولات قابل پیش بینی حداکثر تعداد محصولات برنامه ریزی شده مجاز 15 عدد است.

forecastMetricOptions

object ( ForecastMetricOptions )

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

currencyCode

string

رمز ارز کد ارز سه کاراکتری ISO 4217.

cookieFrequencyCap

integer

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

این فیلد در نسخه 4 منسوخ شده است و در نهایت حذف خواهد شد. به جای آن از cookieFrequencyCapSetting استفاده کنید.

minEffectiveFrequency

integer

حداقل فرکانس مؤثر (تعداد دفعاتی که یک فرد در معرض آگهی قرار گرفته است) برای معیارهای دسترسی گزارش شده [1-10] انتخاب شده است. این روی هدف‌گذاری تأثیر نمی‌گذارد، بلکه فقط بر گزارش‌دهی تأثیر می‌گذارد. اگر مشخص نشده باشد، پیش فرض 1 اعمال می شود.

این فیلد را نمی توان با فیلد effectFrequencyLimit ترکیب کرد.

effectiveFrequencyLimit

object ( EffectiveFrequencyLimit )

بالاترین حداقل فرکانس مؤثر (تعداد دفعاتی که یک فرد در معرض آگهی قرار گرفته است) مقدار [1-10] برای درج در Forecast.effective_frequency_breakdowns. اگر مشخص نشده باشد، Forecast.effective_frequency_breakdowns ارائه نخواهد شد.

مقدار فرکانس مؤثر ارائه شده در اینجا نیز به عنوان حداقل فرکانس مؤثر برای معیارهای دسترسی گزارش شده استفاده خواهد شد.

این فیلد را نمی توان با فیلد minEffectiveFrequency ترکیب کرد.

customerReachGroup

string

نام مشتری که برای آن برنامه ریزی شده است. این یک مقدار تعریف شده توسط کاربر است.

بدن پاسخگو

پیام پاسخ حاوی منحنی دسترسی تولید شده.

در صورت موفقیت آمیز بودن، بدنه پاسخ حاوی داده هایی با ساختار زیر است:

نمایندگی JSON
{
  "onTargetAudienceMetrics": {
    object (OnTargetAudienceMetrics)
  },
  "reachCurve": {
    object (ReachCurve)
  }
}
زمینه های
onTargetAudienceMetrics

object ( OnTargetAudienceMetrics )

ارجاع به مخاطبان هدف برای این منحنی.

reachCurve

object ( ReachCurve )

منحنی دستیابی تولید شده برای ترکیب محصول برنامه ریزی شده.

محدوده مجوز

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

  • https://www.googleapis.com/auth/adwords

برای اطلاعات بیشتر، به نمای کلی OAuth 2.0 مراجعه کنید.

مدت زمان کمپین

مدت زمان کمپین برنامه ریزی شده

نمایندگی JSON
{
  "dateRange": {
    object (DateRange)
  },
  "durationInDays": integer
}
زمینه های
dateRange

object ( DateRange )

محدوده تاریخ کمپین تاریخ ها در قالب yyyy-mm-dd و شامل هستند. تاریخ پایان باید کمتر از 1 سال در آینده باشد و محدوده تاریخ باید <= 92 روز باشد.

این فیلد را نمی توان با فیلد durationInDays ترکیب کرد.

durationInDays

integer

مقدار مدت زمان بر حسب روز

این فیلد را نمی توان با فیلد dateRange ترکیب کرد.

FrequencyCap

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

نمایندگی JSON
{
  "impressions": integer,
  "timeUnit": enum (FrequencyCapTimeUnit)
}
زمینه های
impressions

integer

ضروری. تعداد برداشت‌ها، شامل.

timeUnit

enum ( FrequencyCapTimeUnit )

ضروری. نوع واحد زمان

EffectiveFrequencyLimit

محدودیت فرکانس موثر

نمایندگی JSON
{
  "effectiveFrequencyBreakdownLimit": integer
}
زمینه های
effectiveFrequencyBreakdownLimit

integer

بالاترین مقدار فرکانس مؤثر برای گنجاندن در Forecast.effective_frequency_breakdowns. این فیلد فرکانس های 1-10 را پشتیبانی می کند.

هدف گذاری

هدف گذاری که معیارهای ترافیک برای آن گزارش می شود.

نمایندگی JSON
{
  "plannableLocationIds": [
    string
  ],
  "ageRange": enum (ReachPlanAgeRange),
  "genders": [
    {
      object (GenderInfo)
    }
  ],
  "devices": [
    {
      object (DeviceInfo)
    }
  ],
  "network": enum (ReachPlanNetwork),
  "audienceTargeting": {
    object (AudienceTargeting)
  },
  "plannableLocationId": string
}
زمینه های
plannableLocationIds[]

string

فهرست شناسه‌های مکان قابل برنامه‌ریزی برای هدف قرار دادن با این پیش‌بینی.

اگر بیش از یک شناسه ارائه شده باشد، همه شناسه‌ها باید یک parentCountryId داشته باشند. برنامه ریزی برای بیش از parent_county پشتیبانی نمی شود. شناسه‌های مکان قابل برنامه‌ریزی و parentCountryId آن‌ها را می‌توانید از ReachPlanService.ListPlannableLocations دریافت کنید.

درخواست‌ها باید این فیلد یا plannableLocationId را تنظیم کنند.

ageRange

enum ( ReachPlanAgeRange )

محدوده سنی هدفمند یک مقدار تنظیم نشده معادل هدف قرار دادن تمام سنین است.

genders[]

object ( GenderInfo )

جنسیت های هدفمند یک مقدار تنظیم نشده معادل هدف قرار دادن MALE و FEMALE است.

devices[]

object ( DeviceInfo )

دستگاه های هدفمند اگر مشخص نشده باشد، تمام دستگاه های قابل اجرا را هدف قرار می دهد. دستگاه های قابل اجرا بر اساس محصول و منطقه متفاوت است و می توان آنها را از ReachPlanService.ListPlannableProducts دریافت کرد.

network

enum ( ReachPlanNetwork )

شبکه هدفمند برای محصول تبلیغاتی اگر مشخص نشده باشد، تمام شبکه های قابل اجرا را هدف قرار می دهد. شبکه های قابل اجرا بر اساس محصول و منطقه متفاوت است و می توان آنها را از ReachPlanService.ListPlannableProducts دریافت کرد.

audienceTargeting

object ( AudienceTargeting )

مخاطبان هدف. اگر مشخص نشده باشد، مخاطب خاصی را هدف قرار نمی دهد.

plannableLocationId

string

شناسه مکان انتخاب شده شناسه های مکان قابل برنامه ریزی را می توان از ReachPlanService.ListPlannableLocations دریافت کرد.

درخواست‌ها باید این فیلد یا plannableLocationIds را تنظیم کنند.

این فیلد از نسخه 12 منسوخ شده است و در نسخه بعدی حذف خواهد شد. به جای آن از plannableLocationIds استفاده کنید.

هدف گذاری مخاطب

هدف گذاری مخاطب برای پیش بینی دسترسی.

نمایندگی JSON
{
  "userInterest": [
    {
      object (UserInterestInfo)
    }
  ]
}
زمینه های
userInterest[]

object ( UserInterestInfo )

فهرست مخاطبان بر اساس علایق کاربر که باید مورد هدف قرار گیرند.

محصول برنامه ریزی شده

محصولی که برای دستیابی برنامه ریزی شده است.

نمایندگی JSON
{
  "advancedProductTargeting": {
    object (AdvancedProductTargeting)
  },
  "plannableProductCode": string,
  "budgetMicros": string
}
زمینه های
advancedProductTargeting

object ( AdvancedProductTargeting )

تنظیمات هدف برای محصول انتخاب شده برای فهرست کردن اهداف موجود برای هر محصول از ReachPlanService.ListPlannableProducts استفاده کنید.

plannableProductCode

string

ضروری. محصول انتخاب شده برای برنامه ریزی کد مرتبط با محصول تبلیغاتی (به عنوان مثال: Trueview، Bumper). برای فهرست کردن کدهای محصول قابل برنامه ریزی موجود، از ReachPlanService.ListPlannableProducts استفاده کنید.

budgetMicros

string ( int64 format)

ضروری. حداکثر تخصیص بودجه در میکرو برای محصول انتخابی. مقدار در ارز برنامه ریزی انتخاب شده کد مشخص شده است. به عنوان مثال: 1 000 000 $ = 1 000 000 000 000 میکرو.

AdvancedProductTargeting

تنظیمات هدف گیری پیشرفته برای محصولات

نمایندگی JSON
{

  // Union field advanced_targeting can be only one of the following:
  "youtubeSelectSettings": {
    object (YouTubeSelectSettings)
  }
  // End of list of possible types for union field advanced_targeting.
}
زمینه های
فیلد اتحادیه advanced_targeting . گزینه های هدف گذاری برای این محصول advanced_targeting تنها می تواند یکی از موارد زیر باشد:
youtubeSelectSettings

object ( YouTubeSelectSettings )

تنظیمات برای YouTube هدف گذاری را انتخاب کنید.

YouTubeSelectSettings

درخواست تنظیمات برای YouTube Select Lineups

نمایندگی JSON
{
  "lineupId": string
}
زمینه های
lineupId

string ( int64 format)

صف بندی برای YouTube Select Targeting.

ForecastMetricOptions

معیارهای پیش بینی برای بازگشت را کنترل می کند.

نمایندگی JSON
{
  "includeCoview": boolean
}
زمینه های
includeCoview

boolean

نشان می دهد که آیا معیارهای مشاهده مشترک در پیش بینی پاسخ لحاظ شود یا خیر.

OnTargetAudienceMetrics

معیارهای مخاطب برای محصولات برنامه ریزی شده این معیارها ابعاد هدف گذاری زیر را در نظر می گیرند:

  • محل
  • PlannableAgeRange
  • جنسیت
  • هدف گذاری مخاطب (فقط برای youtubeAudienceSize)
نمایندگی JSON
{
  "youtubeAudienceSize": string,
  "censusAudienceSize": string
}
زمینه های
youtubeAudienceSize

string ( int64 format)

اندازه مخاطب مرجع مطابق با هدف در نظر گرفته شده برای YouTube.

censusAudienceSize

string ( int64 format)

اندازه مخاطب مرجع مطابق با هدف در نظر گرفته شده برای سرشماری.

ReachCurve

منحنی دسترسی برای محصولات برنامه ریزی شده.

نمایندگی JSON
{
  "reachForecasts": [
    {
      object (ReachForecast)
    }
  ]
}
زمینه های
reachForecasts[]

object ( ReachForecast )

همه نقاط روی منحنی دسترسی

ReachForecast

منحنی نقطه در دسترس.

نمایندگی JSON
{
  "costMicros": string,
  "forecast": {
    object (Forecast)
  },
  "plannedProductReachForecasts": [
    {
      object (PlannedProductReachForecast)
    }
  ]
}
زمینه های
costMicros

string ( int64 format)

هزینه در میکرو

forecast

object ( Forecast )

متریک های ترافیکی پیش بینی شده برای این نقطه.

plannedProductReachForecasts[]

object ( PlannedProductReachForecast )

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

پیش بینی

معیارهای ترافیک پیش بینی شده برای محصولات برنامه ریزی شده و هدف گذاری.

نمایندگی JSON
{
  "effectiveFrequencyBreakdowns": [
    {
      object (EffectiveFrequencyBreakdown)
    }
  ],
  "onTargetReach": string,
  "totalReach": string,
  "onTargetImpressions": string,
  "totalImpressions": string,
  "viewableImpressions": string,
  "onTargetCoviewReach": string,
  "totalCoviewReach": string,
  "onTargetCoviewImpressions": string,
  "totalCoviewImpressions": string
}
زمینه های
effectiveFrequencyBreakdowns[]

object ( EffectiveFrequencyBreakdown )

فهرستی از پیش بینی های فرکانس موثر فهرست از 1+ شروع می شود و با مقدار تنظیم شده در GenerateReachForecastRequest.effective_frequency_limit به پایان می رسد. اگر هیچ محدودیت فرکانس مؤثری تنظیم نشده باشد، این لیست خالی خواهد بود.

onTargetReach

string ( int64 format)

تعداد افراد منحصربه‌فرد به حداقل زمان GenerateReachForecastRequest.min_effective_frequency یا GenerateReachForecastRequest.effective_frequency_limit رسیده‌اند که دقیقاً با Targeting مطابقت دارد.

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

totalReach

string ( int64 format)

تعداد کل افراد منحصر به فرد حداقل به بار GenerateReachForecastRequest.min_effective_frequency یا GenerateReachForecastRequest.effective_frequency_limit رسیده است. این شامل افرادی می شود که ممکن است خارج از هدف گذاری مشخص شده باشند.

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

onTargetImpressions

string ( int64 format)

تعداد نمایش‌های تبلیغاتی که دقیقاً با هدف‌گذاری مطابقت دارد.

totalImpressions

string ( int64 format)

تعداد کل نمایش تبلیغات این شامل نمایش‌هایی می‌شود که ممکن است به دلیل اطلاعات ناکافی در مورد کاربرانی که به سیستم وارد شده‌اند، خارج از هدف‌گذاری مشخص‌شده باشد.

viewableImpressions

string ( int64 format)

تعداد دفعاتی که نمایش‌های آگهی قابل مشاهده در نظر گرفته شد. برای اطلاعات بیشتر در مورد اینکه چه چیزی یک آگهی را قابل مشاهده می‌کند و نحوه اندازه‌گیری قابلیت مشاهده، به https://support.google.com/google-ads/answer/7029393 مراجعه کنید.

onTargetCoviewReach

string ( int64 format)

تعداد افراد منحصر به فردی که دقیقاً با هدف گذاری مطابقت دارد از جمله بینندگان مشترک.

totalCoviewReach

string ( int64 format)

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

onTargetCoviewImpressions

string ( int64 format)

تعداد نمایش‌های تبلیغاتی که دقیقاً با هدف منطبق است از جمله بینندگان مشترک.

totalCoviewImpressions

string ( int64 format)

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

EffectiveFrequency Breakdown

تفکیک تعداد افراد منحصر به فرد در یک فرکانس موثر معین

نمایندگی JSON
{
  "effectiveFrequency": integer,
  "onTargetReach": string,
  "totalReach": string,
  "effectiveCoviewReach": string,
  "onTargetEffectiveCoviewReach": string
}
زمینه های
effectiveFrequency

integer

فرکانس موثر [1-10].

onTargetReach

string ( int64 format)

تعداد افراد منحصربه‌فرد به حداقل زمان‌های فرکانس مؤثر رسیده است که دقیقاً با هدف‌گذاری مطابقت دارد.

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

totalReach

string ( int64 format)

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

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

effectiveCoviewReach

string ( int64 format)

تعداد کاربران (از جمله کاربرانی که در حال مشاهده مشترک هستند) برای مقدار فرکانس موثر مرتبط به دست آمده است.

onTargetEffectiveCoviewReach

string ( int64 format)

تعداد کاربران (از جمله کاربرانی که هم‌اکنون مشاهده می‌کنند) برای مقدار فرکانس مؤثر مرتبط در جمعیت‌شناسی طرح مشخص شده به دست آمده است.

PlannedProductReach Forecast

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

نمایندگی JSON
{
  "plannableProductCode": string,
  "costMicros": string,
  "plannedProductForecast": {
    object (PlannedProductForecast)
  }
}
زمینه های
plannableProductCode

string

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

costMicros

string ( int64 format)

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

plannedProductForecast

object ( PlannedProductForecast )

معیارهای ترافیک پیش بینی شده برای این محصول.

پیش بینی محصول برنامه ریزی شده

معیارهای ترافیک پیش بینی شده برای یک محصول برنامه ریزی شده

نمایندگی JSON
{
  "onTargetReach": string,
  "totalReach": string,
  "onTargetImpressions": string,
  "totalImpressions": string,
  "viewableImpressions": string,
  "onTargetCoviewReach": string,
  "totalCoviewReach": string,
  "onTargetCoviewImpressions": string,
  "totalCoviewImpressions": string
}
زمینه های
onTargetReach

string ( int64 format)

تعداد افراد منحصربه‌فردی که دقیقاً با هدف‌گذاری مطابقت دارد.

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

totalReach

string ( int64 format)

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

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

onTargetImpressions

string ( int64 format)

تعداد نمایش‌های تبلیغاتی که دقیقاً با هدف‌گذاری مطابقت دارد.

totalImpressions

string ( int64 format)

تعداد کل نمایش تبلیغات این شامل نمایش‌هایی می‌شود که ممکن است به دلیل اطلاعات ناکافی در مورد کاربرانی که به سیستم وارد شده‌اند، خارج از هدف‌گذاری مشخص‌شده باشد.

viewableImpressions

string ( int64 format)

تعداد دفعاتی که نمایش‌های آگهی قابل مشاهده در نظر گرفته شد. برای اطلاعات بیشتر در مورد اینکه چه چیزی یک آگهی را قابل مشاهده می‌کند و نحوه اندازه‌گیری قابلیت مشاهده، به https://support.google.com/google-ads/answer/7029393 مراجعه کنید.

onTargetCoviewReach

string ( int64 format)

تعداد افراد منحصر به فردی که دقیقاً با هدف گذاری مطابقت دارد از جمله بینندگان مشترک.

totalCoviewReach

string ( int64 format)

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

onTargetCoviewImpressions

string ( int64 format)

تعداد نمایش‌های تبلیغاتی که دقیقاً با هدف منطبق است از جمله بینندگان مشترک.

totalCoviewImpressions

string ( int64 format)

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