VAST Renderer

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}{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
const AD_UNIT_CODE = 'renderer_demo'; // The ad unit code in your Blue Billywig publication

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:

An object containing the following properties:

code: an alphanumeric code identifying this play session for analytics. (string, required)
vastUrl: a VAST TAG url. (string)
vastXml: a full VAST XML. (string)

One of vastUrl or vastXml is required.

targetElementHTMLElementWhen 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.

playoutOverridesObjectA 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.


2.0 | Setting up

To set up and try the renderer:

  1. Create an in-article ad unit in your OVP (you can leave all of the default values in place);
  2. Note the code value of your ad unit.
  3. Note the label of your publication, this is the first part of the domain name in your embeds (for example, “yourcompanyname” for

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:

Was this article helpful?

Related Articles

Contact Support
Can't find the answer you're looking for?
Contact Support