Method: customers.generateReachForecast

Generuje prognozę zasięgu dla danego kierowania lub zestawu reklam.

Lista zgłoszonych błędów: AuthenticationError AuthorizationError FieldError HeaderError InternalError QuotaError RangeError ReachPlanError RequestError

Żądanie HTTP

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

Adres URL używa składni transkodowania gRPC.

Parametry ścieżki

Parametry
customerId

string

To pole jest wymagane. Identyfikator klienta.

Treść żądania

Treść żądania zawiera dane o następującej strukturze:

Zapis 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
}
Pola
campaignDuration

object (CampaignDuration)

To pole jest wymagane. Czas trwania kampanii.
cookieFrequencyCapSetting

object (FrequencyCap)

Wybierz limit wyświetleń na użytkownika, który zostanie zastosowany do każdego zaplanowanego produktu. Jest to odpowiednik limitu wyświetleń na użytkownika wyświetlany w Google Ads podczas tworzenia kampanii i reprezentuje maksymalną liczbę wyświetleń reklamy temu samemu użytkownikowi w określonym przedziale czasu. Jeśli nie określisz tu żadnej wartości, zostanie zastosowana domyślna wartość 0 (bez limitu).

To pole zastępuje wycofane pole cookiefrequencyCap.
targeting

object (Targeting)

Kierowanie, które zostanie zastosowane do wszystkich produktów wybranych w zestawie produktów.

Tak jest w przypadku kierowania reklam: szczegóły realizacji mogą się różnić w zależności od usługi reklamowej, skontaktuj się ze specjalistą ds. implementacji.

Szczegółowe informacje o tym, jak kierowanie na nie wpływa na konkretne dane,
plannedProducts[]

object (PlannedProduct)

To pole jest wymagane. Produkty, które mają być objęte prognozą. Maksymalna liczba dozwolonych zaplanowanych produktów to 15.
forecastMetricOptions

object (ForecastMetricOptions)

Określa dane prognozy zwracane w odpowiedzi.
currencyCode

string

Kod waluty. 3-znakowy kod waluty w formacie ISO 4217.
cookieFrequencyCap

integer

Wybierz limit wyświetleń na użytkownika, który zostanie zastosowany do każdego zaplanowanego produktu. Jest to odpowiednik limitu wyświetleń na użytkownika wyświetlanej w Google Ads podczas tworzenia kampanii i odpowiada on maksymalnej liczbie wyświetleń reklamy temu samemu użytkownikowi. Jeśli go nie podasz, nie zostaną zastosowane żadne ograniczenia.

To pole jest wycofane w wersji 4 i wkrótce zostanie usunięte. Zamiast tego używaj parametru cookiefrequencyCapSetting.
minEffectiveFrequency

integer

Wybrana minimalna efektywna częstotliwość (liczba wyświetleń reklamy danemu użytkownikowi) dla raportowanych danych o zasięgu [1–10]. Nie wpłynie to na kierowanie, ale tylko na raportowanie. Jeśli nie określisz żadnej wartości, zostanie zastosowana domyślna wartość 1.

Tego pola nie można łączyć z polemeffectivefrequencyLimit.
effectiveFrequencyLimit

object (EffectiveFrequencyLimit)

Najwyższa minimalna efektywna częstotliwość (czyli liczba wyświetleń reklamy danej osobie) [1–10], która ma zostać uwzględniona w parametrze Forecast.effective_frequency_breakdowns. Jeśli nie podasz żadnej wartości, wartość Forecast.effective_frequency_breakdowns nie będzie podana.

Podana tu wartość efektywnej częstotliwości będzie również używana jako minimalna efektywna częstotliwość w raportowanych danych o zasięgu.

Tego pola nie można łączyć z polem minEffectivefrequency.
customerReachGroup

string

Nazwa planowanego klienta. Jest to wartość zdefiniowana przez użytkownika.

Treść odpowiedzi

Komunikat odpowiedzi zawierający wygenerowaną krzywą zasięgu.

W przypadku powodzenia treść żądania zawiera dane o następującej strukturze:

