Discover DFP API v201111: Suggested Ad Units

The v201111 version of the DoubleClick for Publishers (DFP) API introduces SuggestedAdUnitService which lets you get and approve those ad units that have tags on your web pages, but no corresponding ad units in DFP.  By default, only ad tags that have 10 or more requests will be returned as suggested ad units. They can be approved using performSuggestedAdUnitAction, after which they become ad units and you can manipulate them using InventoryService.  To use this service, please make sure you have a premium account and that you have enabled the feature in the User Interface.

Why Use Suggested Ad Units?

A simple use case for suggested ad units is for new publishers or blog owners to create new tags for articles and posts on their site and approve suggested ad units based on the number of impressions they generate. This gives you the chance to see how well your content does before targeting line items to your ad units. The ApproveSuggestedAdUnitsExample from the client libraries will show you how to do this.

A more involved use case for publishing platforms is to tag all the pages generated by the users and perform some operations on content that generates a sizable number of impressions.  These operations can include:

1. Approving the suggested ad unit and targeting line items to it
2. Promoting the page as featured content
3. Recognize the user for quality content and auto-approve their pages

Here's a Java code sample of how you would do this:

// Set the number of requests to 50 or more.
Long NUMBER_OF_REQUESTS = 50L;

// Statement to fetch suggested ad units in descending order by number of 
// requests.
String statementText = "ORDER BY numRequests DESC LIMIT 500";
Statement filterStatement = 
    new StatementBuilder(statementText).toStatement();
SuggestedAdUnitPage page = new SuggestedAdUnitPage();

// List of suggested ad unit ids to approve.
List<String> suggestedAdUnitIds = new ArrayList<String>();
page = suggestedAdUnitService.getSuggestedAdUnitsByStatement(
    filterStatement);

if (page.getResults() != null) {
  for (SuggestedAdUnit suggestedAdUnit : page.getResults()) {
    if (suggestedAdUnit.getNumRequests() >= NUMBER_OF_REQUESTS) {
      // Add it to the ID list to be approved.
      suggestedAdUnitIds.add(suggestedAdUnit.getId());
      /*
       * Promoting the page as a featured content.
       * Recognize the user for quality content and auto-approve their 
       * pages.
       */
    }
  }
}

if (suggestedAdUnitIds.size() > 0) {
  // Modify statement to select suggested ad units from the list.
  filterStatement.setQuery(
      "WHERE id IN (" + StringUtils.join(suggestedAdUnitIds, ",") + ")");
  // Create action to approve suggested ad units.
  ApproveSuggestedAdUnit action = new ApproveSuggestedAdUnit();
  // Perform the action.
  UpdateResult result = suggestedAdUnitService.performSuggestedAdUnitAction(
      action, filterStatement);
}

These are just some of the things we think suggested ad units can be used for; we'd love to hear your ideas on our forum or at an Office Hours Hangout.

 - Jeffrey Sham, DFP API Team