Brightcove Interactivity Addon API

はじめに

Brightcove Interactivity Addon は、動画フレーム内のアノテーションから呼び出され、動画フレーム外のページ要素やデータを操作します。

たとえば、動画内に「ここをクリックして図を読み込む」というコールトゥアクションが表示される場合があります。クリックされると、このコールトゥアクションは Brightcove Interactivity Addon を呼び出し、動画フレームの外に図をページ上に読み込ませることができます。

別の例としては、動画に OnTime アノテーション(注釈)が含まれており、動画が30秒に達したときに Brightcove Interactivity Addon が呼び出されて、X (旧Twitter) フィード ウィジェットをページ上（動画フレーム外）に読み込ませることができます。

Addon: 基本的な使用法

Brightcove Interactivity Addon API は、開発者が独自の JavaScript を記述してウェブページ上で動作させるために使用されます。アドオンの開発者が、その動作、デザイン、ルック＆フィールを定義します。

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

引数

hapyak.addon の呼び出しには、name と actions の2つの必須引数が必要です。それぞれの説明は以下の通りです:

name

文字列（string） - 必須

Addon でトリガーされるすべてのイベントに対する名前空間です。

actions

JSON - 必須

各プロパティとその値は以下のルールに従う必要があります：

• キー（key） - 文字列（string）

  トリガーされるイベントの名前です。

• 値（value） - 関数（function）

  イベントがトリガーされたときに呼び出されるコールバック関数です。この関数は1つの引数を取り、それには関連する JSON データが含まれます。

hapyak.addon の呼び出しの戻り値は、作成されたインスタンスへの参照になります。

イベント

すべてのイベント（ユーザー定義のものも含む）のコンテキストでは、this はアドオンインスタンスへの参照となります。

init

init イベントは、Brightcove Interactivity 内で Addon がセットアップされた時点で自動的にトリガーされます。このイベントに対するハンドラーの設定は任意です。

メソッド

以下のメソッドは、hapyak.addon 呼び出しで返されるインスタンスに紐付けられています。

destroy()

Addon インスタンスに設定されたすべてのイベントリスナーをクリーンアップします。インスタンス上の actions プロパティもクリアされます。destroy は引数を取りません。

Message (メッセージ)

Brightcove Interactivity Message API は、Brightcove Interactivity Addon API 内部で使用されており、Brightcove Interactivity コンポーネントとの双方向の通信を可能にします。この API は、Brightcove Interactivity Addon の呼び出しに加えて、Extension API を使って作成されたカスタムアノテーションとの間でメッセージを送受信するためにも使用できます。

hapyak.message.addEventListener(name, callback, context);
                
                hapyak.message.removeEventListener(name, callback);
                
                hapyak.message.send(frame, event, data);

hapyak.message は、ユーザーが Addon との通信を行うためのハンドラーを設定・管理する手段を提供します。この通信は同一ページ上でも、親ページ内の iframe を通じても実行できます。

メソッド

addEventListener(name, callback, context)

指定された name のイベントがトリガーされたときに呼び出されるハンドラーを登録します。

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

name - 文字列（string） - 必須

トリガーされるイベントの名前です。

callback - 関数（function） - 必須

イベント発火後に実行されるコールバック関数です。

context - 文字列（string） - 任意

イベントに対して追加の指定を行うために使用できます。トリガーされるメッセージには、ハンドラーと一致するコンテキストが含まれている必要があります（存在する場合）。

removeEventListener(name, callback)

指定された名前と関数参照に基づいて、登録されたイベントハンドラーを削除します。

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

name - 文字列（string） - 必須

削除するイベントの名前です。

callback - 関数（function） - 必須

使用されたコールバック関数の参照です。

send(frame, event, data)

指定された event に対して、現在のページまたは iframe 上でイベントハンドラーをトリガーします。

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

frame - ウィンドウオブジェクト（window object） - 必須

現在のウィンドウ、または iframe の contentWindow への参照です。

event - 文字列（string） - 必須

発火させるイベントの名前です。

data - JSON - 任意

データを一緒に渡すための任意の JSON データです。

例

Addon

次の例では、アドオンを使用してイベントハンドラーを登録し、親ページから iframe との通信を行う方法を示しています。

親ページのコード

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 コード

(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

この例は上記の Addon の例と同じですが、hapyak.message のメソッドを使用して、すべてのメッセージハンドラーを自分で登録している点が異なります。

親ページのコード

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 コード

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

例