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.
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
## Data Interfaces and Tools
The following are all the data interfaces used when implementing a bidding agent:
|[openrtb.proto](🔗)||Normalized OpenRTB 2.3 request. This is the full request stream.|
|[augmentor.proto](🔗)||Data augmentor Protobuf|
|[Augmentor request generator](🔗)||This tool generates augmentor requests in binary protobuf format for local testing|
## 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.