Zapis JSON 
{
  "onTargetAudienceMetrics": {
    object (OnTargetAudienceMetrics)
  },
  "reachCurve": {
    object (ReachCurve)
  }
}
Pola
onTargetAudienceMetrics

object (OnTargetAudienceMetrics)

Dokumentacja na temat docelowych odbiorców dla tej krzywej.
reachCurve

object (ReachCurve)

Wygenerowana krzywa zasięgu dla planowanego zestawu produktów.

Zakresy autoryzacji

Wymaga następującego zakresu OAuth:

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

Więcej informacji znajdziesz w omówieniu protokołu OAuth 2.0.

CampaignDuration

Czas trwania zaplanowanej kampanii.

Zapis JSON 
{
  "dateRange": {
    object (DateRange)
  },
  "durationInDays": integer
}
Pola
dateRange

object (DateRange)

Zakres dat kampanii. Daty są podane w formacie rrrr-mm-dd i włącznie. Data zakończenia musi być oddalona o mniej niż rok, a zakres dat musi obejmować mniej niż 92 dni.

Tego pola nie można łączyć z polemdurationInDays.
durationInDays

integer

Wartość czasu trwania w dniach.

Tego pola nie można łączyć z polem dateRange.

FrequencyCap

Reguła, która określa maksymalną liczbę wyświetleń reklamy użytkownikowi w danym okresie.

Zapis JSON 
{
  "impressions": integer,
  "timeUnit": enum (FrequencyCapTimeUnit)
}
Pola
impressions

integer

To pole jest wymagane. Liczba wyświetleń włącznie.
timeUnit

enum (FrequencyCapTimeUnit)

To pole jest wymagane. Typ jednostki czasu.

EffectiveFrequencyLimit

Rzeczywisty limit częstotliwości.

Zapis JSON 
{
  "effectiveFrequencyBreakdownLimit": integer
}
Pola
effectiveFrequencyBreakdownLimit

integer

Najwyższa wartość efektywna częstotliwości do uwzględnienia w Forecast.effective_frequency_breakdowns. To pole obsługuje częstotliwości od 1 do 10 włącznie.

Kierowanie

Kierowanie, w którego przypadku będą raportowane dane o ruchu.

Zapis JSON 
{
  "plannableLocationIds": [
    string
  ],
  "ageRange": enum (ReachPlanAgeRange),
  "genders": [
    {
      object (GenderInfo)
    }
  ],
  "devices": [
    {
      object (DeviceInfo)
    }
  ],
  "network": enum (ReachPlanNetwork),
  "audienceTargeting": {
    object (AudienceTargeting)
  },
  "plannableLocationId": string
}
Pola
plannableLocationIds[]

string

Lista identyfikatorów lokalizacji, na które można zaplanować kierowanie zgodnie z tą prognozą.

Jeśli podasz więcej identyfikatorów, wszystkie muszą mieć taką samą wartość parentCountryId. Planowanie obejmujące więcej niż parent_county nie jest obsługiwane. Identyfikatory planowanych lokalizacji i ich parentCountryId można uzyskać z usługi ReachPlanService.ListPlannableLocations.

Żądania muszą mieć ustawione to pole lub plannableLocationId.
ageRange

enum (ReachPlanAgeRange)

Docelowe przedziały wiekowe. Nieskonfigurowana wartość jest odpowiednikiem kierowania na wszystkie grupy wiekowe.
genders[]

object (GenderInfo)

Docelowe płcie. Nieskonfigurowana wartość jest odpowiednikiem kierowania na „MALE” i „FEMALE”.
devices[]

object (DeviceInfo)

Docelowe urządzenia. Jeśli nie podasz żadnej wartości, reklamy będą kierowane na wszystkie odpowiednie urządzenia. Dostępne urządzenia różnią się w zależności od produktu i regionu. Można je kupić od firmy ReachPlanService.ListPlannableProducts.
network

enum (ReachPlanNetwork)

