-
Notifications
You must be signed in to change notification settings - Fork 89
Home
This quick tutorial guides you into programming with the OpenRTB DoubleClick Ad Exchange libraries.
There are two modules:
- doubleclick-core provides utilities to work with AdX's native RTB protocol.
- doubleclick-openrtb provides utilities to work with the AdX/OpenRTB protocol.
The openrtb module is optional; if you have no need of OpenRTB you can use the core library alone.
DoubleClick provides extensive documentation for its native RTB protocol, including some algorithms you are expected to implement and dictionary files you may have to load, parse and index. No more! This library provides official, comprehensive, production-quality implementations of some critical needs.
The RTB model is the foundation of all work performed by a bidder. The AdX RTB protocol is specified by a Protocol Buffer descriptor, which you can download and then use protoc to generate model classes for the BidRequest and BidResponse message types. The doubleclick-core library includes the same protobuf descriptor and the model classes already generated and compiled.
Besides saving you the small effort of running protoc from your own build scripts, doubleclick-core is a dependency of other components from the OpenRTB DoubleClick libraries and other Google projects, and it establishes a standard API namespace for the generated model: com.google.protos.adx.NetworkBid.
Sensitive pieces of information from the DoubleClick protocol—winning prices, hyperlocal geolocation, and device IDs—are encrypted, but decrypting these fields is not trivial. The doubleclick-core library provides a complete implementation, including the encryption side (useful for example to write realistic unit tests). Here's how you decode and decrypt a winning price confirmation, the most common need:
DoubleClickCrypto.Keys keys = new DoubleClickCrypto.Keys(
new SecretKeySpec(... encryption key ..., "HmacSHA1"),
new SecretKeySpec(... integrity key ..., "HmacSHA1"));
DoubleClickCrypto.Price crypto = new DoubleClickCrypto.Price(keys);
...
String encodedPrice = httpRequest.getHeader("price");
double price = crypto.decodePriceValue(encodedPrice);Most code above is configuration; the data for encryption and decryption keys will be obtained from your RTB-enabled Ad Exchange Buyer account. Then your bidder's impression request handler needs only to fetch the winning price header, which value is encrypted and Base64-encoded, and invoke decodePriceValue(). Other DoubleClickCrypto nested classes take care of Hyperlocal and device IDs (IDFA and AdId); they are configured with the same Keys object and have similar methods for decryption and encryption.
Many properties from the RTB model are numeric codes for taxonomies such as product categories, vendors, creative attributes, etc. The same DoubleClick RTB download page liked above lists several dictionary files in CSV format. Besides knowing the code for specific needs, bidder developers often import these files to some memory index structure that makes possible to programmatically validate properties, or log the descriptive names of codes, among other uses. This is exactly the purpose of the DoubleClickMetadata component; sample usage:
DoubleClickMetadata metadata = new DoubleClickMetadata(
new URLConnectionTransport());
...
// Obtain the product category name "Software".
metadata.getProductCategories().get(10885);
// Check if 39 is a valid creative attribute in bid responses
// (false; this is a valid attribute but only in the request).
metadata.getBuyerDeclarableCreativeAttributes().containsKey(39);
// Find a GeoTarget record (geo_criteria_id 1023191 == NYC),
// then searches its hierarchy for the country (will find USA).
GeoTarget nyc = metadata.getGeoTarget(1023191);
GeoTarget usa = city.getAncestor(GeoTarget.Type.COUNTRY);
// GeoTarget only contains the alpha-2 country code, like "US";
// look up the CountryCodes record to map that to alpha-3 "USA".
metadata.getCountryCodes().get(usa.getCountryCode()).getAlpha3();Initializing the DoubleClickMetadata object requires a Transport object that fetches the metadata resources. URLConnectionTransport reads these resources from the web, which makes sure they're up-to-date. If you care more about loading time or stable behavior, a good strategy is downloading all those files from DoubleClick's website, adding them as local resources in your classpath, and using ResourceTransport so the local resources are loaded.
DoubleClickValidator inspects a pair of request / response and finds many potential errors in the response, automatically removing all bad ads but reporting the errors.
The doubleclick-openrtb module extends openrtb-core, combining that to doubleclick-core for the benefit of developers that want an OpenRTB-compatible programming model for DoubleClick Ad Exchange.
Check out openrtb-core's wiki first, if you haven't already.
OpenRTB supports several macros inside its response message, and the openrtb-core library includes a postprocessor that can expand most of these macros... just in case you're sending a response to some exchange that doesn't understand OpenRTB macros (like DoubleClick!). This library provides a specialized DoubleClickSnippetProcessor, which extends openrtb-core's macro preprocessor with additional support for DoubleClick. Specifically, the OpenRTB macro ${AUCTION_PRICE} is translated to DoubleClick's %%WINNING_PRICE%%.
DoubleClick has its own lists of bid response macros and cookie matching macros, which are all "server-side" so the macro processor here won't expand any of them.
The AdxExtUtils class will configure an openrtb-core-provided OpenRtbJsonFactory with support for DoubleClick's OpenRTB extension fields.
The openrtb-doubleclick library offers several facilities for DoubleClick RTB developers, still you would need significant more code to build a full builder, DSP, etc. You may want to look at Open Bidder, a complete toolkit for building scalable, full-featured RTB bidders, optimized for the Google Cloud Platform and DoubleClick but also extensible for other platforms and exchanges.