Today, we’re excited to release v201107 of the DoubleClick for Publishers (DFP) API. In this release, you’ll find support for labels, technology (browsing) targeting, and more.

Labels

Labels can help you categorize your advertisers, orders, and line items, prevent line items from competing advertisers from delivering to the same webpage, and can be used to set frequency caps to ad units. These tasks can now be accomplished via the API using COMPETITIVE_EXCLUSION and AD_UNIT_FREQUENCY_CAP respectively.

Labels can be applied to companies, orders, and line items and are inherited. This means that if you apply a label to an advertiser, it will be applied to the advertiser's orders and line items automatically. If you apply a label to an order, it will be applied to the order's line items automatically. The LineItem.effectiveAppliedLabels and Order.effectiveAppliedLabels fields can be used to determine all labels that are both inherited and defined on the object itself, but the appliedLabels field should be used to update objects.

For more information about labels, please refer to the create, apply, and remove labels Help Center article.

Competitive exclusion for small business publishers

For DFP small business publishers, we have exposed functionality similar to competitive exclusion labels. The Company.enableSameAdvertiserCompetitiveExclusion field prevents ads from the same company from competing with each other. In other words, if two orders exist with the same company or there are two line items from the same order that are eligible to serve on the same page, this field will prevent those two ads from competing with each other. The LineItem.disableSameAdvertiserCompetitiveExclusion, on the other hand, will allow all line items with this set to true to compete with each other, regardless of their labels or company settings.

Technology targeting

Technology (browsing) targeting is also included in this release. Technology targeting allows you to target specific information about the user browsing your site including bandwidth, browser, browser language, and operating system details. The new field Targeting.technologyTargeting can be set with a TechnologyTargeting object with fields for each type of targeting.

To add a new target, first fetch the ID from the respective PublisherQueryLanguageService table and create a Technology object with just the ID filled in. When fetching targets from the API, the objects will be subclassed correctly depending on type. For a refresher on how to set targets using IDs in the DFP API, please refer to the geographical targeting blog post.

External IDs

To help developers who need to reconcile DFP system objects with other systems, we’ve added external IDs to the LineItem and Order objects. Before v201107, the externalId field on Order objects represented the PO Number in the UI. We’ve updated this by renaming it to poNumber and exposing a brand new externalOrderId field. As a developer, you will be able to rename all instances in which you reference externalId as a PO number and use the new field for additional reconciliation.

This blog post has only scratched the surface of the features v201107 brings; to learn more, please visit our release notes page. As always, developer feedback is important to us; if there are any features you are dying to see become a part of the API, please let us know at our forum.

Adam Rogal, DFP API Team

Today we are excited to announce the next version of the DoubleClick for Publishers (DFP) API, version 201101. Highlights of this release include the ability to define custom targeting criteria, and the new Publisher Query Language service.

Custom targeting

Custom targeting allows you to define your own targeting criteria (such as age, gender, or content) that DFP wouldn't otherwise be able to determine. To use custom targeting, you create keys and values, target your line items to those key-value pairs, and then add them to your website's ad tags.

Similar to creating ad units and then targeting them with line items, using the custom targeting API is broken into two steps. First, you will create custom targeting keys and values with the CustomTargetingService, and then you will target these keys and values with the LineItemService. To target the keys and values, set the customTargeting field with a CustomCriteriaSet object. The custom criteria set object contains the targeting expression as an ORed set of ANDed custom criteria. The leaf nodes of the tree are key-value pairs of either free-form or predefined criteria.

If you had the expression (age=17 OR (gender=male AND age=42)), this would be represented as two custom criteria sets with logicalOperator.AND, [age=17] and [gender=male, age=42] ORed together. The custom criteria sets would be children of the customTargeting field.

Below is a diagram that will help you understand how the tree must be organized. The first level is the customTargeting field of the line item. The second level is the ORed custom criteria sets, the children of customTargeting. The final level is the custom criteria that belong to each custom criteria set, ANDed together.

In the above example of (age=17 OR (gender=male AND age=42)), the custom criteria set would look something like this:

For more examples on how to create and target custom criteria, please see the CreateCustomTargetingKeysAndValuesExample.java example as well as the TargetCustomCriteriaExample.java example.

Publisher Query Language service

The new PublisherQueryLanguageService allows you to query for data in the DFP network. You can use the service to pull information about geographical targeting that you could only previously retrieve by downloading one of the CSVs on the geographical targeting page. You can retrieve all targetable cities, for example, by sending a PQL statement like:

SELECT * FROM City where targetable = true

You would receive a ResultSet object similar to the one found in JDBC. Notice that we have included the targetable column in each of our tables to select on locations which can be successfully targeted in line items. A full list of tables can be found on the services reference page and we plan to expand this to other tables in the future.

New release notes page

With this new version, we have also modified our release notes page to give you a better per-object breakdown of new and deprecated fields and services. This will make upgrading your implementation that much easier.

Custom criteria targeting has been our most requested feature and we are eager to receive any feedback you may have through our forum. Also, if there are any blog posts about specific topics you may want, please do not hesitate to make requests on our forum as well.

– Adam Rogal, DFP API Team