In this installment of the Discover DFP API v201111 series, we present new features we’ve added to reports in the API. In addition to merged ad server columns, which helps upgraded publishers reports on both DART and DFP ad servers, you can now use dimension attributes for greater control in reporting.

Dimension Attributes

Dimension attributes let you break down your report by additional fields associated with the dimension. For example, you can now add the trafficker, external ID, and order start date as dimension attributes associated to your order dimension in a delivery report. This is useful if you would like to see how each of your orders is doing and which trafficker was responsible for that order.

In the past, you would get this information by running a report for orders and then looking up the orders with Order Service to inspect the attributes. Now, it’s as simple as adding values to the dimensionAttributes field on your ReportQuery object and the corresponding fields will be integrated into the report. The following code snippet shows you how to create a report job with dimension attributes:

// Create report job.
ReportJob reportJob = new ReportJob();

// Create report query.
ReportQuery reportQuery = new ReportQuery();
reportQuery.setDateRangeType(DateRangeType.LAST_MONTH);
reportQuery.setDimensions(new Dimension[] {Dimension.ORDER});

// Set dimension attributes for order dimension.
reportQuery.setDimensionAttributes(new DimensionAttribute[] {
    DimensionAttribute.ORDER_TRAFFICKER,
    DimensionAttribute.ORDER_START_DATE_TIME,
    DimensionAttribute.ORDER_END_DATE_TIME});

// Set columns to report on.
reportQuery.setColumns(new Column[] {
    Column.AD_SERVER_IMPRESSIONS,
    Column.AD_SERVER_CLICKS});

reportJob.setReportQuery(reportQuery);

You can check out the full example in the RunDeliveryReportExample in the Java client library. Notice that you can only add dimension attributes for dimensions that you have in the report. For example, if you tried to add LINE_ITEM_EXTERNAL_ID, and you only have order (but not line item) as a dimension, you will get the following error:

ReportError.ATTRIBUTES_NOT_SUPPORTED_FOR_REQUEST

Be sure to check out our updated reporting examples in the client libraries and take a look at our documentation for a full mapping of supported dimension attributes and the fields they represent.

We are always looking for ways to improve the API and we’d love to get your feedback. Let us know what you’d like to see in the API or discussed in a blog post by posting on our forum. We’re also more than happy to chat during one of our office hours hangouts.

 - Jeffrey Sham, DFP API Team

Last month, we announced the ability to create both custom and template creatives using the DFP API. Today we’ll show you can use these premium-only features to create richer creatives with custom HTML.

Custom or template

The difference between custom and template creatives is that custom creatives have their HTML snippet set within them, while template creatives are instantiated from system or user defined HTML snippets. Deciding which one to use depends on your network’s needs. If your network deals primarily with traffickers using the DFP UI, it may be beneficial for them to use creative templates in their workflow. The API could be used to retrieve these templates and report on them, but your traffickers would most likely want to create the creatives from templates in the UI.

However, if you are developing a platform in which traffickers spend most of their day, it may scale better to template the HTML yourself within your content management system (CMS) and use custom creatives for the advertisements. You could store custom HTML snippets and prompt the user for assets to insert. In essence, you would be creating your own templates, but without the overhead of template creatives.

Creating custom creatives

To create a custom creative, you first have to define your HTML snippet:

  String htmlSnippet = "<a href='%%CLICK_URL_UNESC%%%%DEST_URL%%'>"
      + "<img src='%%FILE:IMAGE_ASSET%%'/></a><br>Click for great deals!");
  CustomCreative customCreative = new CustomCreative();
      customCreative.setHtmlSnippet(htmlSnippet);

Notice here that the CLICK_URL_UNESC, DEST_URL, and FILE macros are used to customize the creative at serving time. CLICK_URL_UNESC will insert the clickthrough URL while DEST_URL inserts the URL that the ad points to. The FILE macro will reference any attached assets to the creative, in this case one named IMAGE_ASSET.

  // Set the custom creative image asset.
  CustomCreativeAsset customCreativeAsset = new CustomCreativeAsset();
  customCreativeAsset.setMacroName("IMAGE_ASSET");
  customCreativeAsset.setAssetByteArray(/* Byte array from image. */);
  customCreativeAsset.setFileName(
      String.format("image%s.jpg", System.currentTimeMillis()));
  customCreative.setCustomCreativeAssets(
      new CustomCreativeAsset[] {customCreativeAsset});

You would then call CreativeService.createCreative on customCreative to instantiate on the server. After creating the creative, you can then review it using the creative’s previewUrl attribute or the newly added getPreviewUrl method. When updating custom creatives, you don’t need to pass the asset byte array each time. Instead, you can leave it null with assetId set to what it was assigned to when created. The full example can be found on the Java client library page, as well as in our other libraries.

As a final note, custom creatives can be used for many other purposes beyond the simple image ad above. Including a SWF file as an asset, for example, is a common way of creating flash banner ads. You can even include a Google+ +1 button and customize the +1’s destination URL with the DEST_URL macro.

We have a few more posts lined up for the Discover DFP API v201111 series, but if there’s any other topics you’d like to see, please let us know on the forum.

- Adam Rogal, DFP API Team

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

