Method: customers.generateReachForecast

יוצרות תחזית של פוטנציאל החשיפה לתמהיל נתון של טירגוט / מוצרים.

רשימת שגיאות שקרו: AuthenticationError AuthorizationError FieldError HeaderError InternalError QuotaError RangeError ReachPlanError RequestError

בקשת HTTP

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

בכתובת ה-URL נעשה שימוש בתחביר המרת קידוד של gRPC.

פרמטרים של נתיב

פרמטרים
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)

מכסת התדירות שנבחרה של קובצי cookie תחול על כל מוצר מתוכנן. היא מקבילה למכסת התדירות שנחשפה ב-Google Ads בזמן יצירת הקמפיין. היא מייצגת את מספר הפעמים המקסימלי שהמודעה יכולה להופיע בפני אותו משתמש במהלך פרק זמן מוגדר. אם לא מגדירים ערך, המערכת מחילה את ערך ברירת המחדל 0 (ללא הגבלה).

השדה הזה מחליף את השדה cookieFrequencyCap שהוצא משימוש.
targeting

object (Targeting)

הטירגוט שיחול על כל המוצרים שנבחרו בתמהיל המוצרים.

זהו טירגוט מתוכנן: פרטי הביצוע עשויים להשתנות בהתאם למוצר הפרסום, יש להתייעץ עם מומחה הטמעה.

כדי לראות איך הטירגוט משפיע עליהם, אפשר לעיין במדדים ספציפיים.
plannedProducts[]

object (PlannedProduct)

חובה. המוצרים שייכללו בתחזית. המספר המקסימלי של מוצרים מתוכננים הוא 15.
forecastMetricOptions

object (ForecastMetricOptions)

שליטה במדדי התחזית שמוחזרים בתגובה.
currencyCode

string

קוד המטבע. קוד מטבע בן שלושה תווים לפי תקן ISO 4217.
cookieFrequencyCap

integer

מכסת התדירות שנבחרה של קובצי cookie תחול על כל מוצר מתוכנן. היא מקבילה למכסת התדירות שנחשפה ב-Google Ads בזמן יצירת הקמפיין. היא מייצגת את מספר הפעמים המקסימלי שאפשר להציג מודעה לאותו משתמש. אם המדיניות לא מוגדרת, לא תחול מכסה.

השדה הזה הוצא משימוש בגרסה 4 ובסופו של דבר הוא יוסר. במקום זאת, אפשר להשתמש בקובץ cookieFrequencyCapSetting.
minEffectiveFrequency

integer

התדירות האפקטיבית המינימלית שנבחרה (מספר הפעמים שמשתמש נחשף למודעה) עבור מדדי היקף החשיפה המדווחים [1-10]. הפעולה הזו לא תשפיע על הטירגוט, אלא רק על הדיווח. אם לא מציינים שום ערך, המערכת מחילה את ברירת המחדל של הערך 1.

לא ניתן לשלב את השדה הזה עם השדה generateFrequencyLimit.
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.

CampaignDuration

משך הזמן של קמפיין מתוכנן.

ייצוג JSON 
{
  "dateRange": {
    object (DateRange)
  },
  "durationInDays": integer
}
שדות
dateRange

object (DateRange)

טווח התאריכים של הקמפיין. התאריכים מופיעים בפורמט yyyy-mm-dd וכוללים את התאריכים. תאריך הסיום חייב להיות קטן משנה אחת בעתיד וטווח התאריכים חייב להיות <= 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. אפשר לקבל ב-ReachPlanService.ListPlannableLocations את מזהי המיקומים הניתנים לתכנון ואת parentCountryId שלהם.

הבקשות צריכות להגדיר את השדה הזה או plannableLocationId.
ageRange

enum (ReachPlanAgeRange)

טווח גילאים מטורגט. ערך לא מוגדר מקביל לטירגוט לכל הגילאים.
genders[]

object (GenderInfo)

מגדרים מטורגטים. ערך לא מוגדר מקביל למיקוד לMALE ולנקבה.
devices[]

object (DeviceInfo)

מכשירים מטורגטים. אם לא מגדירים טירגוט לכל המכשירים הרלוונטיים. המכשירים הרלוונטיים משתנים בהתאם למוצר ולאזור וניתן להשיג אותם ב-ReachPlanService.ListPlannableProducts.
network

enum (ReachPlanNetwork)

רשת שניתן לטרגט עבור מוצר המודעה. אם לא מציינים שום אפשרות, הטירגוט יטרגט את כל הרשתות הרלוונטיות. הרשתות הרלוונטיות משתנות לפי מוצר ואזור וניתן להשיג אותן ברשת ReachPlanService.ListPlannableProducts.
audienceTargeting

object (AudienceTargeting)

קהלי יעד. אם לא מציינים שום אפשרות, המערכת לא תטרגט קהל ספציפי.
plannableLocationId

string

