{"_id":"56fd65e85ba02a0e00135790","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"},"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"},"project":"56c35c56c0c4630d004e864c","__v":4,"githubsync":"","parentDoc":null,"updates":["58a456f8b26c4a0f00fe5a25"],"next":{"pages":[],"description":""},"createdAt":"2016-03-31T18:01:12.504Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"Having your own \"bidding agent\" in Beeswax allows you to implement custom real-time decisioning in your private bidder. Common use cases for real-time decisioning include custom bid price algorithms,  custom budget pacing or custom creative decisioning including dynamic creatives. Bidding agents can be written in any language, they simply must be able to parse our data interfaces and respond within the strict timeout of 10ms. \n\nThe diagram below shows how a bidding agent for real time price decisioning works:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/c78f6cd-bidding_agent_diagram.png\",\n        \"bidding_agent_diagram.png\",\n        1250,\n        544,\n        \"#20564e\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Bidding Agents in Practice\"\n}\n[/block]\nReading from left to right in the diagram, the Stinger bidder receives a fully normalized open RTB request. Once it enters the bidder, Beeswax applies several layers of filtering to determine which line items configured in [Buzz](doc:getting-started) match the given request and ares thus eligible to serve. The layers of filtering include matching targeting and creative attributes, respecting any user-specific frequency caps, keeping within the daily and total budgets, and pacing evenly. What remains after filtering is a list of line items that are eligible to bid for this request – we call these `ad candidates` in our protobuf definitions. \n\nNext, the Private Bidder makes an HTTP POST containing the `request.proto` to a bidding agent outside of the Beeswax cloud, typically hosted by a customer in the same AWS Region. The request proto contains both the full openRTB request along with a list of the eligible line items. The Bidding Agent must receive this request, parse it, and either respond with an HTTP 204 to not bid, or an HTTP 200 with a list of line items and corresponding bid prices. We enforce a strict timeout of 10ms for your HTTP response, so it is important that your Bidding Agent is in the same AWS region and highly performant. \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\": \"[request.proto](https://github.com/BeeswaxIO/beeswax-api/blob/master/beeswax/bid/request.proto)\",\n    \"0-1\": \"The interface between the bidder and the bidding agent. Includes both the openRTB request and the adcandidates\",\n    \"1-0\": \"[openrtb.proto](https://github.com/BeeswaxIO/beeswax-api/tree/master/beeswax/openrtb)\",\n    \"1-1\": \"This proto is imported by the request.proto. It contains the full openRTB request\",\n    \"2-0\": \"[adcandidates.proto](https://github.com/BeeswaxIO/beeswax-api/blob/master/beeswax/bid/adcandidate.proto)\",\n    \"2-1\": \"This proto is imported by the request.proto. It contains all the candidate line items for the given request\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\nThe following tool can be used to stream sample bidding agent requests to an endpoint\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Tool\",\n    \"0-0\": \"[Bid requestor tool](https://github.com/BeeswaxIO/beeswax-api/tree/master/beeswax/tools/bid)\",\n    \"h-1\": \"Description\",\n    \"0-1\": \"This tools generates Beeswax bid http requests\\nand sends to a designated endpoint with http headers used in the bidding service\\nand http body generated from the specified input file.\"\n  },\n  \"cols\": 2,\n  \"rows\": 1\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Pacing-as-a-Service\"\n}\n[/block]\nA common technique for bidding algorithms is to \"pace\" buying during the day or over the lifetime of the campaign in order to deliver ads on a regular schedule. Beeswax supports what we call \"Pacing-as-a-Service\" for Bidding Agents where customers can utilize their own algorithms with our built-in pacing. This service works by filtering bids from your Bidding Agent based on the ratio of current delivery against goals.\n\nThere is no technical implementation required to utilize Beeswax pacing, as long as the strategy is set up to do so when first created by the Beeswax team.\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":"bidding-agent","type":"basic","title":"Bidding Agent"}
Having your own "bidding agent" in Beeswax allows you to implement custom real-time decisioning in your private bidder. Common use cases for real-time decisioning include custom bid price algorithms, custom budget pacing or custom creative decisioning including dynamic creatives. Bidding agents can be written in any language, they simply must be able to parse our data interfaces and respond within the strict timeout of 10ms. The diagram below shows how a bidding agent for real time price decisioning works: [block:image] { "images": [ { "image": [ "https://files.readme.io/c78f6cd-bidding_agent_diagram.png", "bidding_agent_diagram.png", 1250, 544, "#20564e" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "Bidding Agents in Practice" } [/block] Reading from left to right in the diagram, the Stinger bidder receives a fully normalized open RTB request. Once it enters the bidder, Beeswax applies several layers of filtering to determine which line items configured in [Buzz](doc:getting-started) match the given request and ares thus eligible to serve. The layers of filtering include matching targeting and creative attributes, respecting any user-specific frequency caps, keeping within the daily and total budgets, and pacing evenly. What remains after filtering is a list of line items that are eligible to bid for this request – we call these `ad candidates` in our protobuf definitions. Next, the Private Bidder makes an HTTP POST containing the `request.proto` to a bidding agent outside of the Beeswax cloud, typically hosted by a customer in the same AWS Region. The request proto contains both the full openRTB request along with a list of the eligible line items. The Bidding Agent must receive this request, parse it, and either respond with an HTTP 204 to not bid, or an HTTP 200 with a list of line items and corresponding bid prices. We enforce a strict timeout of 10ms for your HTTP response, so it is important that your Bidding Agent is in the same AWS region and highly performant. [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": "[request.proto](https://github.com/BeeswaxIO/beeswax-api/blob/master/beeswax/bid/request.proto)", "0-1": "The interface between the bidder and the bidding agent. Includes both the openRTB request and the adcandidates", "1-0": "[openrtb.proto](https://github.com/BeeswaxIO/beeswax-api/tree/master/beeswax/openrtb)", "1-1": "This proto is imported by the request.proto. It contains the full openRTB request", "2-0": "[adcandidates.proto](https://github.com/BeeswaxIO/beeswax-api/blob/master/beeswax/bid/adcandidate.proto)", "2-1": "This proto is imported by the request.proto. It contains all the candidate line items for the given request" }, "cols": 2, "rows": 3 } [/block] The following tool can be used to stream sample bidding agent requests to an endpoint [block:parameters] { "data": { "h-0": "Tool", "0-0": "[Bid requestor tool](https://github.com/BeeswaxIO/beeswax-api/tree/master/beeswax/tools/bid)", "h-1": "Description", "0-1": "This tools generates Beeswax bid http requests\nand sends to a designated endpoint with http headers used in the bidding service\nand http body generated from the specified input file." }, "cols": 2, "rows": 1 } [/block] [block:api-header] { "title": "Pacing-as-a-Service" } [/block] A common technique for bidding algorithms is to "pace" buying during the day or over the lifetime of the campaign in order to deliver ads on a regular schedule. Beeswax supports what we call "Pacing-as-a-Service" for Bidding Agents where customers can utilize their own algorithms with our built-in pacing. This service works by filtering bids from your Bidding Agent based on the ratio of current delivery against goals. There is no technical implementation required to utilize Beeswax pacing, as long as the strategy is set up to do so when first created by the Beeswax team. [block:api-header] { "title": "Response Codes" } [/block] See also: [Bidding Agent and Augmentor Response Codes](doc:bidding-agent-and-augmentor-response-codes).