In the v201111 release of the DoubleClick for Publishers (DFP) API, we're bringing you the ability to target your ad units and line items specifically for the mobile platform. The following walk-through based on the CreateMobileLineItem example of the client libraries describes how to create mobile-targeted line items.

Set your Target Platform

The first step is to set the new attribute targetPlatform to MOBILE to specify that the line item is targeted towards mobile platforms rather than the default web browser platform.  Please note that the target platform attribute has also been added to ad units and that attribute needs to be set to MOBILE as well for the targeting to work.

Set your Targeting

We've introduced four mobile targeting options to enable you to target the right platform:

1. device manufacturer
2. mobile carrier
3. mobile device
4. mobile device submodel

Here is how you set up your targeting to target just Google devices:

Technology manufacturer = new Technology();
// The ID for the Google device manufacturer was fetched from the 
// Device_Manufacturer PQL table.
manufacturer.setId(40100L); 

DeviceManufacturerTargeting manufacturerTargeting = 
    new DeviceManufacturerTargeting();
manufacturerTargeting.setDeviceManufacturers(
    new Technology[] {manufacturer});
manufacturerTargeting.setIsTargeted(true);

TechnologyTargeting technologyTargeting = new TechnologyTargeting();
technologyTargeting.setDeviceManufacturerTargeting(
    manufacturerTargeting);

Targeting targeting = new Targeting();
targeting.setTechnologyTargeting(technologyTargeting);

LineItem lineItem = new LineItem();
lineItem.setTargeting(targeting);

That's it! Your line item is now set to target just Google devices.

For mobile device targeting, you can specify two lists of devices: one that is targeted and one that is excluded.  This allows you to target a device manufacturer but exclude certain devices within that family.  However, if a device is part of a device targeting inclusion list, another device from the same manufacturer cannot be in the exclusion list.  For example, putting the Nexus S in the inclusion list and the Nexus One in the exclusion list will result in the following targeting error:

GenericTargetingError.CONFLICTING_INCLUSION_OR_EXCLUSION_OF_SIBLINGS @ targeting.deviceFamilyTargeting

Instead, we recommend targeting the Google device manufacturer and excluding the Nexus One with the device exclusion list.

As always, we value your feedback, so feel free to leave your questions or comments on our forum or join us at one of our upcoming developer Hangouts.

 - Jeffrey Sham, DFP API Team

Today we’d like to introduce you to the v201111 version of the DoubleClick for Publishers API. v201111 is one of our largest versions yet; it includes some highly-requested features such as full support for mobile ad serving, new creative types including templates, video player environment targeting, reporting updates, and suggested ad units. A full list of features can be found on our release notes page.

Mobile

As part of our ongoing effort to expand our publishers’ networks to mobile platforms, we’ve made it easier than ever to create and target mobile inventory in the API. Starting in v201111, you’ll find the targetPlatform field on the AdUnit and LineItem objects. This field allows you to specify that an ad unit represents a piece of mobile inventory, or that a line item is only meant to serve to mobile ad units. If a line item is marked as mobile, you can also specify manufacturer, carrier, and device targeting. New examples for how to create mobile ad units and line items will be made available next to their web counterparts in the client library examples shortly.

Creatives

In v201111, we’ve added a few new creative types, most importantly template creatives and custom creatives. Although both allow you to create richer advertisements, they differ in how you will want to use them in your solution. While custom creatives allow you to specify an arbitrary htmlSnippet with accompanying assets, creative templates allow you to reuse creative formats that will appear on the DFP user interface. Using creative templates, you can then create template creatives in which you can set variables to an already defined html snippet by the template.

We’ve also added the ability to view creatives as they would be served. To do this, pass the web page’s URL containing the appropriate ad tags, creative ID, and line item ID to the new LineItemCreativeAssociationService.getPreviewUrl() method.

Video

Along with the new mobile support in the API, we’ve expanded our video capabilities. In v201108, we added the ability to specify that a line item will serve to a video player environment. By enabling this setting, you can associate companion ads to run alongside the video. In v201111, as a DFP video publisher with a content feed, you can target individual videos within your content management source as well as positions within those videos.

Inventory

We’ve also added the SuggestedAdUnit service. This premium-only service enables you to add a new ad unit to an ad tag before defining it in DFP. This allows you to run forecasts for it before traffickers can start targeting line items to it; this functionality is similar to auto-created zones in DART for Publishers. If the ad server receives at least 10 requests for an undefined ad unit, the SuggestedAdUnitService.getSuggestedAdUnitsByStatement method will return that suggested ad unit. The suggested ad units can then be approved using the ApproveSuggestedAdUnits action. You can find an example of how to do this in our client libraries. Please also make sure that you are a premium user and that you have enabled this feature in your account through the User Interface. For more information, see the premium inventory help page.

Reporting

For v201111, we’ve added new columns and the feature to break down reports by dimension attributes. Whereas in the past you would have to manually correlate reports with objects fetched from services, this new feature allows you to include information such as a line item’s start time, an order’s trafficker, or an order’s external ID directly in the report to better integrate DFP reports with your system.

Follow-up posts in the discover series

Over the next few weeks, you’ll have the chance to get to know all of the features a bit more in the Discover DFP v201111 series starting first with the updated features for the mobile platform. And as a final note, if you haven’t signed up for our first ever hangout yet, we’d love to see you there!

- Adam Rogal, DFP API Team