All line items created using the Display & Video 360 API are initially created in a draft state. In this draft state, line items don't serve ads, so you are free to adjust settings and targeting without those changes affecting any current ad serving. This page describes the steps you should take to confirm that your line item is ready for serving ads, and how to update its status to active.
What to do before activation
Given that line items are the manner in which your ad revenue is spent through ad buying and serving, it is important to make sure that the line item will serve ads as intended when activated. Below are a few things to consider before activating your line item:
- Make sure the flight settings are correct: Check the line item's
flight
field to make sure that the flight window for the line item is set correctly. The flight window of a line item may be custom to the line item or inherited by the parent insertion order. If controlled directly by a manual trigger, the line item automatically inherits the flight of the insertion order. - Verify that there are no warnings blocking the serving of the line item:
Use
advertisers.lineItems.get
to retrieve a line item resource and check the fieldwarningMessages
to verify that the line item has no warnings that may hinder the serving of the line item. TheLineItemWarningMessage
enum notes the impact of each warning. - Confirm that all parent resources are also active: An active line item
will not begin to serve ads if its parent advertiser, campaign, or insertion
order are not active. Retrieve these resources using the
GET
methods in the Advertisers, Campaigns, and Insertion Orders services.
Activate a line item
Line items can be updated by using the PATCH
method in the Line
Items service.
The following code is an example of how to update a line item’s entity status to active:
Java
// Create the line item structure. LineItem lineItem = new LineItem(); lineItem.setEntityStatus("ENTITY_STATUS_ACTIVE"); // Configure the patch request. LineItems.Patch request = service.advertisers().lineItems() .patch(advertiser-id, line-item-id, lineItem); // Set update mask to only update entity status. request.setUpdateMask("entityStatus"); // Update the line item. LineItem response = request.execute(); // Display the new line item entity status. System.out.printf("LineItem %s now has entity status %s.", response.getName(), response.getEntityStatus());
Python
# Create a line item object with only updated entity status. line_item_obj = { 'entityStatus': 'ENTITY_STATUS_Active', } # Update the line item. lineItem = service.advertisers().lineItems().patch( advertiserId=advertiser-id, lineItemId=line-item-id, updateMask="entityStatus", body=line_item_obj ).execute() # Display the line item's new entity status print("Line Item %s now has entity status %s." % (lineItem["name"], lineItem["entityStatus"]))
PHP
// Create line item with updated fields. $lineItem = new Google_Service_DisplayVideo_LineItem(); $lineItem->setEntityStatus('ENTITY_STATUS_ACTIVE'); // Create request parameter array with update mask. $optParams = array('updateMask' => 'entityStatus'); // Call the API, updating the entity status for the identified line item. $result = $this->service->advertisers_lineItems->patch( advertiser-id, line-item-id, $lineItem, $optParams ); printf( 'Line Item %s now has entity status %s.\n', $result['name'], $result['entityStatus'] );
Serve using a manual trigger
Even when active, a line item only serves ads during periods dictated by its flight. Within the date range of a line item's flight, ad serving can be more precisely controlled through the use of a manual trigger.
A manual trigger is a switch that allows the line item to quickly begin serving ads for a short period of time upon activation. Once activated, the line item will serve ads for a set period of time or until the manual trigger is deactivated.
Only one manual trigger can be associated with a line item at a time. You can
retrieve the ID for the desired manual trigger through the Manual Trigger
LIST
method and assign that ID to a line item by updating the
line item's flight
field.
The following code is an example of how to update a line item’s flight to add a manual trigger:
Java
// Create the line item structure. LineItem lineItem = new LineItem(); // Create and set the line item flight. LineItemFlight lineItemFlight = new LineItemFlight(); lineItemFlight .setFlightDateType("LINE_ITEM_FLIGHT_DATE_TYPE_TRIGGER"); lineItemFlight .setTriggerId(manual-trigger-id); lineItem.setFlight(lineItemFlight); // Configure the patch request. LineItems.Patch request = service.advertisers().lineItems() .patch(advertiser-id, line-item-id, lineItem); // Set update mask to only update flight. request.setUpdateMask("flight"); // Update the line item. LineItem response = request.execute(); // Display the new manual trigger ID associated with the line item. System.out.printf("Line Item %s is now associated with manual trigger ID %s.", response.getName(), response.getFlight().getTriggerId());
Python
# Create a line item object with only the updated flight. line_item_obj = { 'flight': { 'flightDateType': 'LINE_ITEM_FLIGHT_DATE_TYPE_TRIGGER', 'triggerId': manual-trigger-id }, } # Update the line item. lineItem = service.advertisers().lineItems().patch( advertiserId=advertiser-id, lineItemId=line-item-id, updateMask="flight", body=line_item_obj ).execute() # Display the line item's new entity status print("Line Item %s is now associated with manual trigger ID %s." % (lineItem["name"], lineItem["flight"]["triggerId"]))
PHP
// Create line item. $lineItem = new Google_Service_DisplayVideo_LineItem(); // Create new flight object identifying the manual trigger ID. $flight = new Google_Service_DisplayVideo_LineItemFlight(); $flight->setFlightDateType('LINE_ITEM_FLIGHT_DATE_TYPE_TRIGGER'); $flight->setTriggerId(manual-trigger-id); // Set flight on updated line item. $lineItem->setFlight($flight); // Create request parameter array with update mask. $optParams = array('updateMask' => 'flight'); // Call the API, updating the entity status for the identified line item. $result = $this->service->advertisers_lineItems->patch( advertiser-id, line-item-id, $lineItem, $optParams ); printf( 'Line Item %s is now associated with manual trigger ID %s.\n', $result['name'], $result['flight']['triggerId'] );
Once the manual trigger is associated with the line item, you can have your line
item start to serve ads by activating the manual trigger. The line item will
serve ads for the amount of time dictated by the trigger's
activationDurationMinutes
field, or until the
trigger is deactivated.