Annotations Client CRUD API

The Brightcove Interactivity Editor API object has methods for creating, reading, updating and deleting annotations.

Setup

First, create a hapyak editor object. Annotations will not be accessible until they are loaded, so it's best to wait until the loadannotations event has fired.

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

Calling CRUD methods

All the CRUD methods run asynchronously and accept an optional callback function as the last parameter, which will run when the operation has succeeded and finished saving or has failed. The callback function receives two arguments:

  1. The result of a successful operation, or null if the operation failed.
  2. The error message in case of an error, or null if the operation succeeded.

Annotation types

The API will provide a list of available annotation types with the types method, which takes no parameters other than the callback function. The callback function recieves a hash of objects representing information about each annotation type. The following fields are provided:

  • id - string used to identify the type
  • title - text title of the annotation type
  • enabled - boolean value describing whether new annotations of this type can be created
  • icon - a string that can be used to render an icon representing this type
  • defaults - a hash of default properties
editor.annotations.types(function (types, errr) {
  if (err) {
      console.log('Error retrieving annotation types: ' + err);
      return;
  }

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

Retrieving a single annotation

Individual annotations can be retrieved by numerical id using the get method.

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

The retrieved object will contain the following fields:

  • annotationId - permanent unique id for this annotation
  • trackId - id of the track to which this annotation is attached
  • type - a string representing the type of the annotation (e.g. "pop", "hotlink", "image", "quiz")
  • created - numerical unix time stamp of the annotations' creation time (i.e. seconds since midnight UTC 1/1/1970)
  • modified - time that the annotation was last modified (also numeric time stamp)
  • writable - a boolean value indicating whether this annotation can be modified
  • properties - plugin-specific properties for this annotation, including start time

Sample retrieved annotation object:

{
  "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"
  }
}

Listing Annotations

The all method will return all annotations currently loaded, sorted by start and end time. There is one optional parameter, which is a string representing the annotation type by which to filter the results. The callback function receives an array of annotation objects in the same format as those returned by 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

To create a new annotation, all the create method, passing the annotation type and an object representing the plugin-specific properties.

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

Any properties not provided will be set to the default value. If start is omitted, the annotation will start at the current time of the video.

Update

An annotation can be updated by calling the update method with the id of the annotation and the properties object.

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

Only provided properties will be modified. Any properties omitted will retain their previous values.

Delete

Delete an annotation by calling the remove method with the annotation id. Warning: Deletion will happen immediately without any confirmation prompt and cannot be undone, so please be careful.

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

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

CRUD API events

Notifications events are provided for all creation, modification and deletion of annotations, whether the operation was initiated with the CRUD API or with the user interface. This is useful for keeping your local data model updated incrementally without having to periodically poll for a complete list of annotations.

The following events are available (names are case-insensitive):

  • onAnnotationCreated
  • onAnnotationUpdated
  • onAnnotationRemoved

There are two ways to listen for notification events. The editor object has addEventListener and removeEventListener methods for adding and removing callback functions for these events.

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