Product Updates | Contact Support | System Status
Page Contents

    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


    Page last updated on 03 Aug 2022