Previsão

Introdução

Este guia explica as diferentes maneiras de usar a previsão na API Google Ad Manager.

Previsão de tráfego

Uma estimativa de tráfego permite ler o histórico de tráfego e as oportunidades de impressão futuras para encontrar melhores maneiras de segmentar e agrupar inventários.

Java

// Create the date range. Include the previous and next 7 days.
Interval interval =
    new Interval(
        Instant.now().plus(Duration.standardDays(-7)),
        Instant.now().plus(Duration.standardDays(7)));
DateRange dateRange = new DateRange();
dateRange.setStartDate(DateTimes.toDateTime(interval.getStart()).getDate());
dateRange.setEndDate(DateTimes.toDateTime(interval.getEnd()).getDate());

// Request the traffic data.
TrafficDataRequest trafficDataRequest = new TrafficDataRequest();
trafficDataRequest.setRequestedDateRange(dateRange);
trafficDataRequest.setTargeting(targeting);
TrafficDataResponse trafficData = forecastService.getTrafficData(trafficDataRequest);

Python

# Create a start date that's 7 days in the past and an end date that's 7 days
# in the future.
today = datetime.date.today()
start_date = today - datetime.timedelta(days=7)
end_date = today + datetime.timedelta(days=7)

# Create targeting.
targeting = {
    'inventoryTargeting': {
        'targetedAdUnits': [
            {
                'includeDescendants': True,
                'adUnitId': root_ad_unit_id,
            }
        ]
    }
}

# Request the traffic forecast data.
traffic_data = forecast_service.getTrafficData({
    'targeting': targeting,
    'requestedDateRange': {
        'startDate': start_date,
        'endDate': end_date
    }
})

PHP

// Create the date range. Include the previous and next 7 days.
$startDate = AdManagerDateTimes::fromDateTime(new DateTime('-7 day'))
    ->getDate();
$endDate = AdManagerDateTimes::fromDateTime(new DateTime('+7 day'))
    ->getDate();
$dateRange = new DateRange();
$dateRange->setStartDate($startDate);
$dateRange->setEndDate($endDate);

// Request the traffic forecast data.
$trafficDataRequest = new TrafficDataRequest();
$trafficDataRequest->setRequestedDateRange($dateRange);
$trafficDataRequest->setTargeting($targeting);
$trafficData = $forecastService->getTrafficData($trafficDataRequest);

C#

TrafficDataRequest trafficDataRequest = new TrafficDataRequest() {
    requestedDateRange = new DateRange() {
        startDate =
            DateTimeUtilities.FromDateTime(startDate, "America/New_York").date,
        endDate = DateTimeUtilities.FromDateTime(endDate, "America/New_York").date
    },
    targeting = new Targeting() {
        inventoryTargeting = new InventoryTargeting()
        {
            targetedAdUnits = new AdUnitTargeting[] {
                new AdUnitTargeting() {
                 adUnitId = rootAdUnitId,
                 includeDescendants = true
                }
            }
        }
    }
};
TrafficDataResponse trafficData =
    forecastService.getTrafficData(trafficDataRequest);

Ruby

# Create a start date that's 7 days in the past and an end date that's 7 days
# in the future.
today = ad_manager.today
start_date = today - 7
end_date = today + 7

# Create targeting.
targeting = {
  :inventory_targeting => {
    :targeted_ad_units => [
      {
        :include_descendants => true,
        :ad_unit_id => root_ad_unit_id
      }
    ]
  }
}

# Request the traffic forecast data.
traffic_data = forecast_service.get_traffic_data({
  :targeting => targeting,
  :requested_date_range => {
    :start_date => start_date.to_h, :end_date => end_date.to_h
  }
})

Previsões de disponibilidade

Um AvailabilityForecast informa o número máximo de unidades disponíveis com que o item de linha pode ser reservado. Essa previsão é análoga à verificação inventário na interface.

A previsão inclui as unidades disponíveis, correspondentes, possíveis, entregues e reservadas. Também pode incluir todos os itens de linha concorrentes e as unidades disponíveis para cada segmentação detalhamento dependendo das opções definidas AvailabilityForecastOptions. Por padrão, nenhum deles é incluído na previsão.

