Create Resources

Line items have numerous parent resources from which they inherit settings and targeting. Most of these resources can be created, retrieved, and updated using the Display & Video 360 API. This page describes the resource hierarchy and gives examples of how to create these resources using the Display & Video 360 API.

Resource Hierarchy

Resource hierarchy diagram

In Display & Video 360, there is a hierarchy of resources whose settings factor into ad serving. Each resource has a distinct purpose in the serving of advertisements. Starting from the lowest hierarchical level:

  • Line Items are resources that control which ads are served, when they are served, and to whom they are served.
  • Insertion orders contain multiple line items. They provide default values for absent line item settings.
  • Campaigns contain multiple insertion orders. They don’t enforce settings on their insertion orders. Their settings serve as a framing by which to measure the progress and success of the ads served under them.
  • Advertisers own multiple advertising campaigns. They enforce brand safety targeting and other general settings on ads served under them. They also own the creative objects used in ads served under it and provide access to resources used in targeting.
  • Partners own multiple advertisers. They enforce further brand safety targeting and other settings on those advertisers. They also provide access to resources used in targeting and floodlight activities used in conversion tracking. Partners can only be retrieved via the API.

Inheritance

Line items inherit numerous settings and access from their parent resources. When managing line items and ad serving, inherited qualities to consider include:

  • Available creatives and floodlight activities: Line items only have access to resources that are owned by their parent partners or advertisers. Creatives are created under advertisers and floodlight activities are owned by partners, so the resources assigned to a line item via the fields creative_ids and conversion_counting must share the same parent advertiser and partner, respectively.
  • Accessible targetable entities: Resources such as channels, combined audiences, and others can be used in targeting. Line items can only be targeted using resources that are accessible to its parent partner or advertiser.
  • Brand safety targeting: Targeting set at the partner or advertiser level is inherited by their line items and is unable to be removed. This existing targeting can be identified by an assigned targeting option’s inheritance field and will affect what further targeting can be applied.

Create Resources

All of the resources listed above can be managed using the Display & Video 360 API. Below are simple code examples of how to create each of these resources using provided client libraries.

Create an advertiser

The following code is an example of how to create an advertiser:

Java

// Create an advertiser object.
Advertiser advertiser = new Advertiser();
advertiser.setPartnerId(partner-id);
advertiser.setDisplayName(display-name);
advertiser.setEntityStatus("ENTITY_STATUS_ACTIVE");

// Create and set the advertiser general configuration.
AdvertiserGeneralConfig advertiserGeneralConfig = new AdvertiserGeneralConfig();
advertiserGeneralConfig.setDomainUrl(domain-url);
advertiserGeneralConfig.setCurrencyCode("USD");
advertiser.setGeneralConfig(advertiserGeneralConfig);

// Create the ad server configuration structure.
AdvertiserAdServerConfig advertiserAdServerConfig = new AdvertiserAdServerConfig();

// Create and add the third party only configuration to the ad server
// configuration.
ThirdPartyOnlyConfig thirdPartyOnlyConfig = new ThirdPartyOnlyConfig();
thirdPartyOnlyConfig.setPixelOrderIdReportingEnabled(false);
advertiserAdServerConfig.setThirdPartyOnlyConfig(thirdPartyOnlyConfig);

// Set the ad server configuration.
advertiser.setAdServerConfig(advertiserAdServerConfig);

// Create and set the creative configuration.
advertiser.setCreativeConfig(new AdvertiserCreativeConfig());

// Configure the create request.
Advertisers.Create request = service.advertisers().create(advertiser);

// Create the advertiser.
Advertiser response = request.execute();

// Display the new advertiser.
System.out.printf("Advertiser %s was created.", response.getName());

Python

# Create an advertiser object.
advertiser_obj = {
  'partnerId': partner-id,
  'displayName': display-name,
  'entityStatus': "ENTITY_STATUS_ACTIVE",
  'generalConfig': {
      'domainUrl' : domain-url,
      'currencyCode' : 'USD'
  },
  'adServerConfig': {
      'thirdPartyOnlyConfig' : {
        'pixelOrderIdReportingEnabled' : False
      }
  },
  'creativeConfig': {}
}

