Brightcove Interactivity Addon API

Brightcove Interactivity Addon API reference.

Introduction

Brightcove Interactivity Addons are invoked from annotations within the video frame to manipulate on-page elements and data outside of the video frame.

For example, a video can contain a call-to-action that says "Click here to load the diagram." When clicked, the call-to-action can invoke a Brightcove Interactivity Addon that will load the diagram onto the page, outside of the video frame.

Another example, a video can contain an OnTime annotation that will invoke a Brightcove Interactivity Addon to load a Twitter Feed widget onto the page, outside of the video frame, when the video reaches 30 seconds in the video.

Addon: Basic use

The Brightcove Interactivity Addon API is used by developers to write custom javascript that will live on your webpages. The developer of the Addon will define the behavior, design, look and feel.

hapyak.addon(name, {
init: function () {
}
});

Arguments

The hapyak.addon call accepts two mandatory arguments - name and actions. They are described as follows:

name

string - mandatory

The namespace for all events triggered on the addon.

actions

JSON - mandatory

Each property and its value should adhere to the following:

  • key - string

    The name of the event to be triggered.

  • value - function

    The callback function to be called when the event is triggered. The function accepts a single argument which contains the related JSON data.

The return value for a hapyak.addon call will be a reference to the created instance.

Events

The context for all events (both user-created and otherwise) will have a context where this will be a reference to the addon instance.

init

The init event is automatically triggered once the addon has been setup within Brightcove Interactivity. Setting up a handler for this event is optional.

Methods

These methods are attached to the instance returned by the hapyak.addon call

destroy()

Cleans up all event listeners setup for the addon instance. The actions property on the instance is also cleared out. destroy accepts no arguments.

Message

The Brightcove Interactivity Message API is used internally by the Brightcove Interactivity Addon API and enables communication to and from Brightcove Interactivity components. In addition to invoking Brightcove Interactivity Addons this API may be used to pass messages to and from custom annotations built with the Extension API.

hapyak.message.addEventListener(name, callback, context);

hapyak.message.removeEventListener(name, callback);

hapyak.message.send(frame, event, data);

hapyak.message provides a way for users to setup and manage handlers to communicate with addons. This communication can be done on the same page or with an iframe on the parent page.


Methods

addEventListener(name, callback, context)

Register a handler to be called when an event of the specified name is triggered.

function myFunc(data) {
console.log('test fired', data);
}

hapyak.message.addEventListener('test', myFunc, 'hapyak');

name - string - mandatory

The name of the event to be triggered

callback - function - mandatory

A callback function to be run after the event has fired

context - string - optional

Can be used to provide an additional level of specification for the event. Any message that is triggered must contain a context that matches the handlers (if one exists).

removeEventListener(name, callback)

Remove a registered event handler with a specified name and function reference

hapyak.message.removeEventListener('test', myFunc);

name - string - mandatory

The name of the event to be removed

callback - function - mandatory

A reference to the callback function used

send(frame, event, data)

Allows a user to trigger an event handler for a given event on either the current page or an iframe.

hapyak.message.send(window, 'test', {
'foo': 'bar'
});

frame - window object - mandatory

A reference to either the current window or a reference to an iframes contentWindow

event - string - mandatory

The name of the event to fire

data - JSON - optional

An optional JSON blob to pass data with

Example

Addon

The following example shows how we can communicate with an iframe from the main parent page using our addon to register event handlers.

Parent page code

document.addEventListener("DOMContentLoaded", function () {
var span = document.getElementById("span");

// Setup an addon to listen for events from the iframe annotation
hapyak.addon("color-change-listener", {
init: function () {
console.log("This is a message from init. Perform any setup needed here.");
},
"notify-color": function (e) {
span.innerHTML = "Iframe background is " + e.data.color;
}
});

document.getElementById("button").addEventListener("click", function () {
// Broadcast a message to all iframes on the page
Array.prototype.forEach.call(document.querySelectorAll("iframe"), function (iframe) {
// Send a message to the iframe annotation telling it to change its color to red
hapyak.message.send(iframe.contentWindow, "change-color", {
  "color": "red"
});
span.innerHTML = "Iframe background is red";
});
}, false);
}, false);

Iframe code

(function () {
document.addEventListener('click', function () {
document.body.style.backgroundColor = 'blue';
// We need to pass a custom context so only addons we with the name `color-change-listener` act on the event
hapyak.message.send(window.parent, 'notify-color', {
    customerContext: 'color-change-listener',
    color: 'blue'
});
}, false);
hapyak.message.addEventListener('change-color', function (e) {
document.body.style.backgroundColor = e.data.color;
});
}());

Example

Message

This example is the same as Addon above, except that we're registering all of the message handlers ourself using hapyak.message methods.

Parent page code

document.addEventListener("DOMContentLoaded", function () {
var span = document.getElementById("span");

// Add an event listener for the notify-color event from our iframe annotation
hapyak.message.addEventListener("notify-color", function (e) {
span.innerHTML = "Iframe background is " + e.data.color;
})

document.getElementById("button").addEventListener("click", function () {
// Broadcast a message to all iframes on the page
Array.prototype.forEach.call(document.querySelectorAll("iframe"), function (iframe) {
// Send a message to the iframe annotation telling it to change its color to red
hapyak.message.send(iframe.contentWindow, "change-color", {
  "color": "red"
});
span.innerHTML = "Iframe background is red";
});
}, false);
}, false);

Iframe code

(function () {
document.addEventListener('click', function () {
document.body.style.backgroundColor = 'blue';
hapyak.message.send(window.parent, 'notify-color', {
    color: 'blue'
});
}, false);
hapyak.message.addEventListener('change-color', function (e) {
document.body.style.backgroundColor = e.data.color;
});
}());

Example