Brightcove Interactivity Javascript Embed API

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

Global Options

`apiKey`

If you have a Brightcove Interactivity API key, pass it in to each API call with this parameter. Brightcove Interactivity typically issues a read API key, and a write API key. The read key should be passed to .viewer, and the write key to .editor.

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

ytPlayer = new YT.Player('video', {
  height: '390',
  width: '640',
  videoId: 'u1zgFlCw8Aw',
  playerVars: {
    html: 1,
    wmode: 'opaque'
  }
});

hapyak.viewer({
    apiKey: readKey,
    player: ytPlayer,
    playerType: "youtube",
    css: "https://modernizr.com/i/css/modernizr-2.1.1.css?v=1",
    width: 640,
    height: 360,
    trackId: 640,
    autoplay: true
});

Options

`player`

Reference to the player DOM node, Javascript object, Flash file.

`playerType`

Tells Brightcove Interactivity what sort of player was passed in. Valid values are "videojs", "youtube", "vimeo", "html5", "jplayer", "wistia", "dailymotion", "brightcove"

`width` (optional)

Tells Brightcove Interactivity the width of the player object. Optional, but the viewer may not always be able to figure out the right sizing.

`height` (optional)

Tells Brightcove Interactivity the height of the player object. Optional, but the viewer may not always be able to figure out the right sizing.

`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.

`minWidth` (optional)

Minimum width of player in pixels to show annotations. If the player width is below this value, all annotations will be hidden. Optional, defaults to 300px.

`minHeight` (optional)

Minimum height of player in pixels to show annotations. If the player height is below this value, all annotations will be hidden. Optional, defaults to 200px.

`onLoad` (optional)

A function to be called when the viewer has loaded. Will be passed one argument, a HapyakViewer 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

`userId` (optional)

You can optionally pass in a userId for tracking purposes.

`username` (optional)

You can optionally pass in a username for tracking purposes.

`groupId` (optional, requires api key)

When using an api key, you can optionally pass in a groupId. The groupId should represent some subgroup of your end users.

`variables`

Dictionary of variables to be made available to dynamic annotations.

.viewer({
  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.

hapyak.viewer({
  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:

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

Another way to accomplish the same thing:

hapyak.viewer({
  /* ...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 HapyakViewer 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.

HapyakViewer

A HapyakViewer 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>

Templates

Brightcove Interactivity supports the concept of template tracks. A template track can be applied to any video, whether it already has a project/track associated or not. To apply a template track to your video, pass in a "project" search parameter.

hapyak.viewer({
  project: {
      template: {
          tags: [arrayOfTags]
          // OR
          id: templateProjectId,
          // OR
          ids: [arrayOfProjectIds]
      }
  }
});

If there were existing annotations for the video, they will be combined with the annotations from the template. If there are no existing annotations, only the template track annotations will be shown.

FAQ

Do you host and serve videos?: No, we integrate with your existing solutions or partner to provide a complete solution as needed.
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.

Brightcove Interactivity Javascript Embed API

Global Options

apiKey

Viewer API

Example

Options

player

playerType

width (optional)

height (optional)

css (optional)

trackId

autoplay (optional)

minWidth (optional)

minHeight (optional)

onLoad (optional)

onLoadAnnotations (optional)

resetVariables (optional)

Advanced Options

userId (optional)

username (optional)

groupId (optional, requires api key)

variables

environment (optional, for debugging)

load

loadannotations

durationchange

loadedmetadata

pause

play

data

authchange

customtrackingevent