# Create the advertiser.
advertiser = service.advertisers().create(
  body=advertiser_obj
).execute()

# Display the new advertiser.
print("Advertiser %s was created." % advertiser["name"])

Create a campaign

The following code is an example of how to create a campaign:

Java

// Create a campaign object.
Campaign campaign = new Campaign();
campaign.setDisplayName(display-name);
campaign.setEntityStatus("ENTITY_STATUS_PAUSED");

// Create a campaign goal object.
CampaignGoal campaignGoal = new CampaignGoal();
campaignGoal.setCampaignGoalType("CAMPAIGN_GOAL_TYPE_BRAND_AWARENESS");

// Create and add a performance goal to the campaign goal object.
PerformanceGoal performanceGoal = new PerformanceGoal();
performanceGoal.setPerformanceGoalType("PERFORMANCE_GOAL_TYPE_CPC");
performanceGoal.setPerformanceGoalAmountMicros(1000000L);
campaignGoal.setPerformanceGoal(performanceGoal);

// Set the campaign goal.
campaign.setCampaignGoal(campaignGoal);

// Create a campaign flight object.
// This object details the planned spend and duration of the campaign.
CampaignFlight campaignFlight = new CampaignFlight();
campaignFlight.setPlannedSpendAmountMicros(1000000L);

// Create the date range for the campaign flight.
DateRange dateRange = new DateRange();

// Set the start date to January first of next year
// and the end date to February first of next year.
Calendar nextYear = Calendar.getInstance();
nextYear.add(Calendar.YEAR, 1);
dateRange.setStartDate(
   new Date().setYear(nextYear.get(Calendar.YEAR)).setMonth(1).setDay(1));
dateRange.setEndDate(
   new Date().setYear(nextYear.get(Calendar.YEAR)).setMonth(2).setDay(1));

// Add the planned date range to the campaign flight object.
campaignFlight.setPlannedDates(dateRange);

// Set the campaign flight.
campaign.setCampaignFlight(campaignFlight);

// Create and set the frequency cap.
FrequencyCap frequencyCap = new FrequencyCap();
frequencyCap.setMaxImpressions(10);
frequencyCap.setTimeUnit("TIME_UNIT_DAYS");
frequencyCap.setTimeUnitCount(1);
campaign.setFrequencyCap(frequencyCap);

// Configure the create request.
Campaigns.Create request = service.advertisers().campaigns()
   .create(advertiser-id, campaign);

// Create the campaign
Campaign response = request.execute();

// Display the new campaign.
System.out.printf("Campaign %s was created.", response.getName());

Python

  # Create a campaign object.
campaign_obj = {
  'displayName': display-name,
  'entityStatus': 'ENTITY_STATUS_PAUSED',
  'campaignGoal': {
      'campaignGoalType' : 'CAMPAIGN_GOAL_TYPE_BRAND_AWARENESS',
      'performanceGoal': {
          'performanceGoalType': 'PERFORMANCE_GOAL_TYPE_CPC',
          'performanceGoalAmountMicros': 1000000
      }
  },
  'campaignFlight': {
      'plannedSpendAmountMicros': 1000000,
      'plannedDates': {
          'startDate': {
              'year': 2021,
              'month': 1,
              'day': 1
          },
          'endDate': {
              'year': 2021,
              'month': 2,
              'day': 1
          }
      }
  },
  'frequencyCap': {
      'maxImpressions': 10,
      'timeUnit': 'TIME_UNIT_DAYS',
      'timeUnitCount': 1
  }
}

# Create the campaign.
campaign = service.advertisers().campaigns().create(
  advertiserId=advertiser-id,
  body=campaign_obj
).execute()

# Display the new campaign.
print("Campaign %s was created." % campaign["name"])

Create an insertion order

The following code is an example of how to create an insertion order:

Java

