{"_id":"56cb88a4245b841300806f8b","githubsync":"","project":"56c35c56c0c4630d004e864c","user":"56c39c05bc41330d009f25d7","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"},"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"},"__v":7,"parentDoc":null,"updates":["5914fb43adef8c0f00798443","5914fc1e27c5b92d0004f884"],"next":{"pages":[],"description":""},"createdAt":"2016-02-22T22:16:04.303Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":8,"body":"Whenever a Creative is created or edited it may be subject to an approval or submission process by one or more “Vendors”. Examples of Vendors:\n* Both Google and AppNexus require all creatives to be submitted for a quality approval in advance of serving\n* Beeswax will use a proactive malware scanning system to assure Creatives do not contain harmful code\n* Measurement vendors like Nielsen and Comscore need Creatives registered with them in order to be tracked.\n\nThis document describes how the approval process works and how to use the API to check the status of an approval.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"When is a Creative Approval Triggered?\"\n}\n[/block]\nA Creative approval process is triggered when any of the following occur:\n* A Creative is first created with all the assets needed to make it eligible to serve. For example, if a Creative is waiting on transcoded video it will not yet be eligible to serve.\n* A Creative’s `creative_content` is changed in any way or the click-through URL is changed. Fields unrelated to the content, such as `notes` or the name of the Creative will not trigger a re-approval.\n* A Creative is deleted\n* An active Creative is made inactive, or an inactive one is made active\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Approval Process Overview\"\n}\n[/block]\nA list of all Creative Approval Vendors is available in the `creative_approval_vendors` table, accessible using a GET:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"http:/[path]/rest/view\\\" -b cookies.txt -d '{\\\"view_name\\\":\\\"creative_approval_vendors\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nThe set of vendors that will be queued up for any given approval depends on the `creative_type` of the creative, whether the vendor is marked as `required`, and whether additional, optional, vendors were requested by the user:\n\n* If a vendor is marked as required, and the `creative_type` matches the creative (or is set to -1) it will be set for approval.\n\nVendors that are not required, such as a measurement vendor, can be requested by adding the vendor declaration to the creative attributes of the Creative, as follows:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\\"approval\\\":\\n {\\\"vendor_id\\\":\\n  [1,2]\\n }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\nA new Creative Approval Queue object is created for each eligible vendor for each Creative, and the status is set to zero (`NOT_SUBMITTED`). A list of available statuses can be found in the creative_status view:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"http:/[path]/rest/view\\\" -b cookies.txt -d '{\\\"view_name\\\":\\\"creative_status\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nA list of the current queue of approvals for a Creative may be found as follows:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"http:/[path]/rest/creative_approval_queue\\\" -b cookies.txt -d '{\\\"creative_id\\\":<ID>} \",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nA queue entry can have an Action, which reflects what to send to the vendor. Eligible actions include:\n* CREATE: Sent when a Creative is first created or when the content changes\n* PAUSE: Sent when a Creative was previously approved, but has now been set to inactive\n* RESUME: Sent when a Creative was previously paused, but has now been set to active\n* DELETE: When a Creative is deleted\n\nThese actions are needed because Malware vendors, for example, continuously scan creatives until we tell them to stop, and charge us per scan. For other vendors, like Google, the only action needed is CREATE. \n\nBuzz de-duplicates requests in the case where the user takes multiple actions on a Creative before an approval is sent to a Vendor. For example, if the user activates and deactivates a Creative multiple times only a single \"PAUSE\" or \"RESUME\" will be sent.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"How is the Creative Approval Queue Processed?\"\n}\n[/block]\nA periodic process runs to submit any CreativeApprovalQueue objects with a status of `NOT_SUBMITTED` to their respective approval vendor APIs. As a result of this process, the status of the CreativeApprovalQueue entries are set to either PENDING or ERROR.\n\nThe API call for processing creatives is a PUT:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X PUT \\\"http://[path]/rest/creative_approval_queue\\\" -b cookies.txt -d '{\\\"creative_id\\\":123}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nThe selection fields within the GET can limit the creatives submitted include account_id, creative_id, creative_approval_id, and request_status, other fields are ignored. Only Super Users can process the queue, so there is no way for an API user to \"push\" something to be approved faster.\n\nAnother periodic process checks the status of previously submitted Creatives by using the request_status:1. If the vendor has completed their process and provides a helpful response, the PUT then updates the CreativeApprovalQueue entries to a status of APPROVED or REJECTED and any text messages relating to the process are stored in the approval_message field of the creative_approval_queue_history object.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Creative Approval and Inventory Sources\"\n}\n[/block]\nCertain inventory sources, such as Google and Appnexus, will not allow Creative to run until they have been proactively approved. As a result, Buzz stores the approval status of the Creative against various inventory sources in the Creative's `creative_attributes` field, and the Stinger bidder will not serve these ads unless and until they have been marked as \"approved\".\n\nVendors marked as `required` that also have a set `inventory_source` field, will automatically be listed as `pending` in the creative attributes whenever a Creative is created or edited. For example, if inventory_sources 1 and 2 are both required, when a Creative is first created it will have an entry in the creative_attributes as follows:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\\"approval\\\":{\\\"inventory_source\\\":{\\\"pending\\\":[1,2]}}}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nWhen a CreativeApprovalQueue is marked as `APPROVED` or `REJECTED`, if the vendor for which the queue entry belongs has an associated `inventory_source`, then the approval vendor attribute for that source is updated with the following syntax:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\\"approval\\\":{\\\"inventory_source\\\":{\\\"approved\\\":[<inventory_source_id>],\\\"rejected\\\":[<inventory_source_id>]}}}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nWhen a Creative that has previously been approved for a given inventory source is changed, the status in the creative attribute changes back to `PENDING`.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Creative Approval and Serving\"\n}\n[/block]\nThe Creative object includes a field `creative_status` which is read-only for users. The `creative_status` field is interpreted by the bidder as “eligible to serve” where 0=not eligible, and 1=eligible. This over-rides the active flag such that a Creative with active=1 and creative_status=0 will not serve.\n\nBy default, Buzz sets the `creative_status` to 1 for all Creatives.\n\nIf the vendor for which the queue entry belongs was marked as `blocking`, then a rejection for this source will switch the creative_status to 2. This would be appropriate, for example, for a malware scan that fails. For the time being, there will be no way to set the `creative_status` back to 1 without administrative help, thus rendering the creative unable to serve.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Creative Approval Queue History\"\n}\n[/block]\nThe CreativeApprovalQueue object contains the currently active approval request and/or response. If a user changes a Creative multiple times it can be helpful to see the history of approval requests. A second object, the [creative_approval_queue_history](doc:creativeapprovalqueuehistory), contains this data and is read-only. To GET the history of a single creative:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"http:/[path]/rest/creative_approval_queue_history\\\" -b cookies.txt -d '{\\\"creative_id\\\":<ID>}\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"creative-approvals","type":"basic","title":"Creative Approvals"}

