{"_id":"56cbab9c9f4ae20b00644f76","category":{"_id":"56c7bab4606ee717003c4766","project":"56c35c56c0c4630d004e864c","__v":18,"pages":["56c7c193f9aa3b0d00c8458f","56cb80a4c675f50b00a4b826","56cb83859f4ae20b00644f1f","56cb853a245b841300806f82","56cb863c32011d2500681925","56cb88a4245b841300806f8b","56cb9915245b841300806fa7","56cb9a079f4ae20b00644f48","56cb9b5bc675f50b00a4b859","56cba5929f4ae20b00644f5d","56cba5c5d5c6241d00ef5e93","56cbab9c9f4ae20b00644f76","56cbad69c675f50b00a4b881","56cbb060d5c6241d00ef5ebb","56cf3c4d6c5d7a13005ee88c","56cf3d0e287eb20b009f9ec7","56cf3d7c5267d70b00494c42","56cf3ee0287eb20b009f9ecd"],"version":"56c35c56c0c4630d004e864f","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-20T01:00:36.607Z","from_sync":false,"order":0,"slug":"buzz-concepts","title":"Buzz Concepts"},"parentDoc":null,"user":"56c39c05bc41330d009f25d7","project":"56c35c56c0c4630d004e864c","__v":12,"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":"","updates":["575c3a3d57b1c00e00557085","576d4baaa39bbf0e00db52ec","591b61c58f2e010f00d382c8","591b6303e633fd0f00077f8d","591b68ebe633fd0f000781cc","59f8d1986b772600307c8615"],"next":{"pages":[],"description":""},"createdAt":"2016-02-23T00:45:16.143Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"This document explains how Buzz handles Creatives. Creatives are a complex subject since they must be flexible enough to support both third-party tags and hosted creatives, and are an element that end-users spend a great deal of time working with.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Overview of Creative-Related Objects\"\n}\n[/block]\nThe diagram below describes the objects in Buzz to support [Creatives](doc:creatives). Creatives belong to a single [Advertiser](doc:advertisers), and can be associated with one or more [Line Items](doc:line-items). When Creatives change, those changes instantly affect all Line Items to which they are associated.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/kUEFMDETRAOKIHGyZiXI_Buzz%20Creatives.png\",\n        \"Buzz Creatives.png\",\n        \"800\",\n        \"600\",\n        \"#667e96\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Using Ad Tags from Another Server\"\n}\n[/block]\nA typical use case for Creatives is to upload ad tags from another server, like Atlas or DoubleClick. Accomplishing this using Buzz is very simple. Using the API, create a new Creative object, choose a `creative_template` for the tag type and set the `creative_content_tag` field to the tag content. The API request would look something like this:\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST \\\"[host]/rest/creative\\\" -b cookies.txt -d '{\\\"account_id\\\":1, \\\"advertiser_id\\\":\\\"1\\\", \\\"creative_type_id\\\":0, \\\"width\\\":768,\\\"height\\\":160, \\\"creative_name\\\":\\\"foo\\\", \\\"creative_template_id\\\":4, \\\"creative_content_tag\\\":\\\"https://ad.server.com/parameters?other&params\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nA second very common activity is to wish to replace any click-through URLs in the ad tags with a macro to allow your ad server to redirect the click first, before sending the end-user's browser to the click-through URL in the ad tags. We can accomplish this with a Creative Rule.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Creative Rules\"\n}\n[/block]\nA Creative Rule is like a regular expression that replaces strings within the creative content before saving the object. Creative Rules are created and maintained by the system administrators.\n\nCreative Rules each have a `key` that is passed as a field to the Creative, for example to use the rule for DoubleClick's DFA ad server, you can use the key `dfa`. There's also the helpful `auto_detect` tag. To use a Creative Rule you would add the `creative_rule_key` parameter to the Creative request:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST \\\"[host]/rest/creative\\\" -b cookies.txt -d '{\\\"account_id\\\":1, \\\"advertiser_id\\\":1, \\\"creative_type_id\\\":0, \\\"width\\\":728,\\\"height\\\":90, \\\"creative_name\\\":\\\"foo\\\", \\\"creative_content_tag\\\":\\\"https://ad.server.com/parameters?other&params\\\", \\\"creative_rule_key\\\":\\\"dfa\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Uploading Creative to Buzz\"\n}\n[/block]\nUsers will often want to upload Creatives directly to Buzz, and not use a third party ad server. There are also cases where the user wants to wrap the ad tags from a third party in their own HTML code. For both of these cases, the recommended way to accomplish the task is with a Creative Template. \n\nCreative Templates do two things:\n* First, they define the body of the Creative to be delivered to the user. This is typically HTML and Javascript for banners, or XML for video, but could be any text-based scripting.\n* Second, they define the elements that will be customized within the template for each Creative. These elements are defined by Creative Macros.\n\nHere's a simple example of what we want the Creative to look like when sent to the bidder:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \" <a href=\\\"{{CLICK}}\\\"><img src=\\\"http://path_to_file/filename.gif\\\"></a>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nIn the example above, let's assume that `{{CLICK}}` is a macro that will be auto expanded by the ad server at the time the ad is served, rather than something the user of Buzz needs to be concerned about. There are three steps to accomplishing this task: Finding the correct Creative Template, creating the Creative Assets, and bringing it all together in the Creative itself.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Creative Template and Custom Macros\"\n}\n[/block]\nLike Creative Rules, Creative Templates belong to Accounts and can be created by the system administrator as `global` and thus available to all Accounts. We do not currently allow custom Creative Templates.\n\nCreative Templates are just code snippets for rendering Creatives. The trick in creating them is including Custom Macros that must be filled at the time the Creative is created. The syntax for Custom Macros is:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{CUSTOM:<NAME>:<TYPE>}}\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nMacros must start and end with double curlys like `{{FOO}}`. Macros must have a unique name, with no space and it is recommended that the name be ALL CAPS. Types are used to validate input when Creatives are created, but have no effect on serving or delivery. Types are described in more detail later in this document. So if we look at Creative Template `1`, it is the `Image Template`. The content of template 1 looks like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<a href='{{CLICK_URL}}' target='_blank'><img src='{{CUSTOM:IMAGE_NAME:FILE}}' alt='tap here' width='{{WIDTH}}' height='{{HEIGHT}}'></a><img src='{{IMPRESSION_URL}}' width='0' height='0'>\\n{{#ADDITIONAL_PIXELS:0:10<img src='{{CUSTOM:PIXEL_URL:URL}}' width='0' height='0'>/}}\\n{{#ADDITIONAL_SCRIPTS:0:10<script type='text/javascript' src='{{CUSTOM:SCRIPT_URL:URL}}'></script>/}}\\n{{BEESWAX_COOKIE_SYNC_IFRAME}}\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Creative Assets\"\n}\n[/block]\nThe next thing we need to do is upload the image file itself. This is accomplished using the [Creative Assets](doc:creative-assets) API method. Note, in a typical UI-centric scenario, the user would upload the assets as part of the same workflow as building the Creative, but from an API perspective these are different tasks. Uploading Creative Assets is a two-step process. First you POST to create a shell for the object, including the name and size. Then, using the ID that was provided by the POST, you upload the asset itself.\n\nStep 1: Create the Asset\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST \\\"[host]/rest/creative_asset\\\" -b cookies.txt -d '{\\\"account_id\\\":1, \\\"creative_asset_name\\\":\\\"test.jpg\\\", \\\"size_in_bytes\\\":11500, \\\"advertiser_id\\\":1}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nResult:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n \\\"success\\\": \\\"true\\\",\\n \\\"payload\\\": \\\"creative_asset created with ID = 5\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nStep 2: Upload the asset\n* We use a POST request to update, instead of a typical PUT\n* We use curl -F to send a file and post `\"creative_content=:::at:::filename\"`\n* The REST URL is slightly different as well with the syntax `/upload/[ID]`\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST -F \\\"creative_content=@test.jpg\\\" \\\"[host]/rest/creative_asset/upload/5\\\" -b cookies.txt\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nResult:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n \\\"success\\\": \\\"true\\\",\\n \\\"payload\\\": \\\"creative_asset updated with ID = 5\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThe Asset is now uploaded to the Buzz CDN and can be included in a Creative. When possible, the Creative Asset will also include thumbnail images and metadata about size and mime-types.The full path to the URL of the asset can be retrieved with a GET request to that same asset ID:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"path_to_buzz/buzz/rest/creative_asset/5\\\" -b cookies.txt\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Creatives Using Templates: The Hard Way\"\n}\n[/block]\nThe final step is to create the Creative itself using the uploaded Asset and the Template. You do not post free-form content into the `creative_content` field, as we did in the tag example earlier. Instead, the content for the creative is a JSON-formatted set of values to be used in the associated template. The evaluation of this JSON is strict, in that every macro within the template must be present in the JSON and no extra fields may be present in the JSON that are not in the template. The template we created expects one and only one macro, for the field `IMAGE_NAME` with the type `FILE`. Our JSON should then look like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\\"creative_fields\\\":{\\\"IMAGE_NAME\\\":\\\"http://path/to/file.gif\\\"}}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nAnd putting this all together our API call to create the Creative should look like this (assume template_id=1):\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST \\\"[host]/rest/creative\\\" -b cookies.txt -d '{advertiser_id\\\":1, \\\"creative_type_id\\\":0, \\\"width\\\":728, \\\"height\\\":90, \\\"creative_name\\\":\\\"banner\\\", \\\"creative_template_id\\\":1, \\\"creative_content\\\":{\\\"creative_fields\\\":{\\\"IMAGE_NAME\\\":\\\"http://path/to/file.gif\\\"}}}'\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Creatives Using Templates: The Slightly Easier Way\"\n}\n[/block]\nEach CreativeTemplate has a field `\"rendering_key\"` that indicated which \"type\" of Creative it is and the corresponding assets it expects. That's Buzz's way of making the association of assets to Creatives a lot easier and making sure the proper types and number of assets are uploaded. For an IMAGE rendering, Buzz expects one and only one asset, and the mime-type of the asset must be an image type. Instead of manually editing the JSON in the `creative_content` field, we POST to the creative with just the ID of the Asset in the `creative_assets` field (999 in this example), like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST \\\"[host]/rest/creative\\\" -b cookies.txt -d '{advertiser_id\\\":1, \\\"creative_type_id\\\":0, \\\"width\\\":728, \\\"height\\\":90, \\\"creative_name\\\":\\\"banner\\\", \\\"creative_template_id\\\":1, \\\"creative_assets\\\":[999]}]}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nFor video types, where there is a second asset for a companion, you would need to pass both the video and image assets as a list of IDs. (Note, there are two fields at the creative level named `primary_asset` and `secondary_asset`, but these fields are deprecated and the `creative_assets` field should be used instead).\n\nBuzz supports video assets and the transcoding of video assets. In order to upload a video asset, you use the same POST method described above but change the object from creative_asset to video_asset:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \" curl -X POST \\\"[host]/rest/video_asset\\\" -b cookies.txt -d '{\\\"creative_asset_name\\\":\\\"video.mp4\\\", \\\"size_in_bytes\\\":200500, \\\"advertiser_id\\\":1}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nYou can also pass an optional parameter to indicate which Video Encoding Profile to use. These profiles are defined at the system level and determine the number of transcodes to create and the encoding parameters to use. By default the `default` profile is used. Profiles may not be edited by the user, only the system administrator. The second step is to upload the video file with a POST:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST -F \\\"creative_content=@video.mp4\\\" \\\"[host]/rest/video_asset/upload/5\\\" -b cookies.txt\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nUnlike creative assets, the video asset will not be active as soon as posted. Instead, there is an asynchronous process for transcoding the video, which can take up to several minutes. Once the video transcoding has completed, the original video asset will be created, a thumbnail will be assigned, and additional video assets will be created for each new copy. To see all the assets created from a single origin file (id=5):\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"[host]/rest/video_asset\\\" -b cookies.txt -d '{\\\"original_video_object\\\":\\\"5\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"More on Macros\"\n}\n[/block]\nBuzz supports two kinds of Macros:\n* System Macros which are expanded by the ad server at the time of delivery. Examples include click-through URLs, the height and width of the creative, the country-code of the user seeing the ad, etc. See: Macros.\n* Custom Macros, which must be replaced at the time the Creative is associated with the template.\n\nThe only interaction Buzz has with System Macros is to validate that any included in a Template are valid. A list of valid System Macros is kept in the macros table of the MySQL database. System macros are always in the form `MACRO_NAME` with no additional parameters. Custom Macros, as described above, are created per template and are in the form:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \" {{CUSTOM:<NAME>:<TYPE>}}\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nValid types are as follows:\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"`INT`\",\n    \"0-1\": \"Must be a positive integer\",\n    \"1-0\": \"`STRING`\",\n    \"1-1\": \"String, may be blank if passed as \\\"\\\"\",\n    \"2-0\": \"`NUMBER`\",\n    \"2-1\": \"Any number\",\n    \"3-0\": \"`URL`\",\n    \"3-1\": \"Valid URL\",\n    \"4-0\": \"`FILE`\",\n    \"4-1\": \"Valid URL. This is a different type to hint both the user and a UI as to what is expected.\",\n    \"h-0\": \"Custom Macro Type\",\n    \"h-1\": \"Description\"\n  },\n  \"cols\": 2,\n  \"rows\": 5\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"About Creative Asset Filenames and Paths\"\n}\n[/block]\nWhen Creative Assets are uploaded to Buzz, they are placed onto a CDN in a specific naming format as follows: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"http://[CDN path]/[account_id]/[advertiser_id]/[creative_asset_id]_[original_name].[ext]\",\n      \"language\": \"text\",\n      \"name\": \" \"\n    }\n  ]\n}\n[/block]\nSo if you upload test.gif to advertiser 123 and account 345 on S3, your URL might look like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"http://buzz-creative-assets/345/123/upload.gif\",\n      \"language\": \"text\",\n      \"name\": \" \"\n    }\n  ]\n}\n[/block]\nIf Buzz can create a thumbnail it will be here: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"http://buzz-creative-assets/345/123/thumb/upload_thumb.gif\",\n      \"language\": \"text\",\n      \"name\": \" \"\n    }\n  ]\n}\n[/block]\nFor original videos, the location is:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"http://buzz-creative-assets/345/123/video/movie.mp4\",\n      \"language\": \"text\",\n      \"name\": \" \"\n    }\n  ]\n}\n[/block]\nAnd the encoded versions might be: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"http://buzz-creative-assets/345/123/encoded/movie_iphone.mp4\\nhttp://buzz-creative-assets/345/123/encoded/movie_flash.flv\",\n      \"language\": \"text\",\n      \"name\": \" \"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Macro Blocks\"\n}\n[/block]\nBuzz supports the concept of repeating Macro Blocks. There are certain use-cases, such as within VAST XML documents, when you wish to allow a number of repeating blocks of content depending on which data is provided by the end user. Suppose we want a portion of our template to look something like this, with any number of url blocks:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<urls>\\n<url>\\n<click>\\\"http://path_to_url+/\\\"</click>\\n<name>name of click</name></url>\\n<url>\\n<click>\\\"http://path_to_url+/\\\"</click>\\n<name>name of click</name></url>\\n<url>\\n<click>\\\"http://path_to_url+/\\\"</click>\\n<name>name of click</name></url>\\n</urls>\",\n      \"language\": \"xml\"\n    }\n  ]\n}\n[/block]\nTo do this in a Creative Template you use a Macro Block with Custom Macros within the block. The syntax of a Macro Block is:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{#NAME:<min>:<max> ...content and other macros … /}}\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nWhere min is the minimum number of blocks required, and max is the maximum. If the block may be omitted min should be set to zero. If there is no maximum, the max field may be omitted. \nSo our template above might look like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<urls>\\n{{#URL:1:5<url>\\n<click>{{CUSTOM:URL_CLICK:URL}}</click>\\n<name>{{CUSTOM:URL_NAME:STRING}}</name></url>/}}\\n</urls>\",\n      \"language\": \"xml\"\n    }\n  ]\n}\n[/block]\nAnd when we use the API to create a Creative we would put the corresponding data into an array like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\\"creative_fields\\\":\\n{\\\"URL\\\":[\\n{\\\"URL_CLICK:\\\"http://path/to/click\\\",\\\"URL_NAME\\\":\\\"name goes here\\\"},\\n{\\\"URL_CLICK:\\\"http://path/to/click\\\",\\\"URL_NAME\\\":\\\"name goes here\\\"},\\n{\\\"URL_CLICK:\\\"http://path/to/click\\\",\\\"URL_NAME\\\":\\\"name goes here\\\"}\\n]}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Creative AddOns\"\n}\n[/block]\nA [Creative AddOn](doc:creative-addons) is a pixel or script that needs to be added to the Creative when it is displayed to the user. AddOns allow you to define a given URL once, then use it with many Creatives across Campaigns and Line Items.\n[block:api-header]\n{\n  \"title\": \"Generating Creative Previews\"\n}\n[/block]\nThe Buzz API supports the generation and serving of realistic previews of Creatives with temporary values replacing any [Macros](doc:macros) within the markup. The process for generating a creative preview is as follows:\n\n1. Create the [Creative](doc:creatives) and make it active. This can be done using the API or the UI.\n2. Make a [GET](doc:creative-2) request to the creative endpoint. If the Creative is ready for preview, the `preview_token` field will be non-null in the response. If the `preview_token` field is null, it generally means that the creative is not active or that the creative assets are not yet ready, for example if transcoding is not yet complete.\n3. Make a GET call to the following URL with `[host]` replaced with the path for your Buzz API instance and `[preview_token]` replaced with the value from above:\n\n`https://[host]/buzz/public/CreativePreview.php?token=[preview_token]`\n\n**Video Preview:** If you are previewing a VAST video creative, the preview will return the XML of the document. In order to see a video player and observe video events being fired add the parameter `&template=video_preview` to the URL.\n\n**Macros Values:** When previewing the creative macros are filled with temporary values not reflective of the values that will be replaced during actual serving. For example, all numeric values are replaced with the string `12345`.","excerpt":"","slug":"creatives-creative-assets-templates-rules","type":"basic","title":"Creatives, Creative Assets, Templates, Rules"}

Creatives, Creative Assets, Templates, Rules


This document explains how Buzz handles Creatives. Creatives are a complex subject since they must be flexible enough to support both third-party tags and hosted creatives, and are an element that end-users spend a great deal of time working with. [block:api-header] { "type": "basic", "title": "Overview of Creative-Related Objects" } [/block] The diagram below describes the objects in Buzz to support [Creatives](doc:creatives). Creatives belong to a single [Advertiser](doc:advertisers), and can be associated with one or more [Line Items](doc:line-items). When Creatives change, those changes instantly affect all Line Items to which they are associated. [block:image] { "images": [ { "image": [ "https://files.readme.io/kUEFMDETRAOKIHGyZiXI_Buzz%20Creatives.png", "Buzz Creatives.png", "800", "600", "#667e96", "" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "Using Ad Tags from Another Server" } [/block] A typical use case for Creatives is to upload ad tags from another server, like Atlas or DoubleClick. Accomplishing this using Buzz is very simple. Using the API, create a new Creative object, choose a `creative_template` for the tag type and set the `creative_content_tag` field to the tag content. The API request would look something like this: [block:code] { "codes": [ { "code": "curl -X POST \"[host]/rest/creative\" -b cookies.txt -d '{\"account_id\":1, \"advertiser_id\":\"1\", \"creative_type_id\":0, \"width\":768,\"height\":160, \"creative_name\":\"foo\", \"creative_template_id\":4, \"creative_content_tag\":\"https://ad.server.com/parameters?other&params\"}'", "language": "curl" } ] } [/block] A second very common activity is to wish to replace any click-through URLs in the ad tags with a macro to allow your ad server to redirect the click first, before sending the end-user's browser to the click-through URL in the ad tags. We can accomplish this with a Creative Rule. [block:api-header] { "type": "basic", "title": "Creative Rules" } [/block] A Creative Rule is like a regular expression that replaces strings within the creative content before saving the object. Creative Rules are created and maintained by the system administrators. Creative Rules each have a `key` that is passed as a field to the Creative, for example to use the rule for DoubleClick's DFA ad server, you can use the key `dfa`. There's also the helpful `auto_detect` tag. To use a Creative Rule you would add the `creative_rule_key` parameter to the Creative request: [block:code] { "codes": [ { "code": "curl -X POST \"[host]/rest/creative\" -b cookies.txt -d '{\"account_id\":1, \"advertiser_id\":1, \"creative_type_id\":0, \"width\":728,\"height\":90, \"creative_name\":\"foo\", \"creative_content_tag\":\"https://ad.server.com/parameters?other&params\", \"creative_rule_key\":\"dfa\"}'", "language": "curl" } ] } [/block] [block:api-header] { "type": "basic", "title": "Uploading Creative to Buzz" } [/block] Users will often want to upload Creatives directly to Buzz, and not use a third party ad server. There are also cases where the user wants to wrap the ad tags from a third party in their own HTML code. For both of these cases, the recommended way to accomplish the task is with a Creative Template. Creative Templates do two things: * First, they define the body of the Creative to be delivered to the user. This is typically HTML and Javascript for banners, or XML for video, but could be any text-based scripting. * Second, they define the elements that will be customized within the template for each Creative. These elements are defined by Creative Macros. Here's a simple example of what we want the Creative to look like when sent to the bidder: [block:code] { "codes": [ { "code": " <a href=\"{{CLICK}}\"><img src=\"http://path_to_file/filename.gif\"></a>", "language": "html" } ] } [/block] In the example above, let's assume that `{{CLICK}}` is a macro that will be auto expanded by the ad server at the time the ad is served, rather than something the user of Buzz needs to be concerned about. There are three steps to accomplishing this task: Finding the correct Creative Template, creating the Creative Assets, and bringing it all together in the Creative itself. [block:api-header] { "type": "basic", "title": "Creative Template and Custom Macros" } [/block] Like Creative Rules, Creative Templates belong to Accounts and can be created by the system administrator as `global` and thus available to all Accounts. We do not currently allow custom Creative Templates. Creative Templates are just code snippets for rendering Creatives. The trick in creating them is including Custom Macros that must be filled at the time the Creative is created. The syntax for Custom Macros is: [block:code] { "codes": [ { "code": "{{CUSTOM:<NAME>:<TYPE>}}", "language": "text" } ] } [/block] Macros must start and end with double curlys like `{{FOO}}`. Macros must have a unique name, with no space and it is recommended that the name be ALL CAPS. Types are used to validate input when Creatives are created, but have no effect on serving or delivery. Types are described in more detail later in this document. So if we look at Creative Template `1`, it is the `Image Template`. The content of template 1 looks like this: [block:code] { "codes": [ { "code": "<a href='{{CLICK_URL}}' target='_blank'><img src='{{CUSTOM:IMAGE_NAME:FILE}}' alt='tap here' width='{{WIDTH}}' height='{{HEIGHT}}'></a><img src='{{IMPRESSION_URL}}' width='0' height='0'>\n{{#ADDITIONAL_PIXELS:0:10<img src='{{CUSTOM:PIXEL_URL:URL}}' width='0' height='0'>/}}\n{{#ADDITIONAL_SCRIPTS:0:10<script type='text/javascript' src='{{CUSTOM:SCRIPT_URL:URL}}'></script>/}}\n{{BEESWAX_COOKIE_SYNC_IFRAME}}", "language": "html" } ] } [/block] [block:api-header] { "type": "basic", "title": "Creative Assets" } [/block] The next thing we need to do is upload the image file itself. This is accomplished using the [Creative Assets](doc:creative-assets) API method. Note, in a typical UI-centric scenario, the user would upload the assets as part of the same workflow as building the Creative, but from an API perspective these are different tasks. Uploading Creative Assets is a two-step process. First you POST to create a shell for the object, including the name and size. Then, using the ID that was provided by the POST, you upload the asset itself. Step 1: Create the Asset [block:code] { "codes": [ { "code": "curl -X POST \"[host]/rest/creative_asset\" -b cookies.txt -d '{\"account_id\":1, \"creative_asset_name\":\"test.jpg\", \"size_in_bytes\":11500, \"advertiser_id\":1}'", "language": "curl" } ] } [/block] Result: [block:code] { "codes": [ { "code": "{\n \"success\": \"true\",\n \"payload\": \"creative_asset created with ID = 5\"\n}", "language": "json" } ] } [/block] Step 2: Upload the asset * We use a POST request to update, instead of a typical PUT * We use curl -F to send a file and post `"creative_content=@filename"` * The REST URL is slightly different as well with the syntax `/upload/[ID]` [block:code] { "codes": [ { "code": "curl -X POST -F \"creative_content=@test.jpg\" \"[host]/rest/creative_asset/upload/5\" -b cookies.txt", "language": "curl" } ] } [/block] Result: [block:code] { "codes": [ { "code": "{\n \"success\": \"true\",\n \"payload\": \"creative_asset updated with ID = 5\"\n}", "language": "json" } ] } [/block] The Asset is now uploaded to the Buzz CDN and can be included in a Creative. When possible, the Creative Asset will also include thumbnail images and metadata about size and mime-types.The full path to the URL of the asset can be retrieved with a GET request to that same asset ID: [block:code] { "codes": [ { "code": "curl -X GET \"path_to_buzz/buzz/rest/creative_asset/5\" -b cookies.txt", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "Creatives Using Templates: The Hard Way" } [/block] The final step is to create the Creative itself using the uploaded Asset and the Template. You do not post free-form content into the `creative_content` field, as we did in the tag example earlier. Instead, the content for the creative is a JSON-formatted set of values to be used in the associated template. The evaluation of this JSON is strict, in that every macro within the template must be present in the JSON and no extra fields may be present in the JSON that are not in the template. The template we created expects one and only one macro, for the field `IMAGE_NAME` with the type `FILE`. Our JSON should then look like this: [block:code] { "codes": [ { "code": "{\"creative_fields\":{\"IMAGE_NAME\":\"http://path/to/file.gif\"}}", "language": "json" } ] } [/block] And putting this all together our API call to create the Creative should look like this (assume template_id=1): [block:code] { "codes": [ { "code": "curl -X POST \"[host]/rest/creative\" -b cookies.txt -d '{advertiser_id\":1, \"creative_type_id\":0, \"width\":728, \"height\":90, \"creative_name\":\"banner\", \"creative_template_id\":1, \"creative_content\":{\"creative_fields\":{\"IMAGE_NAME\":\"http://path/to/file.gif\"}}}'", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "Creatives Using Templates: The Slightly Easier Way" } [/block] Each CreativeTemplate has a field `"rendering_key"` that indicated which "type" of Creative it is and the corresponding assets it expects. That's Buzz's way of making the association of assets to Creatives a lot easier and making sure the proper types and number of assets are uploaded. For an IMAGE rendering, Buzz expects one and only one asset, and the mime-type of the asset must be an image type. Instead of manually editing the JSON in the `creative_content` field, we POST to the creative with just the ID of the Asset in the `creative_assets` field (999 in this example), like this: [block:code] { "codes": [ { "code": "curl -X POST \"[host]/rest/creative\" -b cookies.txt -d '{advertiser_id\":1, \"creative_type_id\":0, \"width\":728, \"height\":90, \"creative_name\":\"banner\", \"creative_template_id\":1, \"creative_assets\":[999]}]}'", "language": "curl" } ] } [/block] For video types, where there is a second asset for a companion, you would need to pass both the video and image assets as a list of IDs. (Note, there are two fields at the creative level named `primary_asset` and `secondary_asset`, but these fields are deprecated and the `creative_assets` field should be used instead). Buzz supports video assets and the transcoding of video assets. In order to upload a video asset, you use the same POST method described above but change the object from creative_asset to video_asset: [block:code] { "codes": [ { "code": " curl -X POST \"[host]/rest/video_asset\" -b cookies.txt -d '{\"creative_asset_name\":\"video.mp4\", \"size_in_bytes\":200500, \"advertiser_id\":1}'", "language": "curl" } ] } [/block] You can also pass an optional parameter to indicate which Video Encoding Profile to use. These profiles are defined at the system level and determine the number of transcodes to create and the encoding parameters to use. By default the `default` profile is used. Profiles may not be edited by the user, only the system administrator. The second step is to upload the video file with a POST: [block:code] { "codes": [ { "code": "curl -X POST -F \"creative_content=@video.mp4\" \"[host]/rest/video_asset/upload/5\" -b cookies.txt", "language": "curl" } ] } [/block] Unlike creative assets, the video asset will not be active as soon as posted. Instead, there is an asynchronous process for transcoding the video, which can take up to several minutes. Once the video transcoding has completed, the original video asset will be created, a thumbnail will be assigned, and additional video assets will be created for each new copy. To see all the assets created from a single origin file (id=5): [block:code] { "codes": [ { "code": "curl -X GET \"[host]/rest/video_asset\" -b cookies.txt -d '{\"original_video_object\":\"5\"}'", "language": "curl" } ] } [/block] [block:api-header] { "type": "basic", "title": "More on Macros" } [/block] Buzz supports two kinds of Macros: * System Macros which are expanded by the ad server at the time of delivery. Examples include click-through URLs, the height and width of the creative, the country-code of the user seeing the ad, etc. See: Macros. * Custom Macros, which must be replaced at the time the Creative is associated with the template. The only interaction Buzz has with System Macros is to validate that any included in a Template are valid. A list of valid System Macros is kept in the macros table of the MySQL database. System macros are always in the form `MACRO_NAME` with no additional parameters. Custom Macros, as described above, are created per template and are in the form: [block:code] { "codes": [ { "code": " {{CUSTOM:<NAME>:<TYPE>}}", "language": "text" } ] } [/block] Valid types are as follows: [block:parameters] { "data": { "0-0": "`INT`", "0-1": "Must be a positive integer", "1-0": "`STRING`", "1-1": "String, may be blank if passed as \"\"", "2-0": "`NUMBER`", "2-1": "Any number", "3-0": "`URL`", "3-1": "Valid URL", "4-0": "`FILE`", "4-1": "Valid URL. This is a different type to hint both the user and a UI as to what is expected.", "h-0": "Custom Macro Type", "h-1": "Description" }, "cols": 2, "rows": 5 } [/block] [block:api-header] { "type": "basic", "title": "About Creative Asset Filenames and Paths" } [/block] When Creative Assets are uploaded to Buzz, they are placed onto a CDN in a specific naming format as follows: [block:code] { "codes": [ { "code": "http://[CDN path]/[account_id]/[advertiser_id]/[creative_asset_id]_[original_name].[ext]", "language": "text", "name": " " } ] } [/block] So if you upload test.gif to advertiser 123 and account 345 on S3, your URL might look like this: [block:code] { "codes": [ { "code": "http://buzz-creative-assets/345/123/upload.gif", "language": "text", "name": " " } ] } [/block] If Buzz can create a thumbnail it will be here: [block:code] { "codes": [ { "code": "http://buzz-creative-assets/345/123/thumb/upload_thumb.gif", "language": "text", "name": " " } ] } [/block] For original videos, the location is: [block:code] { "codes": [ { "code": "http://buzz-creative-assets/345/123/video/movie.mp4", "language": "text", "name": " " } ] } [/block] And the encoded versions might be: [block:code] { "codes": [ { "code": "http://buzz-creative-assets/345/123/encoded/movie_iphone.mp4\nhttp://buzz-creative-assets/345/123/encoded/movie_flash.flv", "language": "text", "name": " " } ] } [/block] [block:api-header] { "type": "basic", "title": "Macro Blocks" } [/block] Buzz supports the concept of repeating Macro Blocks. There are certain use-cases, such as within VAST XML documents, when you wish to allow a number of repeating blocks of content depending on which data is provided by the end user. Suppose we want a portion of our template to look something like this, with any number of url blocks: [block:code] { "codes": [ { "code": "<urls>\n<url>\n<click>\"http://path_to_url+/\"</click>\n<name>name of click</name></url>\n<url>\n<click>\"http://path_to_url+/\"</click>\n<name>name of click</name></url>\n<url>\n<click>\"http://path_to_url+/\"</click>\n<name>name of click</name></url>\n</urls>", "language": "xml" } ] } [/block] To do this in a Creative Template you use a Macro Block with Custom Macros within the block. The syntax of a Macro Block is: [block:code] { "codes": [ { "code": "{{#NAME:<min>:<max> ...content and other macros … /}}", "language": "text" } ] } [/block] Where min is the minimum number of blocks required, and max is the maximum. If the block may be omitted min should be set to zero. If there is no maximum, the max field may be omitted. So our template above might look like this: [block:code] { "codes": [ { "code": "<urls>\n{{#URL:1:5<url>\n<click>{{CUSTOM:URL_CLICK:URL}}</click>\n<name>{{CUSTOM:URL_NAME:STRING}}</name></url>/}}\n</urls>", "language": "xml" } ] } [/block] And when we use the API to create a Creative we would put the corresponding data into an array like this: [block:code] { "codes": [ { "code": "{\"creative_fields\":\n{\"URL\":[\n{\"URL_CLICK:\"http://path/to/click\",\"URL_NAME\":\"name goes here\"},\n{\"URL_CLICK:\"http://path/to/click\",\"URL_NAME\":\"name goes here\"},\n{\"URL_CLICK:\"http://path/to/click\",\"URL_NAME\":\"name goes here\"}\n]}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "Creative AddOns" } [/block] A [Creative AddOn](doc:creative-addons) is a pixel or script that needs to be added to the Creative when it is displayed to the user. AddOns allow you to define a given URL once, then use it with many Creatives across Campaigns and Line Items. [block:api-header] { "title": "Generating Creative Previews" } [/block] The Buzz API supports the generation and serving of realistic previews of Creatives with temporary values replacing any [Macros](doc:macros) within the markup. The process for generating a creative preview is as follows: 1. Create the [Creative](doc:creatives) and make it active. This can be done using the API or the UI. 2. Make a [GET](doc:creative-2) request to the creative endpoint. If the Creative is ready for preview, the `preview_token` field will be non-null in the response. If the `preview_token` field is null, it generally means that the creative is not active or that the creative assets are not yet ready, for example if transcoding is not yet complete. 3. Make a GET call to the following URL with `[host]` replaced with the path for your Buzz API instance and `[preview_token]` replaced with the value from above: `https://[host]/buzz/public/CreativePreview.php?token=[preview_token]` **Video Preview:** If you are previewing a VAST video creative, the preview will return the XML of the document. In order to see a video player and observe video events being fired add the parameter `&template=video_preview` to the URL. **Macros Values:** When previewing the creative macros are filled with temporary values not reflective of the values that will be replaced during actual serving. For example, all numeric values are replaced with the string `12345`.