// Create an insertion order object.
InsertionOrder insertionOrder = new InsertionOrder();
insertionOrder.setCampaignId(campaign-id);
insertionOrder.setDisplayName(display-name);
insertionOrder.setEntityStatus("ENTITY_STATUS_DRAFT");

// Create and add the pacing setting.
Pacing pacing = new Pacing();
pacing.setPacingPeriod("PACING_PERIOD_DAILY");
pacing.setPacingType("PACING_TYPE_EVEN");
pacing.setDailyMaxMicros(10000L);
insertionOrder.setPacing(pacing);

// Create and set the frequency cap.
FrequencyCap frequencyCap = new FrequencyCap();
frequencyCap.setTimeUnit("TIME_UNIT_DAYS");
frequencyCap.setTimeUnitCount(1);
frequencyCap.setMaxImpressions(10);
insertionOrder.setFrequencyCap(frequencyCap);

// Create and set the performance goal.
PerformanceGoal performanceGoal = new PerformanceGoal();
performanceGoal.setPerformanceGoalType("PERFORMANCE_GOAL_TYPE_CPC");
performanceGoal.setPerformanceGoalAmountMicros(1000000L);
insertionOrder.setPerformanceGoal(performanceGoal);

// Create a budget object.
InsertionOrderBudget insertionOrderBudget = new InsertionOrderBudget();
insertionOrderBudget.setBudgetUnit("BUDGET_UNIT_CURRENCY");

// Create a budget segment object.
InsertionOrderBudgetSegment insertionOrderBudgetSegment =
   new InsertionOrderBudgetSegment();
insertionOrderBudgetSegment.setBudgetAmountMicros(100000L);

// Create the date range for the budget segment.
DateRange dateRange = new DateRange();

// Set the start date to January first of next year
// and the end date to February first of next year.
Calendar nextYear = Calendar.getInstance();
nextYear.add(Calendar.YEAR, 1);
dateRange.setStartDate(
   new Date().setYear(nextYear.get(Calendar.YEAR)).setMonth(1).setDay(1));
dateRange.setEndDate(
   new Date().setYear(nextYear.get(Calendar.YEAR)).setMonth(2).setDay(1));

// 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);

// Configure the create request.
InsertionOrders.Create request =
   service.advertisers().insertionOrders()
       .create(advertiser-id, insertionOrder);

// Create the insertion order.
InsertionOrder response = request.execute();

// Display the new insertion order.
System.out.printf("InsertionOrder %s was created.", response.getName());

Python

  # Create an insertion order object.
insertion_order_obj = {
  'campaignId' : campaign-id,
  'displayName': display-name,
  'entityStatus': 'ENTITY_STATUS_DRAFT',
  'pacing': {
      'pacingPeriod': 'PACING_PERIOD_DAILY',
      'pacingType': 'PACING_TYPE_EVEN',
      'dailyMaxMicros': 10000
  },
  'frequencyCap': {
      'maxImpressions': 10,
      'timeUnit': 'TIME_UNIT_DAYS',
      'timeUnitCount': 1
  },
  'performanceGoal' : {
      'performanceGoalType': 'PERFORMANCE_GOAL_TYPE_CPC',
      'performanceGoalAmountMicros': 1000000
  },
  'budget': {
      'budgetUnit': 'BUDGET_UNIT_CURRENCY',
      'budgetSegments': [
          {
              'budgetAmountMicros': 100000,
              'dateRange': {
                  'startDate': {
                      'year': 2021,
                      'month': 1,
                      'day': 1
                  },
                  'endDate': {
                      'year': 2021,
                      'month': 2,
                      'day': 1
                  }
              }
          }
      ]
  }
}

# Create the insertion order.
insertionOrder = service.advertisers().insertionOrders().create(
  advertiserId=advertiser-id,
  body=insertion_order_obj
).execute()

# Display the new insertion order.
print("Insertion Order %s was created." % insertionOrder["name"])

Create a line item

The following code is an example of how to create a line item:

Java

