The VAST Renderer is a lightweight wrapper around the Blue Billywig player. It 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 places 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:
One of | Yes |
| targetElement | HTMLElement | When provided, the player will place itself inside the given HTMLElement. When left undefined, the player follows the placement options defined in the ad unit.Although not required, we recommend supplying this argument to prevent situations where the placement fails because of missing matching elements, or where the player is placed in an undesirable position. | No |
| playoutOverrides | Object | A set of key-value pairs to use as overrides for the playoutData of the renderer configuration. This allows overriding the player configuration programmatically for each render.This feature is rarely required. If you think you need it for your customisation 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 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,
yourcompanynameforyourcompanyname.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 place the renderer script on your page programmatically using JavaScript. See the code example below. Substitute the values of AD_UNIT_CODE and PUBLICATION with the values noted in steps 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, the best approach is to use the player’s command queue feature to attach event handlers and interact with the player API.
Learn more about the Command Queue, or use the code example below.