Sieć, na którą można kierować ofertę reklamową. Jeśli nie podasz żadnej wartości, reklamy będą kierowane na wszystkie odpowiednie sieci. Dostępne sieci różnią się w zależności od usługi i regionu. Można je znaleźć pod adresem ReachPlanService.ListPlannableProducts.
audienceTargeting

object (AudienceTargeting)

Wybrani odbiorcy. Jeśli go nie określisz, nie kierujesz reklam na konkretnych odbiorców.
plannableLocationId

string

Identyfikator wybranej lokalizacji. Identyfikatory planowanych lokalizacji możesz uzyskać z: ReachPlanService.ListPlannableLocations.

Żądania muszą mieć ustawione to pole lub plannableLocationIds.

Od wersji 12 to pole jest wycofane i zostanie usunięte w kolejnej wersji. Użyj w zamian zasady plannableLocationIds.

AudienceTargeting

Prognoza dotycząca kierowania na odbiorców i zasięgu.

Zapis JSON 
{
  "userInterest": [
    {
      object (UserInterestInfo)
    }
  ]
}
Pola
userInterest[]

object (UserInterestInfo)

Lista odbiorców utworzona na podstawie zainteresowań użytkowników, na których można kierować reklamy.

PlannedProduct

Usługa, której zasięg jest planowany.

Zapis JSON 
{
  "advancedProductTargeting": {
    object (AdvancedProductTargeting)
  },
  "plannableProductCode": string,
  "budgetMicros": string
}
Pola
advancedProductTargeting

object (AdvancedProductTargeting)

Ustawienia kierowania dla wybranej usługi. Aby wyświetlić listę dostępnych opcji kierowania dla poszczególnych produktów, użyj ReachPlanService.ListPlannableProducts.
plannableProductCode

string

To pole jest wymagane. Wybrany produkt do planowania. Kod powiązany z ofertą reklamową (np. TrueView, bumper). Aby wyświetlić listę dostępnych kodów produktów, które można zaplanować, użyj pola ReachPlanService.ListPlannableProducts.
budgetMicros

string (int64 format)

To pole jest wymagane. Maksymalne przydział budżetu (w mikro) na wybrany produkt. Wartość jest podana w wybranym kodzie currencyCode planowania. Na przykład: 1 000 000$ = 1 000 000 000 000 mikro.

AdvancedProductTargeting

Zaawansowane ustawienia kierowania produktów.

Zapis JSON 
{
  "surfaceTargetingSettings": {
    object (SurfaceTargeting)
  },
  "targetFrequencySettings": {
    object (TargetFrequencySettings)
  },

  // 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.
}
Pola
surfaceTargetingSettings

object (SurfaceTargeting)

Ustawienia kierowania na powierzchnię tego produktu.
targetFrequencySettings

object (TargetFrequencySettings)

Ustawienia kampanii z docelową częstotliwością. Należy go ustawić podczas wybierania produktu TARGET_FREQUENCY.

Więcej informacji o kampaniach z docelową częstotliwością znajdziesz na stronie https://support.google.com/google-ads/answer/12400225.
Pole sumy advanced_targeting. Opcje kierowania tej usługi. advanced_targeting może być tylko jedną z tych wartości:
youtubeSelectSettings

object (YouTubeSelectSettings)

Ustawienia kierowania YouTube Select.

TargetFrequencySettings

Ustawienia docelowej częstotliwości dla obsługiwanego produktu.

Zapis JSON 
{
  "timeUnit": enum (TargetFrequencyTimeUnit),
  "targetFrequency": integer
}
Pola
timeUnit

enum (TargetFrequencyTimeUnit)

To pole jest wymagane. Jednostka czasu używana do opisania przedziału czasu dla parametru targetfrequency.
targetFrequency

integer

To pole jest wymagane. Cel częstotliwości docelowej w wybranej jednostce czasu.

YouTubeSelectSettings

Przesyłanie prośby o ustawienia dotyczące lineupów YouTube Select

Zapis JSON 
{
  "lineupId": string
}
Pola
lineupId

string (int64 format)

Lineup do kierowania reklam YouTube Select.

ForecastMetricOptions

Określa dane prognozy, które mają zostać zwrócone.