// Create a line item object.
LineItem lineItem = new LineItem();
lineItem.setInsertionOrderId(insertion-order-id);
lineItem.setDisplayName(display-name);
lineItem.setLineItemType("LINE_ITEM_TYPE_DISPLAY_DEFAULT");
lineItem.setEntityStatus("ENTITY_STATUS_DRAFT");

// Create and set the line item flight.
LineItemFlight lineItemFlight = new LineItemFlight();
lineItemFlight
   .setFlightDateType("LINE_ITEM_FLIGHT_DATE_TYPE_INHERITED");
lineItem.setFlight(lineItemFlight);

// Create and set the line item budget.
LineItemBudget lineItemBudget = new LineItemBudget();
lineItemBudget
   .setBudgetAllocationType("LINE_ITEM_BUDGET_ALLOCATION_TYPE_FIXED");
lineItem.setBudget(lineItemBudget);

// Create and set the pacing setting.
Pacing pacing = new Pacing();
pacing.setPacingPeriod("PACING_PERIOD_DAILY");
pacing.setPacingType("PACING_TYPE_EVEN");
pacing.setDailyMaxMicros(10000L);
lineItem.setPacing(pacing);

// Create and set the frequency cap.
FrequencyCap frequencyCap = new FrequencyCap();
frequencyCap.setTimeUnit("TIME_UNIT_DAYS");
frequencyCap.setTimeUnitCount(1);
frequencyCap.setMaxImpressions(10);
lineItem.setFrequencyCap(frequencyCap);

// Create and set the partner revenue model.
PartnerRevenueModel partnerRevenueModel = new PartnerRevenueModel();
partnerRevenueModel
   .setMarkupType("PARTNER_REVENUE_MODEL_MARKUP_TYPE_CPM");
partnerRevenueModel.setMarkupAmount(10L);
lineItem.setPartnerRevenueModel(partnerRevenueModel);

// Set the list of IDs of the creatives associated with the line item.
lineItem.setCreativeIds(creative-ids);

// Create and set the bidding strategy.
BiddingStrategy biddingStrategy = new BiddingStrategy();
biddingStrategy
   .setFixedBid(new FixedBidStrategy().setBidAmountMicros(100000L));
lineItem.setBidStrategy(biddingStrategy);

// Configure the create request.
LineItems.Create request =
   service.advertisers().lineItems().create(advertiser-id, lineItem);

// Create the line item.
LineItem response = request.execute();

// Display the new line item.
System.out.printf("LineItem %s was created.", response.getName());

Python

# Create an line item object.
line_item_obj = {
  'insertionOrderId' : insertion-order-id,
  'displayName': display-name,
  'lineItemType': 'LINE_ITEM_TYPE_DISPLAY_DEFAULT',
  'entityStatus': 'ENTITY_STATUS_DRAFT',
  'flight': {
      'flightDateType': 'LINE_ITEM_FLIGHT_DATE_TYPE_INHERITED'
  },
  'budget': {
      'budgetAllocationType': 'LINE_ITEM_BUDGET_ALLOCATION_TYPE_FIXED'
  },
  'pacing': {
      'pacingPeriod': 'PACING_PERIOD_DAILY',
      'pacingType': 'PACING_TYPE_EVEN',
      'dailyMaxMicros': 10000
  },
  'frequencyCap': {
      'timeUnit': 'TIME_UNIT_DAYS',
      'timeUnitCount': 1,
      'maxImpressions': 10
  },
  'partnerRevenueModel': {
      'markupType': 'PARTNER_REVENUE_MODEL_MARKUP_TYPE_CPM',
      'markupAmount': 10
  },
  'creativeIds': creative-ids,
  'bidStrategy': {
      'fixedBid': {
          'bidAmountMicros': 100000
      }
  }
}

# Create the line item.
lineItem = service.advertisers().lineItems().create(
  advertiserId=advertiser-id,
  body=line_item_obj
).execute()

# Display the new line item.
print("Line Item %s was created." % lineItem["name"])