簡介
本指南將說明 預測 Manager API。
流量預測
流量預測可讓您 讀取歷來流量和未來曝光機會 如何區隔與包裝廣告空間
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);
小茹
# 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。 根據預設，兩者都不會納入預測中。
指定目標細目包括每個指定目標的相符及可用單元 標準。系統會根據 委刊項指定目標例如，指定廣告單元 ID 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>
您可以針對現有或未來的委刊項執行供應量預測 項目。
現有委刊項
您可以使用現有委刊項的 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='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);
小茹
# 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。 如果您設定廣告主 ID，預測也會採用統一封鎖功能 規則納入考量
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);
小茹
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。
現有委刊項
您可以使用現有委刊項的 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='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);
}
小茹
# 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.
潛在委刊項
與供應量預測相同，您可以逐行執行放送預測 不會保存的項目方法是使用 ForecastService.getDeliveryForecast 方法。
未來成交率報表
未來成交率報表 能預測有多少可用曝光 Google Ad Manager 聯播網 確保盡量提高收益 成交率未來成交率報表可以透過 ReportService。
常見問題
- 我有許多委刊項想要預測可用性，在單一請求中執行多項預測嗎？
- 不可以。您必須分別為每一行提出供應量預測要求 或潛在委刊項
- 我執行過大量的預測，現在收到 EXCEEDED_QUOTA 個錯誤。優點
- 預測作業的運算成本高昂，而且配額系統可確保 可靠性相當可靠您可以放心地等待系統產生任何預測結果 而非配額錯誤
- 造成 NO_FORECAST_YET 或 NOT_ENOUGH_INVENTORY 錯誤的原因為何？
- 系統會根據您的聯播網流量執行預測 記錄。 有時候，歷來資料不足，無法進行預測。如要 如要進一步瞭解這些錯誤，請參閱 ForecastError 說明文件。
- 什麼是 AlternativeUnitTypeForecast？
- 有時瞭解還有哪些廣告空間會有幫助。適用對象 例如預測 CPC 行 項目，替代單位類型 預測 當中包含曝光次數資訊。
- 一般來說，我對 Ad Manager 預測功能有其他疑問。
- 看看產品是否已納入產品中 常見問題，或向我們開發人員提問 論壇。