Creative Approvals


Whenever a Creative is created or edited it may be subject to an approval or submission process by one or more “Vendors”. Examples of Vendors: * Both Google and AppNexus require all creatives to be submitted for a quality approval in advance of serving * Beeswax will use a proactive malware scanning system to assure Creatives do not contain harmful code * Measurement vendors like Nielsen and Comscore need Creatives registered with them in order to be tracked. This document describes how the approval process works and how to use the API to check the status of an approval. [block:api-header] { "type": "basic", "title": "When is a Creative Approval Triggered?" } [/block] A Creative approval process is triggered when any of the following occur: * A Creative is first created with all the assets needed to make it eligible to serve. For example, if a Creative is waiting on transcoded video it will not yet be eligible to serve. * A Creative’s `creative_content` is changed in any way or the click-through URL is changed. Fields unrelated to the content, such as `notes` or the name of the Creative will not trigger a re-approval. * A Creative is deleted * An active Creative is made inactive, or an inactive one is made active [block:api-header] { "type": "basic", "title": "Approval Process Overview" } [/block] A list of all Creative Approval Vendors is available in the `creative_approval_vendors` table, accessible using a GET: [block:code] { "codes": [ { "code": "curl -X GET \"http:/[path]/rest/view\" -b cookies.txt -d '{\"view_name\":\"creative_approval_vendors\"}'", "language": "curl" } ] } [/block] The set of vendors that will be queued up for any given approval depends on the `creative_type` of the creative, whether the vendor is marked as `required`, and whether additional, optional, vendors were requested by the user: * If a vendor is marked as required, and the `creative_type` matches the creative (or is set to -1) it will be set for approval. Vendors that are not required, such as a measurement vendor, can be requested by adding the vendor declaration to the creative attributes of the Creative, as follows: [block:code] { "codes": [ { "code": "{\"approval\":\n {\"vendor_id\":\n [1,2]\n }\n}", "language": "json" } ] } [/block] A new Creative Approval Queue object is created for each eligible vendor for each Creative, and the status is set to zero (`NOT_SUBMITTED`). A list of available statuses can be found in the creative_status view: [block:code] { "codes": [ { "code": "curl -X GET \"http:/[path]/rest/view\" -b cookies.txt -d '{\"view_name\":\"creative_status\"}'", "language": "curl" } ] } [/block] A list of the current queue of approvals for a Creative may be found as follows: [block:code] { "codes": [ { "code": "curl -X GET \"http:/[path]/rest/creative_approval_queue\" -b cookies.txt -d '{\"creative_id\":<ID>} ", "language": "curl" } ] } [/block] A queue entry can have an Action, which reflects what to send to the vendor. Eligible actions include: * CREATE: Sent when a Creative is first created or when the content changes * PAUSE: Sent when a Creative was previously approved, but has now been set to inactive * RESUME: Sent when a Creative was previously paused, but has now been set to active * DELETE: When a Creative is deleted These actions are needed because Malware vendors, for example, continuously scan creatives until we tell them to stop, and charge us per scan. For other vendors, like Google, the only action needed is CREATE. Buzz de-duplicates requests in the case where the user takes multiple actions on a Creative before an approval is sent to a Vendor. For example, if the user activates and deactivates a Creative multiple times only a single "PAUSE" or "RESUME" will be sent. [block:api-header] { "type": "basic", "title": "How is the Creative Approval Queue Processed?" } [/block] A periodic process runs to submit any CreativeApprovalQueue objects with a status of `NOT_SUBMITTED` to their respective approval vendor APIs. As a result of this process, the status of the CreativeApprovalQueue entries are set to either PENDING or ERROR. The API call for processing creatives is a PUT: [block:code] { "codes": [ { "code": "curl -X PUT \"http://[path]/rest/creative_approval_queue\" -b cookies.txt -d '{\"creative_id\":123}'", "language": "curl" } ] } [/block] The selection fields within the GET can limit the creatives submitted include account_id, creative_id, creative_approval_id, and request_status, other fields are ignored. Only Super Users can process the queue, so there is no way for an API user to "push" something to be approved faster. Another periodic process checks the status of previously submitted Creatives by using the request_status:1. If the vendor has completed their process and provides a helpful response, the PUT then updates the CreativeApprovalQueue entries to a status of APPROVED or REJECTED and any text messages relating to the process are stored in the approval_message field of the creative_approval_queue_history object. [block:api-header] { "type": "basic", "title": "Creative Approval and Inventory Sources" } [/block] Certain inventory sources, such as Google and Appnexus, will not allow Creative to run until they have been proactively approved. As a result, Buzz stores the approval status of the Creative against various inventory sources in the Creative's `creative_attributes` field, and the Stinger bidder will not serve these ads unless and until they have been marked as "approved". Vendors marked as `required` that also have a set `inventory_source` field, will automatically be listed as `pending` in the creative attributes whenever a Creative is created or edited. For example, if inventory_sources 1 and 2 are both required, when a Creative is first created it will have an entry in the creative_attributes as follows: [block:code] { "codes": [ { "code": "{\"approval\":{\"inventory_source\":{\"pending\":[1,2]}}}", "language": "json" } ] } [/block] When a CreativeApprovalQueue is marked as `APPROVED` or `REJECTED`, if the vendor for which the queue entry belongs has an associated `inventory_source`, then the approval vendor attribute for that source is updated with the following syntax: [block:code] { "codes": [ { "code": "{\"approval\":{\"inventory_source\":{\"approved\":[<inventory_source_id>],\"rejected\":[<inventory_source_id>]}}}", "language": "json" } ] } [/block] When a Creative that has previously been approved for a given inventory source is changed, the status in the creative attribute changes back to `PENDING`. [block:api-header] { "type": "basic", "title": "Creative Approval and Serving" } [/block] The Creative object includes a field `creative_status` which is read-only for users. The `creative_status` field is interpreted by the bidder as “eligible to serve” where 0=not eligible, and 1=eligible. This over-rides the active flag such that a Creative with active=1 and creative_status=0 will not serve. By default, Buzz sets the `creative_status` to 1 for all Creatives. If the vendor for which the queue entry belongs was marked as `blocking`, then a rejection for this source will switch the creative_status to 2. This would be appropriate, for example, for a malware scan that fails. For the time being, there will be no way to set the `creative_status` back to 1 without administrative help, thus rendering the creative unable to serve. [block:api-header] { "type": "basic", "title": "Creative Approval Queue History" } [/block] The CreativeApprovalQueue object contains the currently active approval request and/or response. If a user changes a Creative multiple times it can be helpful to see the history of approval requests. A second object, the [creative_approval_queue_history](doc:creativeapprovalqueuehistory), contains this data and is read-only. To GET the history of a single creative: [block:code] { "codes": [ { "code": "curl -X GET \"http:/[path]/rest/creative_approval_queue_history\" -b cookies.txt -d '{\"creative_id\":<ID>}", "language": "curl" } ] } [/block]