Zapis JSON 
{
  "includeCoview": boolean
}
Pola
includeCoview

boolean

Wskazuje, czy w prognozie odpowiedzi uwzględnić dane dotyczące wspólnego oglądania.

OnTargetAudienceMetrics

Dane o odbiorcach dotyczące zaplanowanych produktów. Dane te uwzględniają te wymiary kierowania:

  • Lokalizacja
  • PlannableAgeRange
  • Płeć
  • Kierowanie na odbiorców (tylko w przypadku youtubeAudienceSize)
Zapis JSON 
{
  "youtubeAudienceSize": string,
  "censusAudienceSize": string
}
Pola
youtubeAudienceSize

string (int64 format)

Porównaj wielkość grupy odbiorców pasującą do rozważanego kierowania w YouTube.
censusAudienceSize

string (int64 format)

Porównaj wielkość grupy odbiorców pasującą do kryteriów kierowania uwzględnionego w spisie ludności.

ReachCurve

Krzywa zasięgu planowanych produktów.

Zapis JSON 
{
  "reachForecasts": [
    {
      object (ReachForecast)
    }
  ]
}
Pola
reachForecasts[]

object (ReachForecast)

Wszystkie punkty na krzywej zasięgu.

ReachForecast

Punkt na krzywej zasięgu.

Zapis JSON 
{
  "costMicros": string,
  "forecast": {
    object (Forecast)
  },
  "plannedProductReachForecasts": [
    {
      object (PlannedProductReachForecast)
    }
  ]
}
Pola
costMicros

string (int64 format)

Koszt w mikro.
forecast

object (Forecast)

Prognozowane dane o ruchu w tym punkcie.
plannedProductReachForecasts[]

object (PlannedProductReachForecast)

Prognozowane dane dotyczące przydziału i ruchu dla każdego zaplanowanego produktu w tym miejscu na krzywej zasięgu.

Prognoza

Prognozowane dane o ruchu dotyczące zaplanowanych produktów i ustawień kierowania.

Zapis JSON 
{
  "effectiveFrequencyBreakdowns": [
    {
      object (EffectiveFrequencyBreakdown)
    }
  ],
  "onTargetReach": string,
  "totalReach": string,
  "onTargetImpressions": string,
  "totalImpressions": string,
  "viewableImpressions": string,
  "onTargetCoviewReach": string,
  "totalCoviewReach": string,
  "onTargetCoviewImpressions": string,
  "totalCoviewImpressions": string,
  "views": string
}
Pola
effectiveFrequencyBreakdowns[]

object (EffectiveFrequencyBreakdown)

Lista skutecznych prognoz częstotliwości. Lista jest uporządkowana od 1+ do wartości określonej w GenerateReachForecastRequest.effective_frequency_limit. Jeśli nie ustawiono efektywnego limitu częstotliwości, ta lista będzie pusta.
onTargetReach

string (int64 format)

Liczba unikalnych użytkowników, do których udało się dotrzeć co najmniej GenerateReachForecastRequest.min_effective_frequency lub GenerateReachForecastRequest.effective_frequency_limit razy, gdy odpowiada wartości kierowania.

Pamiętaj, że do uwzględnienia danych w raportach wymagana jest minimalna liczba unikalnych użytkowników. Jeśli minimalna liczba nie zostanie osiągnięta, wartość onTargetReach zostanie zaokrąglona do 0.
totalReach

string (int64 format)

Łączna liczba unikalnych osób, do których udało się dotrzeć co najmniej GenerateReachForecastRequest.min_effective_frequency lub GenerateReachForecastRequest.effective_frequency_limit razy. Obejmuje to osoby, które mogą nie spełniać kryteriów kierowania.

Pamiętaj, że do uwzględnienia danych w raportach wymagana jest minimalna liczba unikalnych użytkowników. Jeśli minimalna liczba nie zostanie osiągnięta, wartość totalReach zostanie zaokrąglona do 0.
onTargetImpressions

string (int64 format)

Liczba wyświetleń reklamy, które dokładnie odpowiadają wartości kierowania.
totalImpressions

string (int64 format)

