- בקשת HTTP
- פרמטרים של נתיב
- גוף הבקשה
- גוף התשובה
- היקפי ההרשאות
- CampaignDuration (משך הקמפיין)
- FrequencyCap
- EffectiveFrequencyLimit
- Targeting (טירגוט)
- AudienceTargeting
- PlannedProduct
- AdvancedProductTargeting
- TargetFrequencySettings
- YouTubeSelectSettings
- ForecastMetricOptions
- OnTargetAudienceMetrics
- ReachCurve
- ReachForecast
- תחזית
- EffectiveFrequencyBreakdown
- PlannedProductReachForecast
- PlannedProductForecast
- רוצים לנסות?
יוצרות תחזית של פוטנציאל החשיפה לתמהיל נתון של טירגוט / מוצרים.
רשימת שגיאות שקרו: AuthenticationError AuthorizationError FieldError HeaderError InternalError QuotaError RangeError ReachPlanError RequestError
בקשת HTTP
POST https://googleads.googleapis.com/v15/customers/{customerId}:generateReachForecast
בכתובת ה-URL נעשה שימוש בתחביר המרת קידוד של gRPC.
פרמטרים של נתיב
פרמטרים | |
---|---|
customerId |
חובה. המזהה של הלקוח. |
גוף הבקשה
גוף הבקשה מכיל נתונים במבנה הבא:
ייצוג JSON |
---|
{ "campaignDuration": { object ( |
שדות | |
---|---|
campaignDuration |
חובה. משך הזמן של הקמפיין. |
cookieFrequencyCapSetting |
מכסת התדירות שנבחרה של קובצי cookie תחול על כל מוצר מתוכנן. היא מקבילה למכסת התדירות שנחשפה ב-Google Ads בזמן יצירת הקמפיין. היא מייצגת את מספר הפעמים המקסימלי שהמודעה יכולה להופיע בפני אותו משתמש במהלך פרק זמן מוגדר. אם לא מגדירים ערך, המערכת מחילה את ערך ברירת המחדל 0 (ללא הגבלה). השדה הזה מחליף את השדה cookieFrequencyCap שהוצא משימוש. |
targeting |
הטירגוט שיחול על כל המוצרים שנבחרו בתמהיל המוצרים. זהו טירגוט מתוכנן: פרטי הביצוע עשויים להשתנות בהתאם למוצר הפרסום, יש להתייעץ עם מומחה הטמעה. כדי לראות איך הטירגוט משפיע עליהם, אפשר לעיין במדדים ספציפיים. |
plannedProducts[] |
חובה. המוצרים שייכללו בתחזית. המספר המקסימלי של מוצרים מתוכננים הוא 15. |
forecastMetricOptions |
שליטה במדדי התחזית שמוחזרים בתגובה. |
currencyCode |
קוד המטבע. קוד מטבע בן שלושה תווים לפי תקן ISO 4217. |
cookieFrequencyCap |
מכסת התדירות שנבחרה של קובצי cookie תחול על כל מוצר מתוכנן. היא מקבילה למכסת התדירות שנחשפה ב-Google Ads בזמן יצירת הקמפיין. היא מייצגת את מספר הפעמים המקסימלי שאפשר להציג מודעה לאותו משתמש. אם המדיניות לא מוגדרת, לא תחול מכסה. השדה הזה הוצא משימוש בגרסה 4 ובסופו של דבר הוא יוסר. במקום זאת, אפשר להשתמש בקובץ cookieFrequencyCapSetting. |
minEffectiveFrequency |
התדירות האפקטיבית המינימלית שנבחרה (מספר הפעמים שמשתמש נחשף למודעה) עבור מדדי היקף החשיפה המדווחים [1-10]. הפעולה הזו לא תשפיע על הטירגוט, אלא רק על הדיווח. אם לא מציינים שום ערך, המערכת מחילה את ברירת המחדל של הערך 1. לא ניתן לשלב את השדה הזה עם השדה generateFrequencyLimit. |
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.
CampaignDuration
משך הזמן של קמפיין מתוכנן.
ייצוג JSON |
---|
{
"dateRange": {
object ( |
שדות | |
---|---|
dateRange |
טווח התאריכים של הקמפיין. התאריכים מופיעים בפורמט yyyy-mm-dd וכוללים את התאריכים. תאריך הסיום חייב להיות קטן משנה אחת בעתיד וטווח התאריכים חייב להיות <= 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 ולנקבה. |
devices[] |
מכשירים מטורגטים. אם לא מגדירים טירגוט לכל המכשירים הרלוונטיים. המכשירים הרלוונטיים משתנים בהתאם למוצר ולאזור וניתן להשיג אותם ב- |
network |
רשת שניתן לטרגט עבור מוצר המודעה. אם לא מציינים שום אפשרות, הטירגוט יטרגט את כל הרשתות הרלוונטיות. הרשתות הרלוונטיות משתנות לפי מוצר ואזור וניתן להשיג אותן ברשת |
audienceTargeting |
קהלי יעד. אם לא מציינים שום אפשרות, המערכת לא תטרגט קהל ספציפי. |
plannableLocationId |
המזהה של המיקום שנבחר. ניתן לקבל מזהי מיקומים שניתנים לתכנון בכתובת הבקשות צריכות להגדיר את השדה הזה או השדה הזה הוצא משימוש החל מ-V12 ויוסר בגרסה עתידית. במקום זאת, השתמשו ב- |
AudienceTargeting
טירגוט לפי קהל לצורך תחזית פוטנציאל החשיפה.
ייצוג JSON |
---|
{
"userInterest": [
{
object ( |
שדות | |
---|---|
userInterest[] |
רשימת קהלים לטירגוט לפי תחומי עניין של משתמשים. |
PlannedProduct
מוצר שאנחנו מתכננים להגדיל את פוטנציאל החשיפה שלו.
ייצוג JSON |
---|
{
"advancedProductTargeting": {
object ( |
שדות | |
---|---|
advancedProductTargeting |
הגדרות הטירגוט של המוצר שנבחר. כדי להציג את אפשרויות הטירגוט הזמינות לכל מוצר, צריך להשתמש במאפיין |
plannableProductCode |
חובה. המוצר שנבחר לתכנון. הקוד שמשויך למוצר המודעה (לדוגמה: Trueview או באמפר). כדי לציין את קודי המוצרים הזמינים שניתנים לתכנון, משתמשים ב- |
budgetMicros |
חובה. הקצאת תקציב מקסימלית ב-Micros למוצר שנבחר. הערך צוין בקוד המטבע לתכנון שנבחר. לדוגמה: 1 000 000$ = 1 000 000 000 000 micros. |
AdvancedProductTargeting
הגדרות טירגוט מתקדמות למוצרים.
ייצוג JSON |
---|
{ "surfaceTargetingSettings": { object ( |
שדות | |
---|---|
surfaceTargetingSettings |
הגדרות טירגוט בפלטפורמות של המוצר הזה. |
targetFrequencySettings |
ההגדרות של קמפיין תדירות טירגוט. יש להגדיר את הערך בזמן הבחירה במוצר TARGET_Frequency. מידע נוסף על קמפיינים לתדירות טירגוט זמין בכתובת https://support.google.com/google-ads/answer/12400225. |
שדה איחוד advanced_targeting . אפשרויות הטירגוט של המוצר. advanced_targeting יכול להיות רק אחד מהבאים: |
|
youtubeSelectSettings |
הגדרות לטירגוט ב-YouTube Select. |
TargetFrequencySettings
הגדרות של תדירות טירגוט למוצר נתמך.
ייצוג JSON |
---|
{
"timeUnit": enum ( |
שדות | |
---|---|
timeUnit |
חובה. יחידת הזמן המשמשת לתיאור מסגרת הזמן של targetFrequency. |
targetFrequency |
חובה. יעד תדירות הטירגוט לכל יחידת זמן שנבחרה. |
YouTubeSelectSettings
הגדרות בקשה לחבילות ערוצים של YouTube Select
ייצוג JSON |
---|
{ "lineupId": string } |
שדות | |
---|---|
lineupId |
חבילת ערוצים לטירגוט YouTube Select. |
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. אם לא הוגדרה יעילות FrequencyLimit, רשימה זו תהיה ריקה. |
onTargetReach |
מספר המשתמשים הייחודיים שנחשפו למודעות לפחות GenerateReachForecastRequest.min_effective_frequency או מ-GenerateReachForecastRequest.effective_frequency_limit פעמים בהתאמה מדויקת בטירגוט. הערה: כדי שהנתונים ידווחו, צריך להגיע למספר מינימלי של אנשים ייחודיים. אם לא מגיעים למספר המינימלי, הערך 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 |
המספר הכולל של החשיפות של המודעות, כולל צופים בצפייה משותפת. האיסור הזה כולל חשיפות שעשויות לחרוג מהטירגוט שהוגדר, כי אין מספיק מידע על משתמשים שמחוברים לחשבון. |
views |
מספר הצפיות במודעות הצפויות עבור המוצר והטירגוט שצוינו. צפייה נספרת כשמשתמש צופה בחלק משמעותי מהמודעה, או במודעה כולה, מעבר לחשיפה. מידע נוסף על תצוגות זמין בכתובת https://support.google.com/google-ads/answer/2375431. |
EffectiveFrequencyBreakdown
פירוט של מספר המשתמשים הייחודיים שנחשפו למודעות בתדירות יעילה נתונה.
ייצוג JSON |
---|
{ "effectiveFrequency": integer, "onTargetReach": string, "totalReach": string, "effectiveCoviewReach": string, "onTargetEffectiveCoviewReach": string } |
שדות | |
---|---|
effectiveFrequency |
התדירות האפקטיבית [1-10]. |
onTargetReach |
מספר האנשים הייחודיים שנחשפו למודעות לפחות פעמים רבות ומתאימים בדיוק לטירגוט. הערה: כדי שהנתונים ידווחו, צריך להגיע למספר מינימלי של אנשים ייחודיים. אם לא מגיעים למספר המינימלי, הערך onTargetReach יעוגל ל-0. |
totalReach |
המספר הכולל של משתמשים ייחודיים שנחשפו למודעות לפחות פעמים. הטירגוט הזה כולל אנשים שעשויים לחרוג מהטירגוט שצוין. הערה: כדי שהנתונים ידווחו, צריך להגיע למספר מינימלי של אנשים ייחודיים. אם לא מגיעים למספר המינימלי, הערך של totalReach יעוגל ל-0. |
effectiveCoviewReach |
מספר המשתמשים (כולל משתמשים בצפייה משותפת) שנחשפו ערך עבור ערך ה-effectiveFrequency המשויך. |
onTargetEffectiveCoviewReach |
מספר המשתמשים (כולל משתמשים בצפייה משותפת) שהגעת אליהם עבור ערך ה-effectiveFrequency המשויך בקבוצת הדמוגרפית שצוינה בתוכנית. |
PlannedProductReachForecast
המדדים של תחזית ההקצאה והתנועה לגבי מוצר ספציפי בנקודה כלשהי בעקומה של היקף החשיפה.
ייצוג JSON |
---|
{
"plannableProductCode": string,
"costMicros": string,
"plannedProductForecast": {
object ( |
שדות | |
---|---|
plannableProductCode |
המוצר שנבחר לתכנון. קודי המוצרים שהוחזרו נמצאים בתוך קבוצת קודי המוצרים שהוחזרו על ידי ListPlannableProducts כשמשתמשים באותו מזהה מיקום. |
costMicros |
העלות במיליוניות השנייה. הסיבה לכך יכולה להיות שונה מהקצאת הקלט של המוצר, אם אחד או יותר מהמוצרים המתוכננים לא יכולים לעמוד בתקציב בגלל מלאי מוגבל. |
plannedProductForecast |
מדדי תנועה חזויים עבור המוצר הזה. |
PlannedProductForecast
מדדי תנועה חזויים של מוצר מתוכנן.
ייצוג JSON |
---|
{ "onTargetReach": string, "totalReach": string, "onTargetImpressions": string, "totalImpressions": string, "viewableImpressions": string, "onTargetCoviewReach": string, "totalCoviewReach": string, "onTargetCoviewImpressions": string, "totalCoviewImpressions": string, "averageFrequency": number, "views": string } |
שדות | |
---|---|
onTargetReach |
מספר המשתמשים הייחודיים שנחשפו למודעות שתואמות במדויק לטירגוט. הערה: כדי שהנתונים ידווחו, צריך להגיע למספר מינימלי של אנשים ייחודיים. אם לא מגיעים למספר המינימלי, הערך onTargetReach יעוגל ל-0. |
totalReach |
מספר המשתמשים הייחודיים שנחשפו למודעות. הטירגוט הזה כולל אנשים שעשויים לחרוג מהטירגוט שצוין. הערה: כדי שהנתונים ידווחו, צריך להגיע למספר מינימלי של אנשים ייחודיים. אם לא מגיעים למספר המינימלי, הערך של totalReach יעוגל ל-0. |
onTargetImpressions |
מספר חשיפות של מודעה שתואם בדיוק לטירגוט. |
totalImpressions |
מספר החשיפות הכולל של המודעות. האיסור הזה כולל חשיפות שעשויות לחרוג מהטירגוט שהוגדר, כי אין מספיק מידע על משתמשים שמחוברים לחשבון. |
viewableImpressions |
מספר הפעמים שבו חשיפות של מודעה נחשבו כניתנות לצפייה. בכתובת https://support.google.com/google-ads/answer/7029393 אפשר למצוא מידע נוסף על הגורמים שהופכים את המודעה לניתנת לצפייה ועל אופן המדידה של הניראות. |
onTargetCoviewReach |
מספר המשתמשים הייחודיים שנחשפו למודעות בדיוק שתואמות לטירגוט, כולל צופים בצפייה משותפת. |
totalCoviewReach |
מספר המשתמשים הייחודיים שנחשפו למודעות, כולל צופים בצפייה משותפת. הטירגוט הזה כולל אנשים שעשויים לחרוג מהטירגוט שצוין. |
onTargetCoviewImpressions |
מספר החשיפות של מודעות שתואם במדויק לטירגוט, כולל צופים בצפייה משותפת. |
totalCoviewImpressions |
המספר הכולל של החשיפות של המודעות, כולל צופים בצפייה משותפת. האיסור הזה כולל חשיפות שעשויות לחרוג מהטירגוט שהוגדר, כי אין מספיק מידע על משתמשים שמחוברים לחשבון. |
averageFrequency |
מספר הפעמים שבהן משתמש יראה מודעה בכל יחידת זמן שנבחרה. המדד הזה מחושב לפי הממוצע של מספר יחידות הזמן לאורך התחזית. השדה הזה יאוכלס רק בקמפיין תדירות טירגוט. מידע נוסף על קמפיינים לתדירות טירגוט זמין בכתובת https://support.google.com/google-ads/answer/12400225. |
views |
מספר הצפיות במודעות הצפויות עבור המוצר והטירגוט שצוינו. צפייה נספרת כשמשתמש צופה בחלק משמעותי מהמודעה, או במודעה כולה, מעבר לחשיפה. מידע נוסף על תצוגות זמין בכתובת https://support.google.com/google-ads/answer/2375431. |