The VAST Renderer is a lightweight wrapper around the Blue Billywig player. The VAST renderer makes it possible to play back any standard VAST tag by providing a tag URL or the full XML.
By configuring a standard outstream ad unit in the OVP, you can use the VAST renderer embed code and API to play your VAST tags instead of having the player request the attached line items.
In the remainder of this article we’ll use “renderer’ to refer to the VAST Renderer.
1.0 | VAST Renderer API
The renderer offers a minimal API to place the player with the desired VAST tag.
First, the renderer has to be loaded by placing its embed code on the page. This embed code URL is nearly identical to an outstream player’s embed code, with the /a/ replaced by /r/.
The URL’s structure is https://{PUBLICATION}.bbvms.com/r/{AD_UNIT_CODE}.js where
- {PUBLICATION} refers to your publication’s label.
- {AD_UNIT_CODE} is the URL-safe code of the ad unit with your renderer configuration.
Once this script is loaded, the renderer API can be used. Your instance of the renderer API can be found in the window.bluebillywig.renderers array. If multiple renderer scripts are loaded, the array will contain multiple renderer instances.
A specific renderer instance can be identified by its _id property, which is set to {PUBLICATION}-{AD_UNIT_CODE}.
const PUBLICATION = 'bbsupport'; // Your publication label on Blue Billywig (the subdomain of bbvms.com)
const AD_UNIT_CODE = 'renderer_demo'; // The ad unit code in your Blue Billywig publication
const RENDERER_ID = `${PUBLICATION}-${AD_UNIT_CODE}`;
const renderer = window.bluebillywig.renderers.find((renderer) => renderer._id === RENDERER_ID);
The renderer contains a single method: bootstrap, which can be used to place the player on the page with the desired VAST tag. It takes the following arguments, in order:
| Argument | Type | Description | Required? |
| config | Object | An object containing the following properties: – code: an alphanumeric code identifying this play session for analytics. (string, required) One of vastUrl or vastXml is required. | Yes |
| targetElement | HTMLElement | When provided, the player will place itself inside of the given HTMLElement. When left undefined, the player follows the placement options defined in the ad unit. Although not required, we recommend supplying this property to prevent situations where the placement of the player fails because of missing matching elements, or where the player is placed in undesirable positions. | No |
| playoutOverrides | Object | A set of key-values to use as overrides for the playoutData of the renderer configuration. This enables overriding the player configuration programatically for each render. This feature is only rarely required. If you think you need this for your customization needs, please contact support for further assistance. | No |
2.0 | Setting up
To set up and try the renderer:
- Create an in-article ad unit in your OVP (you can leave all of the default values in place);
- Note the code value of your ad unit.
- Note the label of your publication, this is the first part of the domain name in your embeds (for example, “yourcompanyname” for yourcompanyname.bbvms.com)
The renderer’s embed code is almost identical to the ad unit’s regular embed code, but the “/a/” is replaced with “/r/”.
The easiest way to use the renderer is to programatically place the renderer script on your page using JavaScript. Please see the below code example. To use your own configuration, substitute the values of AD_UNIT_CODE and PUBLICATION with the values noted down in step 2 and 3.
3.0 | Controlling the player
Instantiating the renderer is an asynchronous process. Additionally, the renderer API does not offer a direct interface to the underlying player’s API. Therefore it’s best to use the player’s command queue feature to interact with the player’s API for things like attaching event handlers.
Learn more about the Command Queue or use the code example below: