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;
});
}());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;
});
}());