Os detalhamentos de segmentação incluem as unidades correspondentes e disponíveis para cada segmentação critérios. Essas entradas de detalhamento são geradas automaticamente de acordo com o a segmentação do item de linha. Por exemplo, um item de linha segmentado pelo ID do bloco de anúncios 123456 incluiria um detalhamento semelhante a este:

<targetingCriteriaBreakdowns>
  <targetingDimension>AD_UNIT</targetingDimension>
  <targetingCriteriaId>123456</targetingCriteriaId>
  <targetingCriteriaName>My Ad Unit Name</targetingCriteriaName>
   <excluded>false</excluded>
   <availableUnits>1000</availableUnits>
   <matchedUnits>2300</matchedUnits>
</targetingCriteriaBreakdowns>

É possível executar previsões de disponibilidade em linhas existentes ou em potencial do item de linha.

Item de linha existente

É possível executar uma previsão de disponibilidade para um item de linha existente usando o ID dele.

Java

  // Get the ForecastService.
  ForecastServiceInterface forecastService =
      adManagerServices.get(session, ForecastServiceInterface.class);

  // Get forecast for line item.
  AvailabilityForecastOptions options = new AvailabilityForecastOptions();
  options.setIncludeContendingLineItems(true);
  options.setIncludeTargetingCriteriaBreakdown(true);
  AvailabilityForecast forecast =
      forecastService.getAvailabilityForecastById(lineItemId, options);

  long matched = forecast.getMatchedUnits();
  double availablePercent = (forecast.getAvailableUnits() / (matched * 1.0)) * 100;
  String unitType = forecast.getUnitType().toString().toLowerCase();

  System.out.printf("%d %s matched.%n", matched, unitType);
  System.out.printf("%.2f%% %s available.%n", availablePercent, unitType);

  if (forecast.getPossibleUnits() != null) {
    double possiblePercent = (forecast.getPossibleUnits() / (matched * 1.0)) * 100;
    System.out.printf("%.2f%% %s possible.%n", possiblePercent, unitType);
  }

  System.out.printf(
      "%d contending line items.%n",
      forecast.getContendingLineItems() == null ? 0 : forecast.getContendingLineItems().length);

Python

  # Initialize appropriate service.
  forecast_service = client.GetService('ForecastService', version='v202408')

  # Set forecasting options.
  forecast_options = {
      'includeContendingLineItems': True,
      'includeTargetingCriteriaBreakdown': True,
  }

  # Get forecast for line item.
  forecast = forecast_service.getAvailabilityForecastById(
      line_item_id, forecast_options)
  matched = int(forecast['matchedUnits'])
  available_units = int(forecast['availableUnits'])

  if matched > 0:
    available_percent = (float(available_units) / matched) * 100.
  else:
    available_percent = 0

  contending_line_items = getattr(forecast, 'contentingLineItems', [])

  # Display results.
  print('%s %s matched.' % (matched, forecast['unitType'].lower()))
  print('%s%% %s available.' % (
      available_percent, forecast['unitType'].lower()))
  print('%d contending line items.' % len(contending_line_items))

  if 'possibleUnits' in forecast and matched:
    possible_percent = (int(forecast['possibleUnits'])/float(matched)) * 100.
    print('%s%% %s possible' % (possible_percent, forecast['unitType'].lower()))

PHP

      $forecastService = $serviceFactory->createForecastService($session);

      // Get forecast for line item.
      $options = new AvailabilityForecastOptions();
      $options->setIncludeContendingLineItems(true);
      $options->setIncludeTargetingCriteriaBreakdown(true);
      $forecast = $forecastService->getAvailabilityForecastById(
          $lineItemId,
          $options
      );

      // Print out forecast results.
      $matchedUnits = $forecast->getMatchedUnits();
      $unitType = strtolower($forecast->getUnitType());
      printf("%d %s matched.%s", $matchedUnits, $unitType, PHP_EOL);

      if ($matchedUnits > 0) {
          $availableUnits = $forecast->getAvailableUnits();
          $percentAvailableUnits = $availableUnits / $matchedUnits * 100;
          $possibleUnits = $forecast->getPossibleUnits();
          $percentPossibleUnits = $possibleUnits / $matchedUnits * 100;
          printf(
              "%.2d%% %s available.%s",
              $percentAvailableUnits,
              $unitType,
              PHP_EOL
          );
          printf(
              "%.2d%% %s possible.%s",
              $percentPossibleUnits,
              $unitType,
              PHP_EOL
          );
      }

      printf(
          "%d contending line items.%s",
          count($forecast->getContendingLineItems()),
          PHP_EOL
      );

