مقدمه
این راهنما روشهای مختلف استفاده از پیشبینی را در Google Ad Manager API توضیح میدهد.
پیشبینی ترافیک
پیشبینی ترافیک به شما امکان میدهد ترافیک گذشته را در کنار فرصتهای ظهور آینده بخوانید تا راههای بهتری برای بخشبندی و بستهبندی فضای آگهی پیدا کنید.
جاوا
// 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>
میتوانید پیشبینیهای دردسترس بودن را روی یک مورد خطی موجود یا احتمالی اجرا کنید.
مورد سطری موجود
میتوانید بااستفاده از شناسه یک ردیف هدف موجود، پیشبینی دردسترس بودن را برای آن اجرا کنید.
جاوا
// 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 تنظیم کنید. اگر شناسه آگهیدهنده تنظیم کنید، پیشبینی قوانین مسدودسازی یکپارچه را نیز درنظر میگیرد.
جاوا
// 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 انجام دهید.
موارد سطری موجود
میتوانید بااستفاده از شناسههای ردیفهای موجود، پیشبینی تحویل را برای آنها اجرا کنید.
جاوا
// 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 در روش ForecastService.getDeliveryForecast استفاده کنید.
گزارشهای نرخ فروش آینده
گزارش فروش مستقیم آتی دردسترس بودن ظهورها را برای شبکه Google Ad Manager شما پیشبینی میکند تا بتوانید مطمئن شوید که درآمد و نرخ فروش مستقیم را بهحداکثر میرسانید. گزارشهای نرخ فروش آینده را میتوان ازطریق ReportService اجرا کرد.
پرسشگان
- ردیفهای زیادی دارم که میخواهم دردسترس بودن آنها را پیشبینی کنم. آیا میتوانم چندین پیشبینی را در یک درخواست اجرا کنم؟
- نه. باید برای هر مورد سند اطلاعات یا مورد سند اطلاعات احتمالی، درخواست پیشبینی دردسترس بودن جداگانهای ایجاد کنید.
- تعدادی پیشبینی اجرا کردم و اکنون خطای EXCEEDED_QUOTA (فراتر از سهمیه) دریافت میکنم. چه خبر است؟
- پیشبینیها ازنظر محاسباتی پرهزینه هستند و سیستم سهمیه اطمینان میدهد که سرویس قابلاعتماد است. میتوانید با خیال راحت منتظر بمانید و هر پیشبینیای را که منجر به خطای سهمیه شده است دوباره امتحان کنید.
- چه چیزی باعث خطاهای NO_FORECAST_YET یا NOT_ENOUGH_INVENTORY میشود؟
- پیشبینیها براساس سابقه ترافیک شبکهتان اجرا میشوند. گاهی اوقات، دادههای قدیمی کافی برای اجرای پیشبینی وجود ندارد. برای جزئیات بیشتر درباره این خطاها، به سند ForecastError مراجعه کنید.
- AlternativeUnitTypeForecast چیست؟
- گاهی اوقات مفید است که بدانید چه موجودی دیگری دردسترس است. برای مثال، هنگام پیشبینی برای یک مورد خطی CPC، پیشبینیهای نوع واحد جایگزین شامل اطلاعاتی درباره تعداد ظهورها خواهد بود.
- درباره پیشبینی Ad Manager بهطور کلی سؤالات بیشتری دارم.
- ببینید آیا در پرسشگان محصول پوشش داده شده است یا نه، یا در انجمن راهنمایی Ad Manager بپرسید. برای مشکلات خاص، با پشتیبانی Ad Manager API تماس بگیرید.