המזהה של המיקום שנבחר. ניתן לקבל מזהי מיקומים שניתנים לתכנון בכתובת ReachPlanService.ListPlannableLocations.

הבקשות צריכות להגדיר את השדה הזה או plannableLocationIds.

השדה הזה הוצא משימוש החל מ-V12 ויוסר בגרסה עתידית. במקום זאת, השתמשו ב-plannableLocationIds.

AudienceTargeting

טירגוט לפי קהל לצורך תחזית פוטנציאל החשיפה.

ייצוג JSON 
{
  "userInterest": [
    {
      object (UserInterestInfo)
    }
  ]
}
שדות
userInterest[]

object (UserInterestInfo)

רשימת קהלים לטירגוט לפי תחומי עניין של משתמשים.

PlannedProduct

מוצר שאנחנו מתכננים להגדיל את פוטנציאל החשיפה שלו.

ייצוג JSON 
{
  "advancedProductTargeting": {
    object (AdvancedProductTargeting)
  },
  "plannableProductCode": string,
  "budgetMicros": string
}
שדות
advancedProductTargeting

object (AdvancedProductTargeting)

הגדרות הטירגוט של המוצר שנבחר. כדי להציג את אפשרויות הטירגוט הזמינות לכל מוצר, צריך להשתמש במאפיין ReachPlanService.ListPlannableProducts.
plannableProductCode

string

חובה. המוצר שנבחר לתכנון. הקוד שמשויך למוצר המודעה (לדוגמה: Trueview או באמפר). כדי לציין את קודי המוצרים הזמינים שניתנים לתכנון, משתמשים ב-ReachPlanService.ListPlannableProducts.
budgetMicros

string (int64 format)

חובה. הקצאת תקציב מקסימלית ב-Micros למוצר שנבחר. הערך צוין בקוד המטבע לתכנון שנבחר. לדוגמה: 1 000 000$ = 1 000 000 000 000 micros.

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 Select.

YouTubeSelectSettings

הגדרות בקשה לחבילות ערוצים של YouTube Select

ייצוג JSON 
{
  "lineupId": string
}
שדות
lineupId

string (int64 format)

חבילת ערוצים לטירגוט YouTube Select.

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. אם לא הוגדרה יעילות FrequencyLimit, רשימה זו תהיה ריקה.
onTargetReach

string (int64 format)

מספר המשתמשים הייחודיים שנחשפו למודעות לפחות GenerateReachForecastRequest.min_effective_frequency או מ-GenerateReachForecastRequest.effective_frequency_limit פעמים בהתאמה מדויקת בטירגוט.

הערה: כדי שהנתונים ידווחו, צריך להגיע למספר מינימלי של אנשים ייחודיים. אם לא מגיעים למספר המינימלי, הערך 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)

המספר הכולל של החשיפות של המודעות, כולל צופים בצפייה משותפת. האיסור הזה כולל חשיפות שעשויות לחרוג מהטירגוט שהוגדר, כי אין מספיק מידע על משתמשים שמחוברים לחשבון.

EffectiveFrequencyBreakdown

פירוט של מספר המשתמשים הייחודיים שנחשפו למודעות בתדירות יעילה נתונה.

ייצוג 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)

מספר המשתמשים (כולל משתמשים בצפייה משותפת) שנחשפו ערך עבור ערך ה-effectiveFrequency המשויך.
onTargetEffectiveCoviewReach

string (int64 format)

מספר המשתמשים (כולל משתמשים בצפייה משותפת) שהגעת אליהם עבור ערך ה-effectiveFrequency המשויך בקבוצת הדמוגרפית שצוינה בתוכנית.

PlannedProductReachForecast

המדדים של תחזית ההקצאה והתנועה לגבי מוצר ספציפי בנקודה כלשהי בעקומה של היקף החשיפה.

ייצוג JSON 
{
  "plannableProductCode": string,
  "costMicros": string,
  "plannedProductForecast": {
    object (PlannedProductForecast)
  }
}
שדות
plannableProductCode

string

המוצר שנבחר לתכנון. קודי המוצרים שהוחזרו נמצאים בתוך קבוצת קודי המוצרים שהוחזרו על ידי ListPlannableProducts כשמשתמשים באותו מזהה מיקום.
costMicros

string (int64 format)

העלות במיליוניות השנייה. הסיבה לכך יכולה להיות שונה מהקצאת הקלט של המוצר, אם אחד או יותר מהמוצרים המתוכננים לא יכולים לעמוד בתקציב בגלל מלאי מוגבל.
plannedProductForecast

object (PlannedProductForecast)

מדדי תנועה חזויים עבור המוצר הזה.

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)

המספר הכולל של החשיפות של המודעות, כולל צופים בצפייה משותפת. האיסור הזה כולל חשיפות שעשויות לחרוג מהטירגוט שהוגדר, כי אין מספיק מידע על משתמשים שמחוברים לחשבון.