Showing posts with label custom targeting. Show all posts

v201104 - Simplified APIs for geographical targeting and custom criteria

Friday, May 6, 2011 | 2:00 PM

Labels: , , , ,

The next version of the DoubleClick for Publishers (DFP) API, version 201104, is now available. In this release, we've made some updates to LineItem targeting. Specifically, you’ll find a more consistent geographical targeting interface as well as a simplified CustomCriteria API.

A full changelog for v201104 can be found in the release notes.

GeoTargeting

From this version of the API onward, when targeting a LineItem to a geographical location, ID numbers are now used to identify locations instead of string values. Specifically, when creating your Targeting, you won't use RegionLocation, MetroLocation, CityLocation, or CountryLocation objects, and thus, there's no need to pass strings such as "Chicago" or "US."

Instead, whether you’re targeting a country or a city, you simply create a Location object using only its ID number, where the ID number corresponds to a given country, city, etc.

After you pass the Location object to the service, in either a create or update method call, the Location object will return as the corresponding subclass, e.g. MetroLocation, CityLoction, or CountryLocation; this is to simplify the targeting process while still providing meaningful data about your locations.

Here’s an example of creating a Location object using only its ID number and handing it to a GeoTargeting object.

Location regionLocation = new Location();
// Target New York City.
regionLocation.setId(1023191L);
geoTargeting.setTargetedLocations(
    new Location[] {regionLocation});

To find the IDs of the locations you wish to target (New York City in our example), you'll need to call the Publisher Query Language (PQL) service, as shown below.

// Get the PublisherQueryLanguageService.
PublisherQueryLanguageServiceInterface pqlService =
    user.getService(
        DfpService
            .V201104.PUBLISHER_QUERY_LANGUAGE_SERVICE);

// Create statement to select all targetable cities.
StatementBuilder statementBuilder =
new StatementBuilder(
    "SELECT id, CityName FROM City"
    + "WHERE targetable = true AND CityName = ’New York’");

// Get all cities.
ResultSet resultSet = pqlService.select(
    statementBuilder.toStatement());

// Now grab the ID from the resultSet.
Row row = resultSet.getRows(0);
String[] values = PqlUtils.getRowStringValues(row);
String id = values[0];

Alternatively, note that you can also manually look up the ID for a given region in our documentation.

If you'd like to see a complete example, GetAllCitiesExample demonstrates how to query the PQL service for the relevant IDs, while CreateLineItemsExample demonstrates using the IDs for GeoTargeting.

CustomCriteria

The CustomCriteria interface has been simplified in a similar way. Custom targeting keys and values are now exclusively referenced by their ID numbers. Due to this change, the API no longer provides predefined or freeform CustomCriteria. Instead, keys and values must be created ahead of time, then referenced by ID in the CustomCriteria object.

First, you must create the key and value objects. See the original CustomCriteria announcement for a demonstration.

Once the key and value objects have been created, the next step is to plug in the corresponding IDs into the CustomCriteria object.

// Create custom criteria.
CustomCriteria customCriteria = new CustomCriteria();

// Grab the IDs of the keys and values you wish to target.
Long keyId = ...
Long valueId1 = ...
Long valueId2 = ...

// Assign the keys and values.
customCriteria.setKeyId(keyId);
customCriteria.setValueIds(new long[] {valueId1, valueId2});

// CustomCriteria allows us to target either as IS or IS_NOT.
customCriteria.setOperator(
    CustomCriteriaComparisonOperator.IS);

For further insight, please look at CreateCustomTargetingKeysAndValuesExample and TargetCustomCriteriaExample .

As always, we love to hear from our developers and we look forward to any and all feedback on our forum.


-- David Kay, DFP API Team

Announcing v201101 and custom targeting support

Monday, February 7, 2011 | 1:00 PM

Labels: , , , , , ,

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