Łączna liczba wyświetleń reklam. Obejmuje to wyświetlenia, które mogą wykraczać poza zakres kierowania z powodu niewystarczających informacji o zalogowanych użytkownikach.
viewableImpressions

string (int64 format)

Liczba wyświetleń reklamy uznanych za widoczne. Więcej informacji o tym, co sprawia, że reklama jest widoczna i jak jest mierzona, znajdziesz na stronie https://support.google.com/google-ads/answer/7029393.
onTargetCoviewReach

string (int64 format)

Liczba unikalnych użytkowników, którzy zobaczyli reklamę i ściśle zgodny z kierowaniem, z uwzględnieniem wspólnego oglądania.
totalCoviewReach

string (int64 format)

Liczba unikalnych osób, do których udało się dotrzeć, w tym widzów oglądających wspólnie. Obejmuje to osoby, które mogą nie spełniać kryteriów kierowania.
onTargetCoviewImpressions

string (int64 format)

Liczba wyświetleń reklamy, która jest dokładnie zgodna z kierowaniem, z uwzględnieniem wspólnego oglądania.
totalCoviewImpressions

string (int64 format)

Łączna liczba wyświetleń reklamy z uwzględnieniem wspólnego oglądania. Obejmuje to wyświetlenia, które mogą wykraczać poza zakres kierowania z powodu niewystarczających informacji o zalogowanych użytkownikach.
views

string (int64 format)

Prognozowana liczba wyświetleń reklamy dla określonego produktu i określonego kierowania. Obejrzenie jest liczone, gdy widz obejrzy większą część lub całość reklamy, a nie tylko wyświetlenie.

Więcej informacji o wyświetleniach znajdziesz na stronie https://support.google.com/google-ads/answer/2375431.

EffectiveFrequencyBreakdown

Podział liczby unikalnych użytkowników, do których udało się dotrzeć z określoną efektywną częstotliwością.

Zapis JSON 
{
  "effectiveFrequency": integer,
  "onTargetReach": string,
  "totalReach": string,
  "effectiveCoviewReach": string,
  "onTargetEffectiveCoviewReach": string
}
Pola
effectiveFrequency

integer

Efektywna częstotliwość [1–10].
onTargetReach

string (int64 format)

Liczba unikalnych użytkowników, do których udało się dotrzeć z co najmniej skuteczną częstotliwością równą liczbie wyświetleń zgodnej z wartością „Kierowanie”.

Pamiętaj, że do uwzględnienia danych w raportach wymagana jest minimalna liczba unikalnych użytkowników. Jeśli minimalna liczba nie zostanie osiągnięta, wartość onTargetReach zostanie zaokrąglona do 0.
totalReach

string (int64 format)

Łączna liczba unikalnych użytkowników, do których udało się dotrzeć z co najmniej skuteczną częstotliwością. Obejmuje to osoby, które mogą nie spełniać kryteriów kierowania.

Pamiętaj, że do uwzględnienia danych w raportach wymagana jest minimalna liczba unikalnych użytkowników. Jeśli minimalna liczba nie zostanie osiągnięta, wartość totalReach zostanie zaokrąglona do 0.
effectiveCoviewReach

string (int64 format)

Liczba użytkowników (w tym użytkowników wspólnego oglądania), do których udało się dotrzeć w przypadku powiązanej wartości efektywnej częstotliwości.
onTargetEffectiveCoviewReach

string (int64 format)

Liczba użytkowników (w tym użytkowników wspólnego oglądania), do których udało się dotrzeć w przypadku powiązanej wartości efektywnej częstotliwości w ramach określonej grupy demograficznej w planie.

PlannedProductReachForecast

Prognozowane dane dotyczące przydziału i ruchu dotyczące konkretnego produktu w punkcie na krzywej zasięgu.

Zapis JSON 
{
  "plannableProductCode": string,
  "costMicros": string,
  "plannedProductForecast": {
    object (PlannedProductForecast)
  }
}
Pola
plannableProductCode

string

