Introduzione
Questa guida illustra i diversi modi di utilizzare la previsione nell'API Google Ad Manager.
Previsione di traffico
Una previsione del traffico ti consente di leggere il traffico storico insieme alle opportunità di impressioni future per determinare meglio i metodi per segmentare e pacchettizzare l'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
}
})
Previsioni di disponibilità
Un elemento AvailabilityForecast indica il numero massimo di unità disponibili con cui è possibile prenotare l'elemento pubblicitario. Questa previsione è analoga alla funzionalità Verifica inventario nell'interfaccia utente.
La previsione include le unità disponibili, corrispondenti, possibili, pubblicate e prenotate. Può anche includere tutti gli elementi pubblicitari concorrenti e le unità disponibili per ogni analisi del targeting, a seconda delle opzioni impostate in AvailabilityForecastOptions. Per impostazione predefinita, nessuno dei due è incluso nella previsione.
La suddivisione del targeting include le unità corrispondenti e disponibili per ciascun criterio di targeting. Queste voci di suddivisione vengono generate automaticamente in base al targeting dell'elemento pubblicitario. Ad esempio, un elemento pubblicitario che ha come target l'ID unità pubblicitaria 123456 includerà una suddivisione simile alla seguente:
<targetingCriteriaBreakdowns> <targetingDimension>AD_UNIT</targetingDimension> <targetingCriteriaId>123456</targetingCriteriaId> <targetingCriteriaName>My Ad Unit Name</targetingCriteriaName> <excluded>false</excluded> <availableUnits>1000</availableUnits> <matchedUnits>2300</matchedUnits> </targetingCriteriaBreakdowns>
Puoi eseguire previsioni di disponibilità su un elemento pubblicitario esistente o potenziale.
Elemento pubblicitario esistente
Puoi eseguire una previsione disponibilità per un elemento pubblicitario esistente utilizzando il relativo 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
Questo esempio avrà un output simile al seguente:
100 clicks matched.
2 contending line items.
Elemento pubblicitario potenziale
In alternativa, puoi creare un'istanza di un potenziale elemento pubblicitario e di eseguire una previsione senza creare un'istanza permanente. A questo scopo, crea un'istanza di un oggetto elemento pubblicitario locale e impostalo su ProspectiveLineItem. Se imposti un ID inserzionista, la previsione prende in considerazione anche le regole di blocco unificate.
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)
Previsioni di pubblicazione
Se vuoi simulare la pubblicazione di più elementi pubblicitari concorrenti, puoi farlo con una DeliveryForecast.
Elementi pubblicitari esistenti
Puoi eseguire una previsione di pubblicazione per gli elementi pubblicitari esistenti utilizzando i relativi ID.
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
Questo esempio avrà un output simile al seguente:
Forecast for line item 14678:
100 clicks matched
0 clicks delivered
98 clicks predicted
Se vuoi escludere degli elementi pubblicitari dalla simulazione di pubblicazione, puoi farlo impostando i relativi ID nel campo DeliveryForecastOptions.
Elementi pubblicitari potenziali
Analogamente alle previsioni di disponibilità, puoi eseguire previsioni di pubblicazione per gli elementi pubblicitari non persistenti. A questo scopo, utilizza gli oggetti ProspectiveLineItem nel metodo ForecastService.getDeliveryForecast.
Report sell-through futuri
Il report sell-through futuro prevede la disponibilità delle impressioni per la tua rete Google Ad Manager, consentendoti di massimizzare le entrate e la percentuale di sell-through. I report sell-through futuri possono essere creati tramite ReportService.
Domande frequenti
- Ho molti elementi pubblicitari per i quali desidero prevedere la disponibilità. Posso eseguire più previsioni in una singola richiesta?
- No. Devi effettuare una richiesta di previsione della disponibilità distinta per ciascun elemento pubblicitario o potenziale elemento pubblicitario.
- Ho eseguito una serie di previsioni e ora ricevo EXCEEDED_QUOTA errori. What gives?
- Le previsioni sono costose dal punto di vista del calcolo e il sistema di quote garantisce l'affidabilità del servizio. Puoi attendere e riprovare in sicurezza qualsiasi previsione che abbia generato un errore di quota.
- Quali sono le cause degli errori NO_FORECAST_YET o NOT_ENOUGH_INVENTORY?
- Le previsioni vengono eseguite in base alla cronologia del traffico della tua rete. A volte, i dati storici non sono sufficienti per eseguire una previsione. Per ulteriori dettagli su questi errori, consulta la documentazione ForecastError.
- Che cos'è AlternativeUnitType Forecast?
- A volte è utile sapere quale altro inventario è disponibile. Ad esempio, durante la previsione di un elemento pubblicitario CPC, le previsioni del tipo di unità alternativo includeranno informazioni sul numero di impressioni.
- Ho altre domande sulle previsioni di Ad Manager in generale.
- Scopri se sono coperti dalle domande frequenti sul prodotto oppure poni domande nel nostro forum per gli sviluppatori.