Command Queue

When using the player API, detecting when the player is ready to be used can be challenging. Use the command queue to submit functions that the player will call once it is ready.

1.0 | Single player on the page

Using the command queue is straightforward when your page contains only a single player. Ensure the required global variables are set, then add functions to the queue for the player to call.

The first argument to the callback function is always a reference to the player API.

// Ensure the following globals are available
window.bluebillywig = window.bluebillywig || {};
window.bluebillywig.cmd = window.bluebillywig.cmd || [];

window.bluebillywig.cmd.push(function($$api) {
    $$api.on('volumechange', function() {
        console.log('The volume changed!');
    });
});

2.0 | Multiple players on the page

A page containing multiple players requires a different approach. It is necessary to specify which player should consume each request in the queue. When omitted, the request is consumed by the first player and ignored by all others on the page.

To specify the target player, either a playerId or playerAlias must be supplied alongside the callback function.

// Ensure the following globals are available
window.bluebillywig = window.bluebillywig || {};
window.bluebillywig.cmd = window.bluebillywig.cmd || [];

// This request will be consumed by the player embedded with playout "default" and mediaclip 123456
window.bluebillywig.cmd.push({
    playerId: '/p/default/c/123456',
    callback: function($$api) {
        $$api.setMuted(true);
    }
});

// This request will be consumed by the player embedded with playout "someotherplayout" and mediaclip 56789
window.bluebillywig.cmd.push({
    playerId: '/p/someotherplayout/c/56789',
    callback: function($$api) {
        $$api.setMuted(false);
    }
});

window.bluebillywig.cmd.push({
    playerAlias: 'my-unique-player-alias',
    callback: function($$api) {
        $$api.setMuted(false);
    }
});

The playerId always follows this structure:

/p/{PLAYOUT_CODE}/{CONTENT_TYPE_INDICATOR}/{CONTENT_ID}

Where:

• {PLAYOUT_CODE} is the URL-safe code of the playout used to place the player.
• {CONTENT_TYPE_INDICATOR} is a single character indicating the type of embed:
  • c for mediaclips
  • l for playlists
  • p for projects
  • a for outstream ad units
  • q for query embeds
• {CONTENT_ID} is the object ID of the content being embedded (for mediaclips, playlists, and projects), the code of the ad unit (for ad units), or the query string (for query embeds).

The playerAlias can be set by supplying a string value to the alias key at the root of the object used to initialise the player, and will always match the code value provided to a VAST Renderer during bootstrap.