アノテーションクライアント CRUD API

Brightcove Interactivity Editor API オブジェクトには、アノテーションの作成、読み取り、更新、削除を行うためのメソッドが用意されています。

セットアップ

まず、hapyak エディターオブジェクトを作成します。アノテーション(注釈)は読み込まれるまでアクセスできないため、loadannotations イベントが発火するのを待つのがベストです。

let editor = hapyak.editor({
  //fill in apiKey, video, track, etc
  onLoadAnnotations: function () {
      /*
      use CRUD methods here
      editor.annotations.get(...)
      editor.annotations.all(...)
      editor.annotations.create(...)
      editor.annotations.update(...)
      editor.annotations.remove(...)
      */
  }
});

CRUD メソッドの呼び出し

すべての CRU Dメソッドは非同期で実行され、最後の引数としてオプションのコールバック関数を受け取ることができます。このコールバック関数は、操作が成功して保存が完了した場合、または失敗した場合に実行されます。コールバック関数には2つの引数が渡されます:

操作が成功した場合はその結果、失敗した場合は null。
エラーが発生した場合はエラーメッセージ、成功した場合は null。

アノテーションの種類

APIは types メソッドを使用して利用可能なアノテーションの種類の一覧を提供します。このメソッドはコールバック関数以外のパラメータは取りません。コールバック関数には、各アノテーションタイプに関する情報を表すオブジェクトのハッシュが渡されます。提供されるフィールドは以下の通りです：

id - 種類を識別するための文字列
title - アノテーションの種類のタイトル
enabled - この種類の新しいアノテーションを作成できるかどうかを示す真偽値
icon - この種類を表すアイコンを描画するために使用できる文字列
defaults - デフォルトのプロパティを格納したハッシュ

editor.annotations.types(function (types, errr) {
  if (err) {
      console.log('Error retrieving annotation types: ' + err);
      return;
  }

  console.log('Annotation types', annotation);
});

単一アノテーションの取得

個別のアノテーションは、数値のIDを使用して get メソッドで取得することができます。

editor.annotations.get(1234, function (annotation, err) {
  if (err) {
      console.log('Error retrieving annotation: ' + err);
      return;
  }

  ///annotations is an array
  console.log('Loaded annotation', annotation);
});

取得されたオブジェクトには以下のフィールドが含まれます：

annotationId - このアノテーションの恒久的な一意なID
trackId - このアノテーションが関連付けられているトラックのID
type - アノテーションの種類を表す文字列（例："pop"、"hotlink"、"image"、"quiz" など）
created - アノテーションが作成された時刻の数値形式のUNIXタイムスタンプ（1970年1月1日UTC午前0時からの秒数）
modified - 最後にアノテーションが変更された時刻（こちらも数値形式のタイムスタンプ）
writable - このアノテーションが変更可能かどうかを示す真偽値
properties - このアノテーションに固有のプラグイン設定。start 時間などが含まれます

取得されたアノテーションオブジェクトのサンプル：

{
  "annotationId": 19702,
  "trackId": 1630,
  "type": "pop",
  "created": 1389302540413,
  "modified": 1389302540426,
  "writable": true,
  "properties": {
      "text": "Hello World",
      "_duration": 5,
      "start": 0,
      "mode": "pop",
      "top": "80%",
      "left": "5%"
  },
  "customConfig": {
      "Lorem": "Ipsum"
  }
}

アノテーションの一覧取得

all メソッドは、現在読み込まれているすべてのアノテーションを、開始時間と終了時間でソートして返します。オプションで1つのパラメータを指定でき、それは結果をフィルタリングするためのアノテーションの種類を表す文字列です。コールバック関数には、get メソッドと同じ形式のアノテーションオブジェクトの配列が渡されます。

//retrieve all annotations
  editor.annotations.all(function (annotations, err) {
      if (err) {
          console.log('Error retrieving annotations: ' + err);
          return;
      }
  
      ///annotations is an array
      console.log('All annotations', annotations);
  });
  
  //retrieve only quiz annotations
  editor.annotations.all('quiz', function (annotations) {
      if (err) {
          console.log('Error retrieving annotations: ' + err);
          return;
      }
  
      console.log('All quiz annotations', annotations);
  });

create（作成）

新しいアノテーションを作成するには、create メソッドを呼び出し、アノテーションの種類と、プラグイン固有のプロパティを表すオブジェクトを渡します。

editor.annotations.create('pop', {
      start: 5, //start at 5 seconds into the video
      end: 10, //show until 10 seconds
      text: 'Hello World',
      mode: 'thought' //thought bubble
  }, function (annotation, err) {
      if (err) {
          console.log('Error creating annotation: ' + err);
          return;
      }
  
      console.log('Annotation successfully created', annotation);
      //Add the annotation object (or at least the annotationId) to your local list in memory here
  });

指定されていないプロパティはすべてデフォルト値が設定されます。start が省略された場合、アノテーションは動画の現在の再生位置から開始されます。

Update (更新)

アノテーションは、update メソッドにアノテーションのIDとプロパティオブジェクトを渡すことで更新できます。

editor.annotations.update(1234, {
  text: 'Goodbye World'
}, function (annotation, err) {
  if (err) {
      console.log('Error updating annotation: ' + err);
      return;
  }

  console.log('Annotation successfully updated', annotation);
});

指定されたプロパティのみが変更されます。省略されたプロパティは以前の値が保持されます。

削除

remove メソッドにアノテーションのIDを渡すことで、アノテーションを削除することができます。注意: 削除は確認なしに即時実行され、元に戻すことはできませんのでご注意ください。

editor.annotations.remove(1234, function (annotationId, err) {
  if (err) {
      console.log('Error remove annotation: ' + err);
      return;
  }

  console.log('Annotation successfully remove', annotationId);
});

CRUD API イベント

アノテーションの作成、変更、削除に関する通知イベントは、CRUD API またはユーザーインターフェースのいずれによって操作が行われた場合でも提供されます。これにより、アノテーションの完全な一覧を定期的にポーリングすることなく、ローカルのデータモデルを段階的に最新の状態に保つことができます。

以下のイベントが利用可能です（名前の大文字・小文字は区別されません）：

onAnnotationCreated
onAnnotationUpdated
onAnnotationRemoved

通知イベントを監視する方法は2つあります。エディターオブジェクトには、これらのイベントに対してコールバック関数を追加・削除するための addEventListener および removeEventListener メソッドがあります。

editor.addEventListener('annotationcreated', function (annotation) {
  console.log('new annotation created', annotation);
});

Or, event listeners can be registered when creating the editor object.

var editor = hapyak.editor({
  //fill in apiKey, video, track, etc
  onLoadAnnotations: function () {
  },
  onAnnotationCreated: function (annotation) {
      console.log('new annotation created', annotation);
  },
  onAnnotationUpdated: function (annotation) {
      console.log('annotation updated', annotation);
  },
  onAnnotationRemoved: function (annotationId) {
      console.log('annotation removed', annotationId);
  }
});

アノテーション クライアント CRUD API