{"_id":"587d46ad8f1d7639002393fb","__v":1,"user":"56c39c05bc41330d009f25d7","project":"56c35c56c0c4630d004e864c","githubsync":"","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"},"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"},"parentDoc":null,"updates":["5a0c9b0300679b003479b263"],"next":{"pages":[],"description":""},"createdAt":"2017-01-16T22:18:21.746Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":9,"body":"Stinger supports the ability to pass dynamic variables into [Creatives](doc:creatives) in real time through a [Bidding Agent](doc:bidding-agent) or [Augmentor](doc:data-augmentation). This is an advanced use case, and can be very valuable when the bidding system needs to effect the display or behavior of the creative itself.\n\nExamples of how you can use dynamic variables include:\n* Loading a dynamic image into the creative after rendering\n* Passing a variable from the bidding agent or augmentor into the click URL so you can track your bidding decisions in your site analytics\n* Changing text within the creative in real-time, such as airline destination codes or discount pricing.\n\nThis document describes how to execute dynamic variables in each stage of your implementation.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Set-Up\"\n}\n[/block]\nFirst, it is important to realize that dynamic macros can only be executed in conjunction with a custom [Bidding Agent](doc:bidding-agent) or [Augmentor](doc:data-augmentation).\n\nSecond, you must ask the Beeswax team to enable your Buzz instance to allow dynamic macros.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Buzz DYNAMIC Macros\"\n}\n[/block]\nOnce your Buzz instance is enabled, you will able to use special [Macros](doc:macros) in your creatives that are intended to be replaced in real-time by your bidding agent. These macros are in the format:\n\n`{{DYNAMIC:<NAME>:STRING}}`\n\nFor example, if you wanted to pass the airline flight number into your creative, you might include a macro like this:\n\n`{{DYNAMIC:FLIGHT:STRING}}`\n\nUnlike custom macros, the type should always be `STRING`.\n\nThe macro itself will most commonly be included in the `creative_content` or `creative_content_tag` fields of the Creative, but they are also allowed in the `click_url`, `scripts` and `pixels` fields, as well as the [Creative Templates](doc:creativetemplates) and [Creative AddOns](doc:creative-addons) objects.\n\nThere is a maximum of five DYNAMIC macros per creative, including all fields listed above.\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Bidding Agent or Augmentor Implementation\"\n}\n[/block]\nThe values for the dynamic macros are provided in real-time from your bidding agent or augmentor. See the \"dynamic_macro\" message in the [request.proto](https://github.com/BeeswaxIO/beeswax-api/blob/master/beeswax/bid/request.proto) for more details. \n\n**Constraints of dynamic macros:**\n  * Up to 5 dynamic macros per creative are accepted from your bidding agent or augmentor, any macros above 5 will be ignored\n  * The dynamic macro \"name\" from your bidding agent or augmentor is case-insensitive (i.e. a name “foo” and a name of “FOO” will be treated as the same \"name\").\n  * Values cannot include other [Beeswax macros](http://docs.beeswax.com/docs/macros) or other dynamic macros (i.e. a value from your bidding agent of “foo{{USER_ID}}” is not valid). \n\n**Handling macros without values:**\n\nThere are two ways to handle dynamic macros without values. Firstly, you can simply not respond with the \"name\" and \"value\" fields from your bidding agent or augmentor. In this case the macro will not expand and will appear as {{DY:<NAME>}}. Secondly, you can respond with the \"name\" field but leave the \"value\" field blank. In this case the macro will expand to an empty string.  \n\n**Correctly escaping dynamic macros values when used within URLs**\n\nIf you are placing dynamic macros within URLs, you should handle the escaping of dynamic macro values differently:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"URL Type\",\n    \"h-1\": \"Correct URL Escaping\",\n    \"0-0\": \"Click URL\",\n    \"0-1\": \"Beeswax handles escaping of click URLs, so any dynamic value that is placed within a click URL only needs to be url-safe. It does not need to contain extra escaping.\",\n    \"1-0\": \"Other URLs (i.e. additional pixels, script URL, other URLs in your creative content)\",\n    \"1-1\": \"For all other URLs, beeswax does not handle escaping so all dynamic values should be both correctly escaped and url-safe.\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]","excerpt":"","slug":"dynamic-creatives-using-a-bidding-agent","type":"basic","title":"Dynamic Macros (Real-Time Custom Values)"}

