Прогнозирование

Введение

В этом руководстве объясняются различные способы использования прогнозирования в API Google Ad Manager.

Прогноз трафика

Прогноз трафика позволяет вам анализировать исторический трафик, а также будущие возможности показов, чтобы найти более эффективные способы сегментации и упаковки ресурсов.

Ява 

// 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);

Питон 

# 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);

С# 

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);

Руби 

# 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
  }
})

Прогнозы доступности

AvailabilityForecast сообщает о максимальном количестве доступных единиц, в которых можно забронировать позицию. Этот прогноз аналогичен функции проверки запасов в пользовательском интерфейсе.

Прогноз включает доступные, сопоставленные, возможные, доставленные и зарезервированные единицы. Он также может включать все конкурирующие позиции и доступные единицы для каждой разбивки таргетинга в зависимости от параметров, установленных в AvailabilityForecastOptions . По умолчанию ни один из них не включен в прогноз.

Разбивка таргетинга включает подходящие и доступные единицы для каждого критерия таргетинга. Эти записи разбивки создаются автоматически в соответствии с таргетингом позиции. Например, позиция с таргетингом на рекламный блок с идентификатором 123456 будет иметь следующую разбивку:

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

Прогнозы доступности можно выполнять как для существующей, так и для потенциальной позиции.

Существующая позиция

Вы можете выполнить прогноз доступности для существующей позиции, используя ее идентификатор.

Ява 

  // 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);

Питон 

  # 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
      );

С# 

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);

Руби 

  # 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

Этот пример будет иметь вывод, аналогичный следующему: 

100 clicks matched.
2 contending line items.

Потенциальная позиция

Альтернативно вы можете создать экземпляр потенциальной позиции и спрогнозировать ее, не сохраняя ее. Для этого создайте экземпляр объекта локальной позиции и установите его в ProspectiveLineItem . Если вы зададите идентификатор рекламодателя, в прогнозе также будут учитываться единые правила блокировки .

Ява 

  // 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);

Питон 

  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
      );

С# 

// 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);

Руби 

  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)

Прогнозы доставки

Если вы хотите имитировать показ нескольких конкурирующих позиций, вы можете сделать это с помощью DeliveryForecast .

Существующие позиции

Вы можете выполнить прогноз показов для существующих позиций, используя их идентификаторы.

Ява 

  // 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);
  }

Питон 

  # 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
          );
      }

С# 

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);
}

Руби 

  # 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

Этот пример будет иметь вывод, аналогичный следующему: 

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

Если вы хотите исключить какие-либо позиции из моделирования показа, вы можете сделать это, задав их идентификаторы в свойстве DeliveryForecastOptions .

Потенциальные позиции

Подобно прогнозам доступности, вы можете запускать прогнозы показов для несохраняемых позиций. Для этого используйте объекты ProspectiveLineItem в методе ForecastService.getDeliveryForecast .

Отчеты о будущих сквозных продажах

В отчете о будущих сквозных продажах прогнозируется доступность показов для вашей сети Google Ad Manager, поэтому вы можете быть уверены, что максимизируете доход и коэффициент сквозных продаж. Отчеты о будущих сквозных продажах можно создавать через ReportService .

Часто задаваемые вопросы

У меня есть много позиций, для которых я хочу спрогнозировать доступность. Могу ли я запустить несколько прогнозов в одном запросе?
Нет. Вы должны сделать отдельный запрос на прогноз доступности для каждой позиции или потенциальной позиции.
Я выполнил несколько прогнозов и теперь получаю ошибки EXCEEDED_QUOTA. Что дает?
Прогнозы требуют больших вычислительных затрат, а система квот обеспечивает надежность услуги. Вы можете спокойно подождать и повторить любые прогнозы, которые привели к ошибке квоты.
Что вызывает ошибки NO_FORECAST_YET или NOT_ENOUGH_INVENTORY?
Прогнозы составляются на основе истории трафика вашей сети . Иногда для составления прогноза недостаточно исторических данных. Дополнительные сведения об этих ошибках см. в документации ForecastError .
Что такое AlternativeUnitTypeForecast?
Иногда полезно знать, какой еще инвентарь доступен. Например, при прогнозировании позиции с ценой за клик прогнозы альтернативного типа единицы будут включать информацию о количестве показов.
У меня есть еще вопросы о прогнозировании Менеджера рекламы в целом.
Посмотрите, описаны ли они в разделе часто задаваемых вопросов по продукту , или задайте вопрос на нашем форуме разработчиков .