- درخواست HTTP
- پارامترهای مسیر
- درخواست بدن
- بدن پاسخگو
- محدوده مجوز
- مدت زمان کمپین
- FrequencyCap
- EffectiveFrequencyLimit
- هدف گذاری
- هدف گذاری مخاطب
- محصول برنامه ریزی شده
- AdvancedProductTargeting
- YouTubeSelectSettings
- ForecastMetricOptions
- OnTargetAudienceMetrics
- ReachCurve
- ReachForecast
- پیش بینی
- EffectiveFrequency Breakdown
- PlannedProductReach Forecast
- پیش بینی محصول برنامه ریزی شده
- آن را امتحان کنید!
یک پیشبینی دسترسی برای یک ترکیب هدف/محصول معین ایجاد میکند.
فهرست خطاهای پرتاب شده: AuthenticationError AuthorizationError FieldError HeaderError داخلی خطا QuotaError RangeError ReachPlanError RequestError
درخواست HTTP
POST https://googleads.googleapis.com/v14/customers/{customerId}:generateReachForecast
URL از دستور GRPC Transcoding استفاده می کند.
پارامترهای مسیر
مولفه های | |
---|---|
customerId | ضروری. شناسه مشتری. |
درخواست بدن
بدنه درخواست حاوی داده هایی با ساختار زیر است:
نمایندگی JSON |
---|
{ "campaignDuration": { object ( |
زمینه های | |
---|---|
campaignDuration | ضروری. مدت زمان کمپین |
cookieFrequencyCapSetting | درپوش فرکانس کوکی انتخاب شده برای اعمال به هر محصول برنامه ریزی شده. این معادل محدودیت فرکانسی است که در تبلیغات Google هنگام ایجاد یک کمپین نشان داده میشود، این نشاندهنده حداکثر تعداد دفعاتی است که یک تبلیغ میتواند به همان کاربر در یک بازه زمانی مشخص نشان داده شود. اگر مشخص نشده باشد، یک پیش فرض 0 (بدون درپوش) اعمال می شود. این فیلد جایگزین فیلد CookieFrequencyCap منسوخ شده می شود. |
targeting | هدف گذاری برای همه محصولات انتخاب شده در ترکیب محصول اعمال شود. این هدف گذاری برنامه ریزی شده است: جزئیات اجرا ممکن است بر اساس محصول تبلیغاتی متفاوت باشد، با یک متخصص پیاده سازی مشورت کنید. برای جزئیات بیشتر در مورد اینکه چگونه هدف گذاری روی آنها تأثیر می گذارد، به معیارهای خاص مراجعه کنید. |
plannedProducts[] | ضروری. محصولات قابل پیش بینی حداکثر تعداد محصولات برنامه ریزی شده مجاز 15 عدد است. |
forecastMetricOptions | سنجههای پیشبینی بازگشتی در پاسخ را کنترل میکند. |
currencyCode | رمز ارز کد ارز سه کاراکتری ISO 4217. |
cookieFrequencyCap | درپوش فرکانس کوکی انتخاب شده برای اعمال به هر محصول برنامه ریزی شده. این معادل محدودیت فرکانسی است که در Google Ads هنگام ایجاد یک کمپین نشان داده می شود، این نشان دهنده حداکثر تعداد دفعاتی است که یک تبلیغ می تواند به همان کاربر نشان داده شود. اگر مشخص نشده باشد، هیچ سرپوشی اعمال نمی شود. این فیلد در نسخه 4 منسوخ شده است و در نهایت حذف خواهد شد. به جای آن از cookieFrequencyCapSetting استفاده کنید. |
minEffectiveFrequency | حداقل فرکانس مؤثر (تعداد دفعاتی که یک فرد در معرض آگهی قرار گرفته است) برای معیارهای دسترسی گزارش شده [1-10] انتخاب شده است. این روی هدفگذاری تأثیر نمیگذارد، بلکه فقط بر گزارشدهی تأثیر میگذارد. اگر مشخص نشده باشد، پیش فرض 1 اعمال می شود. این فیلد را نمی توان با فیلد effectFrequencyLimit ترکیب کرد. |
effectiveFrequencyLimit | بالاترین حداقل فرکانس مؤثر (تعداد دفعاتی که یک فرد در معرض آگهی قرار گرفته است) مقدار [1-10] برای درج در Forecast.effective_frequency_breakdowns. اگر مشخص نشده باشد، Forecast.effective_frequency_breakdowns ارائه نخواهد شد. مقدار فرکانس مؤثر ارائه شده در اینجا نیز به عنوان حداقل فرکانس مؤثر برای معیارهای دسترسی گزارش شده استفاده خواهد شد. این فیلد را نمی توان با فیلد minEffectiveFrequency ترکیب کرد. |
customerReachGroup | نام مشتری که برای آن برنامه ریزی شده است. این یک مقدار تعریف شده توسط کاربر است. |
بدن پاسخگو
پیام پاسخ حاوی منحنی دسترسی تولید شده.
در صورت موفقیت آمیز بودن، بدنه پاسخ حاوی داده هایی با ساختار زیر است:
نمایندگی JSON |
---|
{ "onTargetAudienceMetrics": { object ( |
زمینه های | |
---|---|
onTargetAudienceMetrics | ارجاع به مخاطبان هدف برای این منحنی. |
reachCurve | منحنی دستیابی تولید شده برای ترکیب محصول برنامه ریزی شده. |
محدوده مجوز
به محدوده OAuth زیر نیاز دارد:
-
https://www.googleapis.com/auth/adwords
برای اطلاعات بیشتر، به نمای کلی OAuth 2.0 مراجعه کنید.
مدت زمان کمپین
مدت زمان کمپین برنامه ریزی شده
نمایندگی JSON |
---|
{
"dateRange": {
object ( |
زمینه های | |
---|---|
dateRange | محدوده تاریخ کمپین تاریخ ها در قالب yyyy-mm-dd و شامل هستند. تاریخ پایان باید کمتر از 1 سال در آینده باشد و محدوده تاریخ باید <= 92 روز باشد. این فیلد را نمی توان با فیلد durationInDays ترکیب کرد. |
durationInDays | مقدار مدت زمان بر حسب روز این فیلد را نمی توان با فیلد dateRange ترکیب کرد. |
FrequencyCap
قاعده ای که حداکثر تعداد دفعاتی که یک تبلیغ می تواند به کاربر در یک بازه زمانی خاص نشان داده شود را مشخص می کند.
نمایندگی JSON |
---|
{
"impressions": integer,
"timeUnit": enum ( |
زمینه های | |
---|---|
impressions | ضروری. تعداد برداشتها، شامل. |
timeUnit | ضروری. نوع واحد زمان |
EffectiveFrequencyLimit
محدودیت فرکانس موثر
نمایندگی JSON |
---|
{ "effectiveFrequencyBreakdownLimit": integer } |
زمینه های | |
---|---|
effectiveFrequencyBreakdownLimit | بالاترین مقدار فرکانس مؤثر برای گنجاندن در Forecast.effective_frequency_breakdowns. این فیلد فرکانس های 1-10 را پشتیبانی می کند. |
هدف گذاری
هدف گذاری که معیارهای ترافیک برای آن گزارش می شود.
نمایندگی JSON |
---|
{ "plannableLocationIds": [ string ], "ageRange": enum ( |
زمینه های | |
---|---|
plannableLocationIds[] | فهرست شناسههای مکان قابل برنامهریزی برای هدف قرار دادن با این پیشبینی. اگر بیش از یک شناسه ارائه شده باشد، همه شناسهها باید یک درخواستها باید این فیلد یا |
ageRange | محدوده سنی هدفمند یک مقدار تنظیم نشده معادل هدف قرار دادن تمام سنین است. |
genders[] | جنسیت های هدفمند یک مقدار تنظیم نشده معادل هدف قرار دادن MALE و FEMALE است. |
devices[] | دستگاه های هدفمند اگر مشخص نشده باشد، تمام دستگاه های قابل اجرا را هدف قرار می دهد. دستگاه های قابل اجرا بر اساس محصول و منطقه متفاوت است و می توان آنها را از |
network | شبکه هدفمند برای محصول تبلیغاتی اگر مشخص نشده باشد، تمام شبکه های قابل اجرا را هدف قرار می دهد. شبکه های قابل اجرا بر اساس محصول و منطقه متفاوت است و می توان آنها را از |
audienceTargeting | مخاطبان هدف. اگر مشخص نشده باشد، مخاطب خاصی را هدف قرار نمی دهد. |
plannableLocationId | شناسه مکان انتخاب شده شناسه های مکان قابل برنامه ریزی را می توان از درخواستها باید این فیلد یا این فیلد از نسخه 12 منسوخ شده است و در نسخه بعدی حذف خواهد شد. به جای آن از |
هدف گذاری مخاطب
هدف گذاری مخاطب برای پیش بینی دسترسی.
نمایندگی JSON |
---|
{
"userInterest": [
{
object ( |
زمینه های | |
---|---|
userInterest[] | فهرست مخاطبان بر اساس علایق کاربر که باید مورد هدف قرار گیرند. |
محصول برنامه ریزی شده
محصولی که برای دستیابی برنامه ریزی شده است.
نمایندگی JSON |
---|
{
"advancedProductTargeting": {
object ( |
زمینه های | |
---|---|
advancedProductTargeting | تنظیمات هدف برای محصول انتخاب شده برای فهرست کردن اهداف موجود برای هر محصول از |
plannableProductCode | ضروری. محصول انتخاب شده برای برنامه ریزی کد مرتبط با محصول تبلیغاتی (به عنوان مثال: Trueview، Bumper). برای فهرست کردن کدهای محصول قابل برنامه ریزی موجود، از |
budgetMicros | ضروری. حداکثر تخصیص بودجه در میکرو برای محصول انتخابی. مقدار در ارز برنامه ریزی انتخاب شده کد مشخص شده است. به عنوان مثال: 1 000 000 $ = 1 000 000 000 000 میکرو. |
AdvancedProductTargeting
تنظیمات هدف گیری پیشرفته برای محصولات
نمایندگی JSON |
---|
{ // Union field |
زمینه های | |
---|---|
فیلد اتحادیه advanced_targeting . گزینه های هدف گذاری برای این محصول advanced_targeting تنها می تواند یکی از موارد زیر باشد: | |
youtubeSelectSettings | تنظیمات برای YouTube هدف گذاری را انتخاب کنید. |
YouTubeSelectSettings
درخواست تنظیمات برای YouTube Select Lineups
نمایندگی JSON |
---|
{ "lineupId": string } |
زمینه های | |
---|---|
lineupId | صف بندی برای YouTube Select Targeting. |
ForecastMetricOptions
معیارهای پیش بینی برای بازگشت را کنترل می کند.
نمایندگی JSON |
---|
{ "includeCoview": boolean } |
زمینه های | |
---|---|
includeCoview | نشان می دهد که آیا معیارهای مشاهده مشترک در پیش بینی پاسخ لحاظ شود یا خیر. |
OnTargetAudienceMetrics
معیارهای مخاطب برای محصولات برنامه ریزی شده این معیارها ابعاد هدف گذاری زیر را در نظر می گیرند:
- محل
- PlannableAgeRange
- جنسیت
- هدف گذاری مخاطب (فقط برای youtubeAudienceSize)
نمایندگی JSON |
---|
{ "youtubeAudienceSize": string, "censusAudienceSize": string } |
زمینه های | |
---|---|
youtubeAudienceSize | اندازه مخاطب مرجع مطابق با هدف در نظر گرفته شده برای YouTube. |
censusAudienceSize | اندازه مخاطب مرجع مطابق با هدف در نظر گرفته شده برای سرشماری. |
ReachCurve
منحنی دسترسی برای محصولات برنامه ریزی شده.
نمایندگی JSON |
---|
{
"reachForecasts": [
{
object ( |
زمینه های | |
---|---|
reachForecasts[] | همه نقاط روی منحنی دسترسی |
ReachForecast
منحنی نقطه در دسترس.
نمایندگی JSON |
---|
{ "costMicros": string, "forecast": { object ( |
زمینه های | |
---|---|
costMicros | هزینه در میکرو |
forecast | متریک های ترافیکی پیش بینی شده برای این نقطه. |
plannedProductReachForecasts[] | معیارهای تخصیص و ترافیک پیش بینی شده برای هر محصول برنامه ریزی شده در این نقطه از منحنی دسترسی. |
پیش بینی
معیارهای ترافیک پیش بینی شده برای محصولات برنامه ریزی شده و هدف گذاری.
نمایندگی JSON |
---|
{
"effectiveFrequencyBreakdowns": [
{
object ( |
زمینه های | |
---|---|
effectiveFrequencyBreakdowns[] | فهرستی از پیش بینی های فرکانس موثر فهرست از 1+ شروع می شود و با مقدار تنظیم شده در GenerateReachForecastRequest.effective_frequency_limit به پایان می رسد. اگر هیچ محدودیت فرکانس مؤثری تنظیم نشده باشد، این لیست خالی خواهد بود. |
onTargetReach | تعداد افراد منحصربهفرد به حداقل زمان GenerateReachForecastRequest.min_effective_frequency یا GenerateReachForecastRequest.effective_frequency_limit رسیدهاند که دقیقاً با Targeting مطابقت دارد. توجه داشته باشید که برای گزارش دادهها باید به حداقل تعداد افراد منحصربهفرد رسید. اگر حداقل عدد برآورده نشود، مقدار onTargetReach به 0 گرد می شود. |
totalReach | تعداد کل افراد منحصر به فرد حداقل به بار GenerateReachForecastRequest.min_effective_frequency یا GenerateReachForecastRequest.effective_frequency_limit رسیده است. این شامل افرادی می شود که ممکن است خارج از هدف گذاری مشخص شده باشند. توجه داشته باشید که برای گزارش دادهها باید به حداقل تعداد افراد منحصربهفرد رسید. اگر حداقل عدد برآورده نشود، مقدار totalReach به 0 گرد می شود. |
onTargetImpressions | تعداد نمایشهای تبلیغاتی که دقیقاً با هدفگذاری مطابقت دارد. |
totalImpressions | تعداد کل نمایش تبلیغات این شامل نمایشهایی میشود که ممکن است به دلیل اطلاعات ناکافی در مورد کاربرانی که به سیستم وارد شدهاند، خارج از هدفگذاری مشخصشده باشد. |
viewableImpressions | تعداد دفعاتی که نمایشهای آگهی قابل مشاهده در نظر گرفته شد. برای اطلاعات بیشتر در مورد اینکه چه چیزی یک آگهی را قابل مشاهده میکند و نحوه اندازهگیری قابلیت مشاهده، به https://support.google.com/google-ads/answer/7029393 مراجعه کنید. |
onTargetCoviewReach | تعداد افراد منحصر به فردی که دقیقاً با هدف گذاری مطابقت دارد از جمله بینندگان مشترک. |
totalCoviewReach | تعداد افراد منحصربهفرد از جمله بینندگان مشترک. این شامل افرادی می شود که ممکن است خارج از هدف گذاری مشخص شده باشند. |
onTargetCoviewImpressions | تعداد نمایشهای تبلیغاتی که دقیقاً با هدف منطبق است از جمله بینندگان مشترک. |
totalCoviewImpressions | تعداد کل آگهیها از جمله بینندگان مشترک. این شامل نمایشهایی میشود که ممکن است به دلیل اطلاعات ناکافی در مورد کاربرانی که به سیستم وارد شدهاند، خارج از هدفگذاری مشخصشده باشد. |
EffectiveFrequency Breakdown
تفکیک تعداد افراد منحصر به فرد در یک فرکانس موثر معین
نمایندگی JSON |
---|
{ "effectiveFrequency": integer, "onTargetReach": string, "totalReach": string, "effectiveCoviewReach": string, "onTargetEffectiveCoviewReach": string } |
زمینه های | |
---|---|
effectiveFrequency | فرکانس موثر [1-10]. |
onTargetReach | تعداد افراد منحصربهفرد به حداقل زمانهای فرکانس مؤثر رسیده است که دقیقاً با هدفگذاری مطابقت دارد. توجه داشته باشید که برای گزارش دادهها باید به حداقل تعداد افراد منحصربهفرد رسید. اگر حداقل عدد برآورده نشود، مقدار onTargetReach به 0 گرد می شود. |
totalReach | تعداد کل افراد منحصر به فرد حداقل به دفعات فراوانی مؤثر رسیده است. این شامل افرادی می شود که ممکن است خارج از هدف گذاری مشخص شده باشند. توجه داشته باشید که برای گزارش دادهها باید به حداقل تعداد افراد منحصربهفرد رسید. اگر حداقل عدد برآورده نشود، مقدار totalReach به 0 گرد می شود. |
effectiveCoviewReach | تعداد کاربران (از جمله کاربرانی که در حال مشاهده مشترک هستند) برای مقدار فرکانس موثر مرتبط به دست آمده است. |
onTargetEffectiveCoviewReach | تعداد کاربران (از جمله کاربرانی که هماکنون مشاهده میکنند) برای مقدار فرکانس مؤثر مرتبط در جمعیتشناسی طرح مشخص شده به دست آمده است. |
PlannedProductReach Forecast
معیارهای تخصیص و ترافیک پیشبینیشده برای یک محصول خاص در نقطهای از منحنی دسترسی.
نمایندگی JSON |
---|
{
"plannableProductCode": string,
"costMicros": string,
"plannedProductForecast": {
object ( |
زمینه های | |
---|---|
plannableProductCode | محصول انتخاب شده برای برنامه ریزی کدهای محصول بازگردانده شده در مجموعه کدهایی هستند که توسط ListPlannableProducts هنگام استفاده از همان شناسه مکان بازگردانده می شوند. |
costMicros | هزینه در میکرو اگر یک یا چند محصول برنامه ریزی شده به دلیل موجودی محدود نتوانند بودجه را برآورده کنند، ممکن است با تخصیص ورودی محصول متفاوت باشد. |
plannedProductForecast | معیارهای ترافیک پیش بینی شده برای این محصول. |
پیش بینی محصول برنامه ریزی شده
معیارهای ترافیک پیش بینی شده برای یک محصول برنامه ریزی شده
نمایندگی JSON |
---|
{ "onTargetReach": string, "totalReach": string, "onTargetImpressions": string, "totalImpressions": string, "viewableImpressions": string, "onTargetCoviewReach": string, "totalCoviewReach": string, "onTargetCoviewImpressions": string, "totalCoviewImpressions": string } |
زمینه های | |
---|---|
onTargetReach | تعداد افراد منحصربهفردی که دقیقاً با هدفگذاری مطابقت دارد. توجه داشته باشید که برای گزارش دادهها باید به حداقل تعداد افراد منحصربهفرد رسید. اگر حداقل عدد برآورده نشود، مقدار onTargetReach به 0 گرد می شود. |
totalReach | تعداد افراد منحصر به فرد رسیده است. این شامل افرادی می شود که ممکن است خارج از هدف گذاری مشخص شده باشند. توجه داشته باشید که برای گزارش دادهها باید به حداقل تعداد افراد منحصربهفرد رسید. اگر حداقل عدد برآورده نشود، مقدار totalReach به 0 گرد می شود. |
onTargetImpressions | تعداد نمایشهای تبلیغاتی که دقیقاً با هدفگذاری مطابقت دارد. |
totalImpressions | تعداد کل نمایش تبلیغات این شامل نمایشهایی میشود که ممکن است به دلیل اطلاعات ناکافی در مورد کاربرانی که به سیستم وارد شدهاند، خارج از هدفگذاری مشخصشده باشد. |
viewableImpressions | تعداد دفعاتی که نمایشهای آگهی قابل مشاهده در نظر گرفته شد. برای اطلاعات بیشتر در مورد اینکه چه چیزی یک آگهی را قابل مشاهده میکند و نحوه اندازهگیری قابلیت مشاهده، به https://support.google.com/google-ads/answer/7029393 مراجعه کنید. |
onTargetCoviewReach | تعداد افراد منحصر به فردی که دقیقاً با هدف گذاری مطابقت دارد از جمله بینندگان مشترک. |
totalCoviewReach | تعداد افراد منحصربهفرد از جمله بینندگان مشترک. این شامل افرادی می شود که ممکن است خارج از هدف گذاری مشخص شده باشند. |
onTargetCoviewImpressions | تعداد نمایشهای تبلیغاتی که دقیقاً با هدف منطبق است از جمله بینندگان مشترک. |
totalCoviewImpressions | تعداد کل آگهیها از جمله بینندگان مشترک. این شامل نمایشهایی میشود که ممکن است به دلیل اطلاعات ناکافی در مورد کاربرانی که به سیستم وارد شدهاند، خارج از هدفگذاری مشخصشده باشد. |