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