C#

using (ForecastService forecastService = user.GetService<ForecastService>())
{
// Get forecast for line item.
AvailabilityForecastOptions options = new AvailabilityForecastOptions();
options.includeContendingLineItems = true;
options.includeTargetingCriteriaBreakdown = true;
AvailabilityForecast forecast =
    forecastService.getAvailabilityForecastById(lineItemId, options);

// Display results.
long matched = forecast.matchedUnits;
double availablePercent =
    (double) (forecast.availableUnits / (matched * 1.0)) * 100;
String unitType = forecast.unitType.ToString().ToLower();

Console.WriteLine("{0} {1} matched.\n{2} % {3} available.", matched, unitType,
    availablePercent, unitType);
if (forecast.possibleUnitsSpecified)
{
    double possiblePercent =
        (double) (forecast.possibleUnits / (matched * 1.0)) * 100;
    Console.WriteLine(possiblePercent + "% " + unitType + " possible.\n");
}

Console.WriteLine("{0} contending line items.",
    (forecast.contendingLineItems != null)
        ? forecast.contendingLineItems.Length
        : 0);

Ruby

  # Get the ForecastService.
  forecast_service = ad_manager.service(:ForecastService, API_VERSION)
  # Set forecasting options.
  forecast_options = {
    :include_contending_line_items => True,
    :include_targeting_criteria_breakdown => True,
  }

  # Get forecast for the line item.
  forecast = forecast_service.get_availability_forecast_by_id(
      line_item_id, forecast_options
  )

  unless forecast.nil?
    # Display results.
    matched = forecast[:matched_units]
    available_percent = forecast[:available_units] * 100.0 / matched
    unit_type = forecast[:unit_type].to_s.downcase
    puts '%.2f %s matched.' % [matched, unit_type]
    puts '%.2f%% of %s available.' % [available_percent, unit_type]
    puts '%d contending line items.' % forecast[:contending_line_items].size
    unless forecast[:possible_units].nil?
      possible_percent = forecast[:possible_units] * 100.0 / matched
      puts '%.2f%% of %s possible.' % [possible_percent, unit_type]
    end
  end

Este exemplo terá uma saída semelhante a esta:

100 clicks matched.
2 contending line items.

Item de linha prospectivo

Como alternativa, é possível instanciar um item de linha em potencial e uma previsão sem persistem. Para isso, instancie um objeto de item de linha local e defina-o no ProspectiveLineItem. Se você definir um ID de anunciante, a previsão também usará o bloqueio unificado padrão em conta.

Java

  // Get forecast for prospective line item.
  ProspectiveLineItem prospectiveLineItem = new ProspectiveLineItem();
  prospectiveLineItem.setAdvertiserId(advertiserId);
  prospectiveLineItem.setLineItem(lineItem);
  AvailabilityForecastOptions options = new AvailabilityForecastOptions();
  options.setIncludeContendingLineItems(true);
  options.setIncludeTargetingCriteriaBreakdown(true);

  AvailabilityForecast forecast =
      forecastService.getAvailabilityForecast(prospectiveLineItem, options);

Python

  prospective_line_item = {
      'lineItem': line_item,
      'advertiserId': advertiser_id
  }

  # Set forecasting options.
  forecast_options = {
      'includeContendingLineItems': True,
      # The field includeTargetingCriteriaBreakdown can only be set if
      # breakdowns are not manually specified.
      # 'includeTargetingCriteriaBreakdown': True,
      'breakdown': {
          'timeWindows': [
              now_datetime,
              now_datetime + datetime.timedelta(days=1),
              now_datetime + datetime.timedelta(days=2),
              now_datetime + datetime.timedelta(days=3),
              now_datetime + datetime.timedelta(days=4),
              end_datetime
          ],
          'targets': [
              {
                  # Optional, the name field is only used to identify this
                  # breakdown in the response.
                  'name': 'United States',
                  'targeting': {
                      'inventoryTargeting': {
                          'targetedAdUnits': [
                              {
                                  'includeDescendants': True,
                                  'adUnitId': root_ad_unit_id,
                              }
                          ]
                      },
                      'geoTargeting': {
                          'targetedLocations': [
                              {
                                  'id': '2840',
                                  'displayName': 'US'
                              }
                          ]
                      }
                  }
              },
              {
                  # Optional, the name field is only used to identify this
                  # breakdown in the response.
                  'name': 'Geneva',
                  'targeting': {
                      'inventoryTargeting': {
                          'targetedAdUnits': [
                              {
                                  'includeDescendants': True,
                                  'adUnitId': root_ad_unit_id,
                              }
                          ]
                      },
                      'geoTargeting': {
                          'targetedLocations': [
                              {
                                  'id': '20133',
                                  'displayName': 'Geneva'
                              }
                          ]
                      }
                  }
              }
          ]
      }
  }

  # Get forecast.
  forecast = forecast_service.getAvailabilityForecast(
      prospective_line_item, forecast_options)

PHP

      // Get forecast for prospective line item.
      $prospectiveLineItem = new ProspectiveLineItem();
      $prospectiveLineItem->setAdvertiserId($advertiserId);
      $prospectiveLineItem->setLineItem($lineItem);
      $options = new AvailabilityForecastOptions();
      $options->setIncludeContendingLineItems(true);
      $options->setIncludeTargetingCriteriaBreakdown(true);

      $forecast = $forecastService->getAvailabilityForecast(
          $prospectiveLineItem,
          $options
      );

C#

// Get availability forecast.
AvailabilityForecastOptions options = new AvailabilityForecastOptions()
{
    includeContendingLineItems = true,
    // Targeting criteria breakdown can only be included if breakdowns
    // are not speficied.
    includeTargetingCriteriaBreakdown = false,
    breakdown = new ForecastBreakdownOptions
    {
        timeWindows = new DateTime[] {
            lineItem.startDateTime,
            DateTimeUtilities.FromDateTime(tomorrow.AddDays(1),
                "America/New_York"),
            DateTimeUtilities.FromDateTime(tomorrow.AddDays(2),
                "America/New_York"),
            DateTimeUtilities.FromDateTime(tomorrow.AddDays(3),
                "America/New_York"),
            DateTimeUtilities.FromDateTime(tomorrow.AddDays(4),
                "America/New_York"),
            lineItem.endDateTime
        },
        targets = new ForecastBreakdownTarget[] {
            new ForecastBreakdownTarget()
            {
                // Optional name field to identify this breakdown
                // in the response.
                name = "United States",
                targeting = new Targeting()
                {
                    inventoryTargeting = new InventoryTargeting()
                    {
                        targetedAdUnits = new AdUnitTargeting[] {
                            new AdUnitTargeting()
                            {
                                adUnitId = rootAdUnitId,
                                includeDescendants = true
                            }
                        }
                    },
                    geoTargeting = new GeoTargeting()
                    {
                        targetedLocations = new Location[] {
                            new Location() { id = 2840L }
                        }
                    }
                }
            }, new ForecastBreakdownTarget()
            {
                // Optional name field to identify this breakdown
                // in the response.
                name = "Geneva",
                targeting = new Targeting()
                {
                    inventoryTargeting = new InventoryTargeting()
                    {
                        targetedAdUnits = new AdUnitTargeting[] {
                            new AdUnitTargeting()
                            {
                                adUnitId = rootAdUnitId,
                                includeDescendants = true
                            }
                        }
                    },
                    geoTargeting = new GeoTargeting()
                    {
                        targetedLocations = new Location[] {
                            new Location () { id = 20133L }
                        }
                    }
                }
            }
        }
    }
};
ProspectiveLineItem prospectiveLineItem = new ProspectiveLineItem()
{
    advertiserId = advertiserId,
    lineItem = lineItem
};
AvailabilityForecast forecast =
  forecastService.getAvailabilityForecast(prospectiveLineItem, options);

Ruby

  prospective_line_item = {
    :advertiser_id => advertiser_id,
    :line_item => line_item
  }

  # Set forecasting options.
  forecast_options = {
    :include_contending_line_items => true,
    # The field includeTargetingCriteriaBreakdown can only be set if breakdowns
    # are not mannually specified.
    # :include_targeting_criteria_breakdown => true,
    :breakdown => {
      # Break down forecast by day from start_time to end_time
      :time_windows => time_windows,
      # Break down forecast by any targeting configuration
      :targets => [
        {
          # Optional, the name field is only used to identify this breakdown in
          # the response.
          :name => 'United States',
          :targeting => {
            :inventory_targeting => targeting[:inventory_targeting],
            :geo_targeting => {
              :targeted_locations => [
                {
                  :id => '2840',
                  :display_name => 'US'
                }
              ]
            }
          }
        },
        {
          # Optional, the name field is only used to identify this breakdown in
          # the response.
          :name => 'Geneva',
          :targeting => {
            :inventory_targeting => targeting[:inventory_targeting],
            :geo_targeting => {
              :targeted_locations => [
                {
                  :id => '20133',
                  :display_name => 'Geneva'
                }
              ]
            }
          }
        }
      ]
    }
  }

  # Get forecast for the line item.
  forecast = forecast_service.get_availability_forecast(
      prospective_line_item, forecast_options)

Previsões de entrega

Se você quiser simular a exibição de vários itens de linha concorrentes, será possível faça isso com um DeliveryForecast.

Itens de linha existentes

Você pode executar uma previsão de exibição para itens de linha existentes usando seus IDs.

Java

  // Get the ForecastService.
  ForecastServiceInterface forecastService =
      adManagerServices.get(session, ForecastServiceInterface.class);

  DeliveryForecastOptions options = new DeliveryForecastOptions();

  DeliveryForecast forecast =
      forecastService.getDeliveryForecastByIds(Longs.toArray(lineItemIds), options);

  for (LineItemDeliveryForecast lineItemForecast : forecast.getLineItemDeliveryForecasts()) {
    String unitType = lineItemForecast.getUnitType().toString().toLowerCase();
    System.out.printf("Forecast for line item %d:%n", lineItemForecast.getLineItemId());
    System.out.printf("\t%d %s matched%n", lineItemForecast.getMatchedUnits(), unitType);
    System.out.printf("\t%d %s delivered%n", lineItemForecast.getDeliveredUnits(), unitType);
    System.out.printf(
        "\t%d %s predicted%n", lineItemForecast.getPredictedDeliveryUnits(), unitType);
  }

Python

  # Initialize appropriate service.
  forecast_service = client.GetService('ForecastService', version='v202408')

  # Get forecast for line item.
  forecast = forecast_service.getDeliveryForecastByIds(
      [line_item_id1, line_item_id2], {'ignoredLineItemIds': []})

  for single_forecast in forecast['lineItemDeliveryForecasts']:
    unit_type = single_forecast['unitType']
    print('Forecast for line item %d:\n\t%d %s matched\n\t%d %s delivered\n\t'
          '%d %s predicted\n' % (
              single_forecast['lineItemId'], single_forecast['matchedUnits'],
              unit_type, single_forecast['deliveredUnits'], unit_type,
              single_forecast['predictedDeliveryUnits'], unit_type))


if __name__ == '__main__':
  # Initialize client object.
  ad_manager_client = ad_manager.AdManagerClient.LoadFromStorage()
  main(ad_manager_client, LINE_ITEM_ID_1, LINE_ITEM_ID_2)

PHP

      $forecastService = $serviceFactory->createForecastService($session);

      // Get forecast for the line items with no options set.
      $forecast = $forecastService->getDeliveryForecastByIds(
          [$lineItemId1, $lineItemId2],
          new DeliveryForecastOptions()
      );

      // Print out forecast results.
      $lineItemDeliveryForecasts = $forecast->getLineItemDeliveryForecasts();
      foreach ($lineItemDeliveryForecasts as $lineItemForecast) {
          $unitType = strtolower($lineItemForecast->getUnitType());
          printf(
              "Forecast for line item ID %d:%s",
              $lineItemForecast->getLineItemId(),
              PHP_EOL
          );
          printf(
              "    %d %s matched%s",
              $lineItemForecast->getMatchedUnits(),
              $unitType,
              PHP_EOL
          );
          printf(
              "    %d %s delivered%s",
              $lineItemForecast->getDeliveredUnits(),
              $unitType,
              PHP_EOL
          );
          printf(
              "    %d %s predicted%s",
              $lineItemForecast->getPredictedDeliveryUnits(),
              $unitType,
              PHP_EOL
          );
      }

C#

using (ForecastService forecastService = user.GetService<ForecastService>())
{
// Get a delivery forecast for the line items.
DeliveryForecastOptions options = new DeliveryForecastOptions();
options.ignoredLineItemIds = new long[]
{
};
DeliveryForecast forecast = forecastService.getDeliveryForecastByIds(new long[]
{
    lineItemId1,
    lineItemId2
}, options);

// Display results.
foreach (LineItemDeliveryForecast lineItemForecast in forecast
    .lineItemDeliveryForecasts)
{
    String unitType = lineItemForecast.unitType.GetType().Name.ToLower();
    Console.WriteLine("Forecast for line item {0}:",
        lineItemForecast.lineItemId);
    Console.WriteLine("\t{0} {1} matched", lineItemForecast.matchedUnits,
        unitType);
    Console.WriteLine("\t{0} {1} delivered", lineItemForecast.deliveredUnits,
        unitType);
    Console.WriteLine("\t{0} {1} predicted",
        lineItemForecast.predictedDeliveryUnits, unitType);
}

Ruby

  # Get the ForecastService.
  forecast_service = ad_manager.service(:ForecastService, API_VERSION)
  # Get forecast for the line item.
  forecast = forecast_service.get_delivery_forecast_by_ids(
      [line_item_id1, line_item_id2], nil)

  unless forecast.nil? || forecast[:line_item_delivery_forecasts].nil?
    forecast[:line_item_delivery_forecasts].each do |single_forecast|
      # Display results.
      unit_type = single_forecast[:unit_type]
      puts ('Forecast for line item %d:\n\t%d %s matched\n\t%d %s ' +
          'delivered\n\t%d %s predicted\n') % [single_forecast[:line_item_id],
          single_forecast[:matched_units], unit_type,
          single_forecast[:delivered_units], unit_type,
          single_forecast[:predicted_delivery_units], unit_type]
    end
  end

Este exemplo terá uma saída semelhante a esta:

Forecast for line item 14678:
    100 clicks matched
    0 clicks delivered
    98 clicks predicted

Se você quiser excluir itens de linha da simulação de exibição, Portanto, ao definir seus IDs na DeliveryForecastOptions.

Itens de linha em potencial

Assim como as previsões de disponibilidade, é possível fazer previsões de entrega on-line itens que não são mantidos. Para fazer isso, use objetos ProspectiveLineItem no método ForecastService.getDeliveryForecast.

Relatórios de futuras vendas por distribuidores

O relatório de venda por distribuidores futuros prevê a disponibilidade de impressões para o rede do Google Ad Manager para garantir a maximização da receita e a taxa de venda por distribuidores. Os relatórios de venda por distribuidores futuros podem ser gerados por ReportService.

Perguntas frequentes

Tenho muitos itens de linha para os quais quero prever a disponibilidade. Posso executar várias previsões em uma solicitação?
Não É necessário fazer uma solicitação de previsão de disponibilidade separada para cada linha ou item de linha em potencial.
Realizei uma série de previsões e agora estou recebendo EXCEEDED_LENGTH erros. What gives?
As previsões são caras em termos computacionais, e o sistema de cotas garante o serviço é confiável. Você pode esperar e tentar de novo com segurança as previsões que resultaram em um erro de cota.
O que causa os erros NO_FORECAST_YET ou NOT_ENOUGH_INVENTORY?
As previsões são executadas com base no tráfego da sua rede histórico. Às vezes, não há dados históricos suficientes para gerar uma previsão. Para mais sobre esses erros, consulte a ForecastError na documentação do Google Cloud.
O que é um AlternativeUnitType havia?
Às vezes, é útil saber quais outros inventários estão disponíveis. Para exemplo, ao fazer a previsão para um Linha CPC item, o tipo de unidade alternativa previsões incluirá informações sobre o número de impressões.
Tenho mais dúvidas sobre a previsão do Ad Manager em geral.
Confira se elas estão incluídas nas Perguntas frequentes do produto ou faça uma pergunta no nosso fórum de desenvolvedores.