מבוא
במדריך הזה מוסברות הדרכים השונות להשתמש בתחזיות ב-Google Ad 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);
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 } })
תחזיות לגבי זמינות שטחי הפרסום
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>
אפשר להריץ תחזיות לגבי זמינות שטחי הפרסום על פריט קיים או על פריט פוטנציאלי.
פריט קיים
אתם יכולים להריץ תחזית לגבי זמינות שטחי הפרסום של פריט קיים באמצעות המזהה שלו.
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='v202608') # 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
הפלט של הדוגמה הזו אמור להיראות כך:
100 clicks matched.
2 contending line items.
פריט פוטנציאלי
לחלופין, אפשר ליצור מופע של פריט פוטנציאלי ולחזות בלי לשמור אותו. כדי לעשות את זה, יוצרים מופע של אובייקט פריט מקומי ומגדירים אותו ב-ProspectiveLineItem. אם מגדירים מזהה מפרסם, התחזית מביאה בחשבון גם כללי חסימה מאוחדים.
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)
תחזיות מסירה
אם רוצים לדמות את הצגת המודעות של כמה פריטים מתחרים, אפשר לעשות זאת באמצעות DeliveryForecast.
פריטים קיימים
אתם יכולים להריץ תחזית הצגה לפריטים קיימים באמצעות המזהים שלהם.
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='v202608') # 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
הפלט של הדוגמה הזו אמור להיראות כך:
Forecast for line item 14678:
100 clicks matched
0 clicks delivered
98 clicks predicted
אם אתם רוצים להחריג פריטים מסוימים מהסימולציה של הצגת המודעות, אתם יכולים להגדיר את המזהים שלהם ב-DeliveryForecastOptions.
פריטים פוטנציאליים
בדומה לתחזיות לגבי זמינות שטחי הפרסום, אפשר להריץ תחזיות לגבי הצגת מודעות על פריטים שלא נשמרו. כדי לעשות את זה, משתמשים באובייקטים מסוג ProspectiveLineItem ב-method ForecastService.getDeliveryForecast.
דוחות מכירות עתידיות בפועל
הדוח "מכירה עתידית" חוזה את הזמינות של החשיפות ברשת Google Ad Manager, כדי שתוכלו לוודא שאתם ממקסמים את ההכנסות ואת שיעור המכירה. אפשר להריץ דוחות של מכירות עתידיות בפועל דרך ReportService.
שאלות נפוצות
- יש לי הרבה פריטים שאני רוצה לחזות את הזמינות שלהם. האם אפשר להריץ כמה תחזיות בבקשה אחת?
- לא. צריך לשלוח בקשה נפרדת לתחזית לגבי זמינות שטחי הפרסום לכל פריט או פריט פוטנציאלי.
- הרצתי כמה תחזיות ועכשיו אני מקבל שגיאות EXCEEDED_QUOTA. מה קורה?
- התחזיות דורשות משאבי מחשוב רבים, ומערכת המכסות מבטיחה שהשירות יהיה אמין. אפשר להמתין ולנסות שוב להריץ תחזיות שגרמו לשגיאת מכסה.
- מה גורם לשגיאות NO_FORECAST_YET או NOT_ENOUGH_INVENTORY?
- התחזיות מופעלות על סמך היסטוריית התנועה של הרשת. לפעמים אין מספיק נתונים היסטוריים כדי להריץ תחזית. לפרטים נוספים על השגיאות האלה, אפשר לעיין במסמכי התיעוד של ForecastError.
- מה זה AlternativeUnitTypeForecast?
- לפעמים כדאי לדעת איזה מלאי נוסף זמין. לדוגמה, כשיוצרים תחזית לפריט עלות לקליק, התחזיות לסוגי יחידות חלופיים יכללו מידע על מספר החשיפות.
- יש לי עוד שאלות על תחזיות ב-Ad Manager באופן כללי.
- אפשר לבדוק אם יש תשובות בשאלות הנפוצות על המוצר, או לשאול בעזרה מהקהילה של Ad Manager. אם נתקלתם בבעיות ספציפיות, אתם יכולים לפנות לתמיכה של Ad Manager API.