Brightcove Interactivity Javascript Embed API

The Brightcove Interactivity Embed API allows you to create a viewer and/or editor for .

Viewer API

The Brightcove Interactivity annotation viewer supports viewing annotations for an existing video element on a page. The existing video javascript object, iframe, html element, etc is passed into the viewer API method call.

Example



  player.interactivityViewer({
    css: "https://modernizr.com/i/css/modernizr-2.1.1.css?v=1",
    width: 640,
    height: 360,
    trackId: 640,
    autoplay: true
});

Options

width (optional)

Brightcove doesn't support this as a parameter, this needs to be defined in the player options.

height (optional)

Brightcove doesn't support this as a parameter, this needs to be defined in the player options.

css (optional)

The location of a CSS file to load.

trackId

The ID of the Brightcove Interactivity commentary track to load. A Brightcove Interactivity "track" is the container for popup, drawing, audio, etc, commentary.

autoplay (optional)

If set to true, the video with commentary will start to play once the video is loaded, and the track has been downloaded from www.hapyak.com.

onLoad (optional)

A function to be called when the viewer has loaded. Will be passed one argument, a Interactivity Viewer object (see below).

onLoadAnnotations (optional)

A function to be called when all annotations have been loaded.

resetVariables (optional)

If set to true, all track variables set by quizzes, clicks or iframe scripts will be cleared before loading.

Advanced Options

groupId (optional, requires api key)

variables

Dictionary of variables to be made available to dynamic annotations.

player.interactivityViewer
  variables: {
      courseName: "Math 101"
  }
});

environment (optional, for debugging)

Valid values are "production", "staging" or "feature". Only used when attempting to test against a specific environment.

player.interactivityViewer
  environment: 'production'
});

The viewer API triggers a number of event callbacks related to both video and data. An event callback may be registered by passing the event name to addEventListener (see below) or including the event callback as an option, with the name of the event preceeded by on as the key.

For example, the play event, which fires whenever the video starts playing may be registered as an option:

player.interactivityViewer
  /* ...other options here... */
  onplay: function() {
      console.log('video started playing');
  }
});

Another way to accomplish the same thing:

player.interactivityViewer
  /* ...other options here... */
  onload: function(viewer) {
      viewer.addEventListener('play', function () {
          console.log('video started playing');
      });
  }
});

The advantages of using addEventListener are that multiple callback functions can be registered and that a listener can be removed with the removeEventListener method.

The following events are available:

load

The load event fires when the viewer has loaded. The callback function receives one argument, which is the Interactivity Viewer object. (This event cannot be registered on with addEventListener.)

loadannotations

This event fires when all annotations have been loaded

durationchange

This event fires when the duration of the video is available to the API.

loadedmetadata

This event fires when the dimensions (height and width) and duration of the video are available to the API.

pause

This event fires when the video pauses.

play

This event fires when the video plays.

data

This event fires every time a data variable is changed. The callback function receives two arguments: an object hash of all data variables, and an object hash of all data variables that have changed since the last time the event fired.

authchange

This event fires every time user authorization data is changed. The callback function receives one argument: an object hash of all user auth properties.

customtrackingevent

This event fires every time an event that is tracked by analytics occurs. This includes video actions, such as pause, play, and seek, as well as annotation views and annotation actions. The callback function receives one argument: an object hash describing the event and all its properties.

Interactivity Viewer

A Interactivity Viewer object will be passed to the onLoad callback and supports the following methods and properties.

Methods

getTrackId()

Returns the id (an integer) of the currently loaded track.

resize(width, height)

Resizes the player to the desired height and width.

play()

Plays the video.

pause()

Pauses the video.

resetVariables()

Reset all track variables set by quizzes, clicks or iframe scripts.

getData(name)

Returns the value of the variable by name. If the method is called without any argument, it returns an object hash of all variable values.

setData(name, value)

Sets the value of the variable by name. If the second argument is omitted, the key value is cleared.

If the first argument is null or if there is one parameter that is an object, that object is used as a hash of multiple variable values to be set.

destroy()

Tells the editor to shutdown and cleanup.

Properties

duration

The duration in seconds of the video. This value will be NaN until the onlaodedmetadata event has fired. This property is read-only.

currentTime

The current time in the video of the play head, in seconds. This property can be set to cause the video to seek. If currentTime is set to a negative number or is greater than the duration, seeking will not happen.

paused

A boolean value indicating the play/pause state of the video. A video may not be playing even though paused is false if the video is stalled while loading from the network. This property is read-only.

Setting custom user identification variables

Interactivity analytics can be updated to track additional information, in this case you can setup a userId and username. This information can be used to identify the user in the analytics metrics.

Add the custom userId and username variables as Query Parameter.

  • userId Type: String.
  • username Type: String.
https://players.brightcove.net/{BC_ACCOUNT}/{YOUR_PLAYER}/index.html?interactivityProjectId={PROJECT_ID}&videoId={VIDEO_ID}&userId={USER_ID}&username={USERNAME}


Add the custom userId and username variables to the advanced embed.

  • data-interactivity-user-id Type: String.
  • data-interactivity-username Type: String.

      <div style="width: 960px;">
        <video-js id="testingvid" data-account="your_account_id" data-player="your_player_id" 
        data-embed="default" controls="" data-video-id="your_video_id" data-interactivity-project-id="
        your_interactivity_project_id" data-application-id="" 
        data-interactivity-user-id="your_user-id"  data-interactivity-username="
        your_interactivity_username" width="960" height="540"
        class="vjs-fluid"></video-js></div>
      
      <script src="https://players.brightcove.net/1866680400001/oYMIsqoPB_default/index.min.js"></script>

FAQ

Will this work behind a firewall?
As long as the firewall can allow access to our HTTPS cloud service, yes.
How can I customize the look and feel of the player and annotations?
All styles can be controlled via CSS giving you absolute power over styling.
Does this work on mobile?
Annotations will work in any browser that allows HTML to be overlaid on video. Android and iOS devices are generally able to view annotations using our solution.