Introducción
En esta guía, se explican las diferentes maneras de usar la previsión en la API de Google Ad Manager.
Previsión del tráfico
Una previsión del tráfico te permite leer el tráfico histórico junto con las oportunidades de impresiones futuras para encontrar mejores formas de segmentar y empaquetar el inventario.
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
}
})
Previsiones de disponibilidad
Un objeto AvailabilityForecast informa la cantidad máxima de unidades disponibles con las que se puede reservar la línea de pedido. Esta previsión es análoga a la función Verificar inventario de la IU.
La previsión incluye las unidades disponibles, coincidentes, posibles, publicadas y reservadas. También puede incluir todas las líneas de pedido rivales y las unidades disponibles para cada desglose de segmentación según las opciones establecidas en AvailabilityForecastOptions. De forma predeterminada, no se incluye ninguno en la previsión.
Los desgloses de segmentación incluyen las unidades coincidentes y disponibles para cada criterio de segmentación. Estas entradas de desglose se generan automáticamente según la segmentación de la línea de pedido. Por ejemplo, una línea de pedido segmentada para el ID de unidad de anuncios 123456 incluiría un desglose similar al siguiente:
<targetingCriteriaBreakdowns> <targetingDimension>AD_UNIT</targetingDimension> <targetingCriteriaId>123456</targetingCriteriaId> <targetingCriteriaName>My Ad Unit Name</targetingCriteriaName> <excluded>false</excluded> <availableUnits>1000</availableUnits> <matchedUnits>2300</matchedUnits> </targetingCriteriaBreakdowns>
Puedes ejecutar previsiones de disponibilidad en una línea de pedido existente o potencial.
Línea de pedido existente
Puedes ejecutar una previsión de disponibilidad para una línea de pedido existente con su ID.
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='v202402')
# 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
En este ejemplo, tendrá un resultado similar al siguiente:
100 clicks matched.
2 contending line items.
Línea de pedido potencial
Como alternativa, puedes crear una instancia de una línea de pedido potencial y prever sin mantenerla. Para ello, crea una instancia de un objeto de línea de pedido local y configúralo en ProspectiveLineItem. Si estableces un ID de anunciante, la previsión también tendrá en cuenta las reglas de bloqueo unificadas.
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)
Previsiones de publicación
Si deseas simular la publicación de varias líneas de pedido que compiten, puedes hacerlo con DeliveryForecast.
Líneas de pedido existentes
Puedes ejecutar una previsión de publicación para líneas de pedido existentes mediante sus 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='v202402')
# 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
En este ejemplo, tendrá un resultado similar al siguiente:
Forecast for line item 14678:
100 clicks matched
0 clicks delivered
98 clicks predicted
Si deseas excluir líneas de pedido de la simulación de publicación, puedes configurar sus ID en DeliveryForecastOptions.
Líneas de pedido potenciales
Al igual que con las previsiones de disponibilidad, puedes ejecutar previsiones de publicación en líneas de pedido que no son persistentes. Para hacerlo, usa los objetos ProspectiveLineItem en el método ForecastService.getDeliveryForecast.
Informes de venta directa futura
El informe de venta directa futura predice la disponibilidad de las impresiones para tu red de Google Ad Manager a fin de que puedas asegurarte de maximizar los ingresos y la tasa de venta directa. Los informes de venta directa futura se pueden ejecutar mediante ReportService.
Preguntas frecuentes
- Tengo muchas líneas de pedido para las que quiero prever la disponibilidad. ¿Puedo ejecutar varias previsiones en una solicitud?
- No. Debes realizar una solicitud de previsión de disponibilidad por separado para cada línea de pedido o línea de pedido potencial.
- Realicé varias previsiones y ahora recibo EXCEEDED_QUOTA errores. ¿Para qué me sirve esto?
- Las previsiones son costosas en términos de procesamiento y el sistema de cuotas garantiza que el servicio sea confiable. Puedes esperar de forma segura y volver a intentar cualquier previsión que haya generado un error de cuota.
- ¿Qué causa los errores NO_FORECAST_YET o NOT_ENOUGH_INVENTORY?
- Las previsiones se ejecutan según el historial de tráfico de tu red. A veces, no hay suficientes datos históricos para ejecutar una previsión. Para obtener más detalles sobre estos errores, consulta la documentación sobre ForecastError.
- ¿Qué es una AlternativeUnitTypeForecast?
- A veces es útil saber qué otro inventario está disponible. Por ejemplo, cuando realices una previsión para una línea de pedido de CPC, las previsiones de tipos de unidades alternativas incluirán información sobre la cantidad de impresiones.
- Tengo más preguntas sobre la previsión de Ad Manager en general.
- Consulta si se abordan en las Preguntas frecuentes sobre el producto o consulta en nuestro foro para desarrolladores.