Wybrany produkt do planowania. Zwrócone kody produktów należą do zestawu kodów zwracanych przez element ListPlannableProducts przy użyciu tego samego identyfikatora lokalizacji.
costMicros

string (int64 format)

Koszt w mikro. Może się ona różnić od przydziału danych wejściowych dla produktu, jeśli co najmniej 1 zaplanowany produkt nie może wykorzystać budżetu z powodu ograniczonych zasobów reklamowych.
plannedProductForecast

object (PlannedProductForecast)

Prognozowane dane o ruchu w przypadku tej usługi.

PlannedProductForecast

Prognozowane dane o ruchu w planowanym produkcie.

Zapis JSON 
{
  "onTargetReach": string,
  "totalReach": string,
  "onTargetImpressions": string,
  "totalImpressions": string,
  "viewableImpressions": string,
  "onTargetCoviewReach": string,
  "totalCoviewReach": string,
  "onTargetCoviewImpressions": string,
  "totalCoviewImpressions": string,
  "averageFrequency": number,
  "views": string
}
Pola
onTargetReach

string (int64 format)

Liczba unikalnych osób, do których udało się dotrzeć, dokładnie odpowiadająca wartości w sekcji Kierowanie.

Pamiętaj, że do uwzględnienia danych w raportach wymagana jest minimalna liczba unikalnych użytkowników. Jeśli minimalna liczba nie zostanie osiągnięta, wartość onTargetReach zostanie zaokrąglona do 0.
totalReach

string (int64 format)

Liczba unikalnych osób, do których udało się dotrzeć. Obejmuje to osoby, które mogą nie spełniać kryteriów kierowania.

Pamiętaj, że do uwzględnienia danych w raportach wymagana jest minimalna liczba unikalnych użytkowników. Jeśli minimalna liczba nie zostanie osiągnięta, wartość totalReach zostanie zaokrąglona do 0.
onTargetImpressions

string (int64 format)

Liczba wyświetleń reklamy, które dokładnie odpowiadają wartości kierowania.
totalImpressions

string (int64 format)

Łączna liczba wyświetleń reklam. Obejmuje to wyświetlenia, które mogą wykraczać poza zakres kierowania z powodu niewystarczających informacji o zalogowanych użytkownikach.
viewableImpressions

string (int64 format)

Liczba wyświetleń reklamy uznanych za widoczne. Więcej informacji o tym, co sprawia, że reklama jest widoczna i jak jest mierzona, znajdziesz na stronie https://support.google.com/google-ads/answer/7029393.
onTargetCoviewReach

string (int64 format)

Liczba unikalnych użytkowników, którzy zobaczyli reklamę i ściśle zgodny z kierowaniem, z uwzględnieniem wspólnego oglądania.
totalCoviewReach

string (int64 format)

Liczba unikalnych osób, do których udało się dotrzeć, w tym widzów oglądających wspólnie. Obejmuje to osoby, które mogą nie spełniać kryteriów kierowania.
onTargetCoviewImpressions

string (int64 format)

Liczba wyświetleń reklamy, która jest dokładnie zgodna z kierowaniem, z uwzględnieniem wspólnego oglądania.
totalCoviewImpressions

string (int64 format)

Łączna liczba wyświetleń reklamy z uwzględnieniem wspólnego oglądania. Obejmuje to wyświetlenia, które mogą wykraczać poza zakres kierowania z powodu niewystarczających informacji o zalogowanych użytkownikach.
averageFrequency

number

Średnia liczba jednostek czasu wyświetlenia reklamy w wybranej jednostce czasu w prognozie. To pole będzie wypełniane tylko w przypadku kampanii z docelową częstotliwością.

Więcej informacji o kampaniach z docelową częstotliwością znajdziesz na stronie https://support.google.com/google-ads/answer/12400225.
views

string (int64 format)

Prognozowana liczba wyświetleń reklamy dla określonego produktu i określonego kierowania. Obejrzenie jest liczone, gdy widz obejrzy większą część lub całość reklamy, a nie tylko wyświetlenie.

Więcej informacji o wyświetleniach znajdziesz na stronie https://support.google.com/google-ads/answer/2375431.