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.
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.
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.
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.
- In Buzz, you create segments for each decile. Buzz gives each segment a "segment_key" which looks something like "buzz-123"
- You map the ten segment_keys to the ten deciles in your server
- In Buzz, you target the Line Item to include these segments (UI or API)
- NOTE: You must set up at least one line_item in Buzz that targets a segment in order for augmentation to work at all.
- The data augmentor receives the OpenRTB request on each auction
- The OpenRTB request is de-serialized and parsed
- The domain on the request is identified and used as the look up key
- Based on the lookup key, one or more segment_keys are found, each representing the "brand safety score" of the domain
- 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
The following are all the data interfaces used when implementing a bidding agent:
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_Site Bidrequest_App Bidrequest_Device Bidrequest_User Bidrequest_Regs Bidrequest_Ext
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
See also: Bidding Agent and Augmentor Response Codes.
Updated less than a minute ago