An insertion order contains a set of line items that are part of the same
advertising push. InsertionOrder
resources do the following:
- Set a shared budget for their line items.
- Enable line item ad serving through their flight dates and entity status.
- Limit valid configurations for their line items through their type and settings.
If you are using an existing insertion order, you can skip to Create a line item .
Choose configurations
Before creating an insertion order, review and decide on these settings:
-
bidStrategy. -
budget. -
insertionOrderType. -
frequencyCap. -
kpi. -
pacing. -
partnerCosts.
The InsertionOrder
resource also has many optional fields. Read the reference documentation
for more information.
How to create an insertion order
Here's how to create an insertion order with the following settings:
- A bid strategy set to maximize spend based on viewable impressions.
- A goal of spending one-tenth of one currency unit per thousand viewable impressions.
- A pace over the entirety of the flight that prevents underspending.
-
A budget of one currency unit to spend between the provided start and end dates.
Java
// Provide the ID of the parent advertiser. long advertiserId = advertiser - id ; // Provide the ID of the parent campaign. long campaignId = campaign - id ; // Provide the display name of the insertion order. String displayName = display - name ; // Provide the year, month, and day of the start date of the insertion order // budget segment. int startYear = start - date - year ; int startMonth = start - date - month ; int startDay = start - date - day ; // Provide the year, month, and day of the end date of the insertion order // budget segment. int endYear = end - date - year ; int endMonth = end - date - month ; int endDay = end - date - day ; // Create the insertion order structure. InsertionOrder insertionOrder = new InsertionOrder () . setCampaignId ( campaignId ) . setDisplayName ( displayName ) . setEntityStatus ( "ENTITY_STATUS_DRAFT" ); // Create and add the pacing setting. Pacing pacing = new Pacing (). setPacingPeriod ( "PACING_PERIOD_FLIGHT" ). setPacingType ( "PACING_TYPE_AHEAD" ); insertionOrder . setPacing ( pacing ); // Create and set the frequency cap. FrequencyCap frequencyCap = new FrequencyCap (). setUnlimited ( true ); insertionOrder . setFrequencyCap ( frequencyCap ); // Create and set the Key Performance Indicator (KPI). Kpi kpi = new Kpi (). setKpiType ( "KPI_TYPE_VCPM" ). setKpiAmountMicros ( 100_000L ); insertionOrder . setKpi ( kpi ); // Create the budget structure. InsertionOrderBudget insertionOrderBudget = new InsertionOrderBudget () . setBudgetUnit ( "BUDGET_UNIT_CURRENCY" ) . setAutomationType ( "INSERTION_ORDER_AUTOMATION_TYPE_BID_BUDGET" ); // Create a budget segment structure. InsertionOrderBudgetSegment insertionOrderBudgetSegment = new InsertionOrderBudgetSegment (). setBudgetAmountMicros ( 1_000_000L ); // Create and assign date range object. DateRange dateRange = new DateRange () . setStartDate ( new Date (). setYear ( startYear ). setMonth ( startMonth ). setDay ( startDay )) . setEndDate ( new Date (). setYear ( endYear ). setMonth ( endMonth ). setDay ( endDay )); // Add the date range to the budget segment. insertionOrderBudgetSegment . setDateRange ( dateRange ); // Add budget segment list to the budget. insertionOrderBudget . setBudgetSegments ( ImmutableList . of ( insertionOrderBudgetSegment )); // Set budget. insertionOrder . setBudget ( insertionOrderBudget ); // Create and assign the bidding strategy. insertionOrder . setBidStrategy ( new BiddingStrategy () . setMaximizeSpendAutoBid ( new MaximizeSpendBidStrategy () . setPerformanceGoalType ( "BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_AV_VIEWED" ))); // Set optimization objective. insertionOrder . setOptimizationObjective ( "NO_OBJECTIVE" ); // Configure the create request. InsertionOrders . Create request = service . advertisers (). insertionOrders (). create ( advertiserId , insertionOrder ); // Create the insertion order. InsertionOrder response = request . execute (); // Display the new insertion order ID. System . out . printf ( "Insertion Order %s was created." , response . getName ());
Python
# Provide the ID of the parent advertiser. advertiser_id = advertiser - id # Provide the ID of the parent campaign. campaign_id = campaign - id # Provide the display name of the insertion order. display_name = display - name # Provide the year, month, and day of the start date of the insertion order # budget segment. start_date_year = start - date - year start_date_month = start - date - month start_date_day = start - date - day # Provide the year, month, and day of the end date of the insertion order # budget segment. end_date_year = end - date - year end_date_month = end - date - month end_date_day = end - date - day # Create the insertion order object. insertion_order_obj = { "campaignId" : campaign_id , "displayName" : display_name , "entityStatus" : "ENTITY_STATUS_DRAFT" , "pacing" : { "pacingPeriod" : "PACING_PERIOD_FLIGHT" , "pacingType" : "PACING_TYPE_AHEAD" , }, "frequencyCap" : { "unlimited" : True }, "integrationDetails" : {}, "budget" : { "budgetUnit" : "BUDGET_UNIT_CURRENCY" , "automationType" : "INSERTION_ORDER_AUTOMATION_TYPE_BID_BUDGET" , "budgetSegments" : [{ "budgetAmountMicros" : "1000000" , "dateRange" : { "startDate" : { "year" : start_date_year , "month" : start_date_month , "day" : start_date_day , }, "endDate" : { "year" : end_date_year , "month" : end_date_month , "day" : end_date_day , }, }, }], }, "bidStrategy" : { "maximizeSpendAutoBid" : { "performanceGoalType" : ( "BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_AV_VIEWED" ) } }, "kpi" : { "kpiType" : "KPI_TYPE_VCPM" , "kpiAmountMicros" : "100000" }, "optimizationObjective" : "NO_OBJECTIVE" , } # Build and execute request. insertion_order_response = ( service . advertisers () . insertionOrders () . create ( advertiserId = advertiser_id , body = insertion_order_obj ) . execute () ) # Print the new insertion order. print ( f 'Insertion Order { insertion_order_response [ "name" ] } was created.' )
PHP
// Provide the ID of the parent advertiser. $advertiserId = advertiser-id ; // Provide the ID of the parent campaign. $campaignId = campaign-id ; // Provide the display name of the insertion order. $displayName = display-name ; // Provide the year, month, and day of the start date of the insertion // order budget segment. $startYear = start-date-year ; $startMonth = start-date-month ; $startDay = start-date-day ; // Provide the year, month, and day of the end date of the insertion // order budget segment. $endYear = end-date-year ; $endMonth = end-date-month ; $endDay = end-date-day ; // Create the insertion order structure. $insertionOrder = new Google_Service_DisplayVideo_InsertionOrder(); $insertionOrder->setCampaignId($campaignId); $insertionOrder->setDisplayName($displayName); $insertionOrder->setEntityStatus('ENTITY_STATUS_DRAFT'); // Create and set the pacing. $pacing = new Google_Service_DisplayVideo_Pacing(); $pacing->setPacingPeriod('PACING_PERIOD_FLIGHT'); $pacing->setPacingType('PACING_TYPE_AHEAD'); $insertionOrder->setPacing($pacing); // Create and set the frequency cap. $frequencyCap = new Google_Service_DisplayVideo_FrequencyCap(); $frequencyCap->setUnlimited(true); $insertionOrder->setFrequencyCap($frequencyCap); // Create and set the Key Performance Indicator (KPI). $kpi = new Google_Service_DisplayVideo_Kpi(); $kpi->setKpiType('KPI_TYPE_VCPM'); $kpi->setKpiAmountMicros(100000); $insertionOrder->setKpi($kpi); // Create and set the insertion order budget. $budget = new Google_Service_DisplayVideo_InsertionOrderBudget(); $budget->setBudgetUnit('BUDGET_UNIT_CURRENCY'); $budget->setAutomationType('INSERTION_ORDER_AUTOMATION_TYPE_BID_BUDGET'); $budgetSegment = new Google_Service_DisplayVideo_InsertionOrderBudgetSegment(); $budgetSegment->setBudgetAmountMicros(1000000); $dateRange = new Google_Service_DisplayVideo_DateRange(); $startDate = new Google_Service_DisplayVideo_Date(); $startDate->setYear($startDateTime->format('Y')); $startDate->setMonth($startDateTime->format('n')); $startDate->setDay($startDateTime->format('j')); $dateRange->setStartDate($startDate); $endDate = new Google_Service_DisplayVideo_Date(); $endDate->setYear($endDateTime->format('Y')); $endDate->setMonth($endDateTime->format('n')); $endDate->setDay($endDateTime->format('j')); $dateRange->setEndDate($endDate); $budgetSegment->setDateRange($dateRange); $budget->setBudgetSegments(array($budgetSegment)); $insertionOrder->setBudget($budget); // Create and set the bidding strategy. $maxSpendBidStrategy = new Google_Service_DisplayVideo_MaximizeSpendBidStrategy(); $maxSpendBidStrategy->setPerformanceGoalType('BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_AV_VIEWED'); $biddingStrategy = new Google_Service_DisplayVideo_BiddingStrategy(); $biddingStrategy->setMaximizeSpendAutoBid($maxSpendBidStrategy); $insertionOrder->setBidStrategy($biddingStrategy); // Create and set the optimization objective. $insertionOrder->setOptimizationObjective('NO_OBJECTIVE'); // Call the API, creating the insertion order under the advertiser and // campaign given. try { $result = $this->service->advertisers_insertionOrders->create( $advertiserId, $insertionOrder ); } catch (\Exception $e) { $this->renderError($e); return; } // Print the new insertion order. printf('<p>Insertion Order %s was created.</p>', $result['name']);
How to activate an insertion order
Insertion orders must be created in a draft state. Use a patch
request to update the entityStatus
field of the InsertionOrder
. Line items under the insertion order won't serve ads
unless the insertion order is active.
Here's how to activate an insertion order:
Java
// Create the structure for the updated insertion order. InsertionOrder insertionOrder = new InsertionOrder (). setEntityStatus ( "ENTITY_STATUS_ACTIVE" ); // Configure the patch request and set update mask to only update entity // status. InsertionOrders . Patch request = service . advertisers () . insertionOrders () . patch ( advertiser - id , insertion - order - id , insertionOrder ) . setUpdateMask ( "entityStatus" ); // Update the insertion order. InsertionOrder response = request . execute (); // Display the new insertion order entity status. System . out . printf ( "Insertion Order %s now has entity status %s%n" , response . getName (), response . getEntityStatus ());
Python
# Create the structure for the updated insertion order. insertion_order_obj = { "entityStatus" : "ENTITY_STATUS_ACTIVE" , } # Call the API, updating the entity status for the identified insertion # order. response = ( service . advertisers () . insertionOrders () . patch ( advertiserId = advertiser - id , insertionOrderId = insertion - order - id , updateMask = "entityStatus" , body = insertion_order_obj , ) . execute () ) # Display the new insertion order entity status. print ( f "Insertion Order { response [ 'name' ] } now has entity status " f " { response [ 'entityStatus' ] } ." )
PHP
// Create the structure for the updated insertion order. $insertionOrder = new Google_Service_DisplayVideo_InsertionOrder(); $insertionOrder->setEntityStatus('ENTITY_STATUS_ACTIVE'); // Call the API, updating the entity status for the identified insertion // order. try { $result = $this->service->advertisers_insertionOrders->patch( advertiser-id , insertion-order-id , $insertionOrder, array('updateMask' => 'entityStatus') ); } catch (\Exception $e) { $this->renderError($e); return; } // Display the new insertion order entity status. printf( '<p>Insertion Order %s now has entity status %s.</p>', $result['name'], $result['entityStatus'] );