Dynamic Macros (Real-Time Custom Values)


Stinger supports the ability to pass dynamic variables into [Creatives](doc:creatives) in real time through a [Bidding Agent](doc:bidding-agent) or [Augmentor](doc:data-augmentation). This is an advanced use case, and can be very valuable when the bidding system needs to effect the display or behavior of the creative itself. Examples of how you can use dynamic variables include: * Loading a dynamic image into the creative after rendering * Passing a variable from the bidding agent or augmentor into the click URL so you can track your bidding decisions in your site analytics * Changing text within the creative in real-time, such as airline destination codes or discount pricing. This document describes how to execute dynamic variables in each stage of your implementation. [block:api-header] { "type": "basic", "title": "Set-Up" } [/block] First, it is important to realize that dynamic macros can only be executed in conjunction with a custom [Bidding Agent](doc:bidding-agent) or [Augmentor](doc:data-augmentation). Second, you must ask the Beeswax team to enable your Buzz instance to allow dynamic macros. [block:api-header] { "type": "basic", "title": "Buzz DYNAMIC Macros" } [/block] Once your Buzz instance is enabled, you will able to use special [Macros](doc:macros) in your creatives that are intended to be replaced in real-time by your bidding agent. These macros are in the format: `{{DYNAMIC:<NAME>:STRING}}` For example, if you wanted to pass the airline flight number into your creative, you might include a macro like this: `{{DYNAMIC:FLIGHT:STRING}}` Unlike custom macros, the type should always be `STRING`. The macro itself will most commonly be included in the `creative_content` or `creative_content_tag` fields of the Creative, but they are also allowed in the `click_url`, `scripts` and `pixels` fields, as well as the [Creative Templates](doc:creativetemplates) and [Creative AddOns](doc:creative-addons) objects. There is a maximum of five DYNAMIC macros per creative, including all fields listed above. [block:api-header] { "type": "basic", "title": "Bidding Agent or Augmentor Implementation" } [/block] The values for the dynamic macros are provided in real-time from your bidding agent or augmentor. See the "dynamic_macro" message in the [request.proto](https://github.com/BeeswaxIO/beeswax-api/blob/master/beeswax/bid/request.proto) for more details. **Constraints of dynamic macros:** * Up to 5 dynamic macros per creative are accepted from your bidding agent or augmentor, any macros above 5 will be ignored * The dynamic macro "name" from your bidding agent or augmentor is case-insensitive (i.e. a name “foo” and a name of “FOO” will be treated as the same "name"). * Values cannot include other [Beeswax macros](http://docs.beeswax.com/docs/macros) or other dynamic macros (i.e. a value from your bidding agent of “foo{{USER_ID}}” is not valid). **Handling macros without values:** There are two ways to handle dynamic macros without values. Firstly, you can simply not respond with the "name" and "value" fields from your bidding agent or augmentor. In this case the macro will not expand and will appear as {{DY:<NAME>}}. Secondly, you can respond with the "name" field but leave the "value" field blank. In this case the macro will expand to an empty string. **Correctly escaping dynamic macros values when used within URLs** If you are placing dynamic macros within URLs, you should handle the escaping of dynamic macro values differently: [block:parameters] { "data": { "h-0": "URL Type", "h-1": "Correct URL Escaping", "0-0": "Click URL", "0-1": "Beeswax handles escaping of click URLs, so any dynamic value that is placed within a click URL only needs to be url-safe. It does not need to contain extra escaping.", "1-0": "Other URLs (i.e. additional pixels, script URL, other URLs in your creative content)", "1-1": "For all other URLs, beeswax does not handle escaping so all dynamic values should be both correctly escaped and url-safe." }, "cols": 2, "rows": 2 } [/block]