{"_id":"56fd66df5a08190e00084f02","parentDoc":null,"project":"56c35c56c0c4630d004e864c","version":{"_id":"56c35c56c0c4630d004e864f","project":"56c35c56c0c4630d004e864c","__v":8,"createdAt":"2016-02-16T17:28:54.864Z","releaseDate":"2016-02-16T17:28:54.864Z","categories":["56c35c57c0c4630d004e8650","56c7b9e5379b311700ed8fe3","56c7bab4606ee717003c4766","56c7bb3613e5400d001e8cbd","56cf3f5a5267d70b00494c4b","56cf3f866c5d7a13005ee894","56fd3956caad892200847bce","599da256e7742b002588bb02"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"0.5.0","version":"0.5"},"githubsync":"","user":"56c39c05bc41330d009f25d7","category":{"_id":"56c7b9e5379b311700ed8fe3","pages":["56c7ba3853cafe0d00a53daa"],"project":"56c35c56c0c4630d004e864c","version":"56c35c56c0c4630d004e864f","__v":1,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-20T00:57:09.551Z","from_sync":false,"order":2,"slug":"stinger","title":"Stinger"},"__v":2,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-31T18:05:19.185Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"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. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/10cf1d8-data_augmentor.png\",\n        \"data_augmentor.png\",\n        1067,\n        545,\n        \"#f4c35a\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Data Augmentation in Practice\"\n}\n[/block]\nReading 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. \n\nThe 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](doc:getting-started), and the [Segments](doc:segments) will show up in Buzz for targeting with no further customization. \n\nYou can find our Protobuf interface for our augmentor on [GitHub](https://github.com/BeeswaxIO/beeswax-api/blob/master/beeswax/augment/augmentor.proto). \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Example\"\n}\n[/block]\nRequirement: 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.\n\nSet-Up:\n1. In Buzz, you create segments for each decile. Buzz gives each segment a \"segment_key\" which looks something like \"buzz-123\"\n2.  You map the ten segment_keys to the ten deciles in your server\n3. In Buzz, you target the [Line Item](doc:line-items) to include these segments (UI or API)\n4. NOTE: You must set up at least one line_item in Buzz that targets a segment in order for augmentation to work at all.\n\nReal-Time Actions:\n1. The data augmentor receives the OpenRTB request on each auction\n2. The OpenRTB request is de-serialized and parsed\n3. The domain on the request is identified and used as the look up key\n4. Based on the lookup key, one or more segment_keys are found, each representing the \"brand safety score\" of the domain\n5. 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\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Data Interfaces and Tools\"\n}\n[/block]\nThe following are all the data interfaces used when implementing a bidding agent:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"File\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"[openrtb.proto](https://github.com/BeeswaxIO/beeswax-api/tree/master/beeswax/openrtb)\",\n    \"0-1\": \"Normalized OpenRTB 2.3 request. This is the full request stream.\",\n    \"1-0\": \"[augmentor.proto](https://github.com/BeeswaxIO/beeswax-api/blob/master/beeswax/augment/augmentor.proto)\",\n    \"1-1\": \"Data augmentor Protobuf\",\n    \"2-1\": \"This tool generates augmentor requests in binary protobuf format for local testing\",\n    \"2-0\": \"[Augmentor request generator](https://github.com/BeeswaxIO/beeswax-api/tree/master/beeswax/tools/augmentor)\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Request Minification\"\n}\n[/block]\nIn 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.\n\nObjects available:\n\n```Bidrequest_Imp\nBidrequest_Site\nBidrequest_App\nBidrequest_Device\nBidrequest_User\nBidrequest_Regs\nBidrequest_Ext```\n\nFields available:\n\n```app_bundle\napp_name\ndomain\nlat\nlon\ndisplaymanagerver\nuser_id\nbidrequest.user.buyeruid\nbidrequest.device.ifa\nbidrequest.device.dpidsha1\nbidrequest.device.dpidmd5\nbidrequest.device.os\nbidrequest.user.ext.user_id\nbidrequest.user.ext.user_id_type\nuser_agent```\n[block:api-header]\n{\n  \"title\": \"Response Codes\"\n}\n[/block]\nSee also: [Bidding Agent and Augmentor Response Codes](doc:bidding-agent-and-augmentor-response-codes).","excerpt":"","slug":"data-augmentation","type":"basic","title":"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. [block:image] { "images": [ { "image": [ "https://files.readme.io/10cf1d8-data_augmentor.png", "data_augmentor.png", 1067, 545, "#f4c35a" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "Data Augmentation in Practice" } [/block] 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](doc:getting-started), and the [Segments](doc:segments) will show up in Buzz for targeting with no further customization. You can find our Protobuf interface for our augmentor on [GitHub](https://github.com/BeeswaxIO/beeswax-api/blob/master/beeswax/augment/augmentor.proto). [block:api-header] { "type": "basic", "title": "Example" } [/block] 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](doc:line-items) 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 [block:api-header] { "type": "basic", "title": "Data Interfaces and Tools" } [/block] The following are all the data interfaces used when implementing a bidding agent: [block:parameters] { "data": { "h-0": "File", "h-1": "Description", "0-0": "[openrtb.proto](https://github.com/BeeswaxIO/beeswax-api/tree/master/beeswax/openrtb)", "0-1": "Normalized OpenRTB 2.3 request. This is the full request stream.", "1-0": "[augmentor.proto](https://github.com/BeeswaxIO/beeswax-api/blob/master/beeswax/augment/augmentor.proto)", "1-1": "Data augmentor Protobuf", "2-1": "This tool generates augmentor requests in binary protobuf format for local testing", "2-0": "[Augmentor request generator](https://github.com/BeeswaxIO/beeswax-api/tree/master/beeswax/tools/augmentor)" }, "cols": 2, "rows": 3 } [/block] [block:api-header] { "title": "Request Minification" } [/block] 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. Objects available: ```Bidrequest_Imp Bidrequest_Site Bidrequest_App Bidrequest_Device Bidrequest_User Bidrequest_Regs Bidrequest_Ext``` Fields available: ```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``` [block:api-header] { "title": "Response Codes" } [/block] See also: [Bidding Agent and Augmentor Response Codes](doc:bidding-agent-and-augmentor-response-codes).