Data Augmentation

Customization of the incoming request with first party data is what we call "data augmentation". An augmentor is typically a simple key-value lookup with a very short latency window (10ms). Use cases for data augmentation include custom geo databases, mapping of users to rich profiles, and scoring of inventory data. The diagram below shows how data augmentation fits into the Beeswax stack.

Data Augmentation in Practice

Reading from left to right in the diagram, the data augmentor receives a fully normalized open RTB request via an HTTP POST containing the openrtb.proto. The data augmentor must respond with either an HTTP 204 response if no augmentation was performed, or a 200 along with a list of segment objects as key-value pairs. The segment object schema is defined in the protocol buffer interface and allows you to send custom keys using the id field and custom values using the value field. If the data augmentor does not successfully respond, Beeswax will drop the request and will not forward it to your custom bidder instance. This means no other campaigns will be eligible to bid for the given request.

The segment key-values are then be added to the original RTB request, as represented by the "Auctions with Custom Segments" stream above. With the segments now available in the request stream you can now create those segments in Buzz, and the Segments will show up in Buzz for targeting with no further customization.

You can find our Protobuf interface for our augmentor on GitHub.

Example

Requirement: You have created a database that scores the brand safety of a given domain in deciles from 0.1 to 1.0. You wish to only target a given Line Item to domains with a brand safety of 0.9 or higher.

Set-Up:

1. In Buzz, you create segments for each decile. Buzz gives each segment a "segment_key" which looks something like "buzz-123"
2. You map the ten segment_keys to the ten deciles in your server
3. In Buzz, you target the Line Item to include these segments (UI or API)
4. NOTE: You must set up at least one line_item in Buzz that targets a segment in order for augmentation to work at all.

Real-Time Actions:

1. The data augmentor receives the OpenRTB request on each auction
2. The OpenRTB request is de-serialized and parsed
3. The domain on the request is identified and used as the look up key
4. Based on the lookup key, one or more segment_keys are found, each representing the "brand safety score" of the domain
5. The segment keys are returned as key-value pairs (the value isn't used in this case) and are sent to the Stinger bidder for matching

Data Interfaces and Tools

The following are all the data interfaces used when implementing a Data Augmenter:

Request Minification

In order to reduce bandwidth between the Beeswax system and the Augmentor, the request sent can be minified to just the fields or objects required by the customer. In addition, we can filter requests to the augmentor based on which (if any) fields or objects must be present in order to qualify for augmentation.

Bidrequest_Imp
Bidrequest_Site
Bidrequest_App
Bidrequest_Device
Bidrequest_User
Bidrequest_Regs
Bidrequest_Ext

app_bundle
app_name
domain
lat
lon
displaymanagerver
user_id
bidrequest.user.buyeruid
bidrequest.device.ifa
bidrequest.device.dpidsha1
bidrequest.device.dpidmd5
bidrequest.device.os
bidrequest.user.ext.user_id
bidrequest.user.ext.user_id_type
user_agent

Response Codes

See also: Bidding Agent and Augmentor Response Codes.