Announcing v201103

Thursday, March 31, 2011 | 10:55 AM

Labels:

Today, we are announcing the next version of the DoubleClick for Publishers (DFP) API - version 201103. In this release, you’ll find added new targeting features, updated authentication methods, and increased performance of the reporting service. A full changelog for v201103 can be found on the release notes page .


New targeting features

In v201103, two new targeting features have been added: time and day targeting (day-parting) and user domain targeting . With day-part targeting, the user can set up which times of day a particular ad should run, and either in the timezone of the browser or publisher network. The snippet of code below shows you to target a line item to only serve ads on the weekends of a website user.

DayPartTargeting dayPartTargeting = new DayPartTargeting();
dayPartTargeting.setTimeZone(DeliveryTimeZone.BROWSER);

// Target only the weekend in the browser's timezone.
DayPart saturdayDayPart = new DayPart();
saturdayDayPart.setDayOfWeek(DayOfWeek.SATURDAY);
saturdayDayPart.setStartTime(
    new TimeOfDay(0, MinuteOfHour.ZERO));
saturdayDayPart.setEndTime(
    new TimeOfDay(24, MinuteOfHour.ZERO));

DayPart sundayDayPart = new DayPart();
sundayDayPart.setDayOfWeek(DayOfWeek.SUNDAY);
sundayDayPart.setStartTime(new TimeOfDay(0, MinuteOfHour.ZERO));
sundayDayPart.setEndTime(new TimeOfDay(24, MinuteOfHour.ZERO));
dayPartTargeting.setDayParts(
    new DayPart[] {saturdayDayPart, sundayDayPart});

targeting.setDayPartTargeting(dayPartTargeting);
lineItem.setTargeting(targeting);

User domain targeting allows the user to target specific domains from which to allow or disallow viewing of ads. The following snippet of code shows you how to restrict ads to not serve to users coming from IP addresses from “usa.gov” domain.

UserDomainTargeting userDomainTargeting =
    new UserDomainTargeting();
userDomainTargeting.setDomains(new String[] {"usa.gov"});
userDomainTargeting.setTargeted(false);
lineItem.setTargeting(userDomainTargeting);
Authentication changes

Along with targeting feature updates, the API has also changed the way authentication is handled. Previously, a RequestHeader object could contain both an authToken and an oAuthToken, which would cause an AMBIGUOUS_SOAP_REQUEST_HEADER exception if both were present. Now, we’ve replaced both the authToken and oAuthToken field with an authentication field, which takes a complex type of either ClientLogin or OAuth; this enables seamless integration of new authentication mechanisms.

For using the ClientLogin authentication mechanism, you would do:

<soapenv:Header>
  <ns1:RequestHeader
      xmlns:ns1=
        "https://www.google.com/apis/ads/publisher/v201103"
      soapenv:actor=
        "http://schemas.xmlsoap.org/soap/actor/next"
      soapenv:mustUnderstand="0">
    <ns1:networkCode>...</ns1:networkCode>
    <ns1:applicationName>...</ns1:applicationName>
    <ns1:authentication xsi:type="ns1:ClientLogin">
      <ns1:token>...</ns1:token>
    </ns1:authentication>
  </ns1:RequestHeader>
</soapenv:Header>

Likewise for OAuth authentication, you would do:

<soapenv:Header>
  <ns1:RequestHeader
      xmlns:ns1=
        "https://www.google.com/apis/ads/publisher/v201103"
      soapenv:actor=
        "http://schemas.xmlsoap.org/soap/actor/next"
      soapenv:mustUnderstand="0">
    <ns1:networkCode>...</ns1:networkCode>
    <ns1:applicationName>...</ns1:applicationName>
    <ns1:authentication xsi:type="ns1:OAuth">
      <parameters>
        OAuth oauth_consumer_key="...",
        oauth_nonce="...", oauth_signature="..."
      </parameters>
    </ns1:authentication>
  </ns1:RequestHeader>
</soapenv:Header>

Notice that in this case the authentication tag is xsi-typed as ns1:OAuth. Setting OAuth Authentication header will still work as it did before. For more information please see the authentication section of the developer’s guide.


Report enhancements

We’ve also improved the stability of the ReportService and changed the way reports with custom dates are fetched. Previous to v201103, ReportQuery could have a custom startDateTime and endDateTime. To align the API with the features of the product, the ReportQuery object now only takes dates for startDate and endDate. Furthermore, this also fixes an issue where an additional day past the endDateTime was being returned.

As always, we take developer feedback very seriously and we look forward to any feature requests on our forum .


-- Adam Rogal, DFP API Team