Advanced Usage

• Installation

• Usage

  • Fetching Data from the BoxCast API
  • Loading Video Player for Single Broadcast
  • Loading Video Player for Channel (Multi-Broadcast)
  • Loading Highlight Clips
  • Controlling Video Player
  • Video Player Options
  • Unloading the Player

Installation

The boxcast.js library can be loaded from our CDN by including the script tag anywhere on your page.

<script src="https://js.boxcast.com/v3.min.js"></script>

Usage

Fetching Data from the BoxCast API

The BoxCast API allows you to retrieve information about any of the broadcasts or channels you have configured. This JavaScript SDK provides some convenience methods to access the public information that can be shared without authentication.

For integrations requiring access to the non-public data under an OAuth-protected authenticated scope, please see the [BoxCast API Documentation](https://assets.boxcast.com/api/reference/)

Get an individual broadcast by broadcastId:

boxcast.getBroadcast(broadcastId)
  .then(function(broadcast) {
    console.log('Loaded broadcast', broadcast);
  })
  .catch(function(error) {
    console.error('Error loading broadcast', error);
  });

Get a list of all broadcasts in a channel by channelId:

var promise = boxcast.getChannelBroadcasts(channelId, args);

Get an list of all highlights for a single broadcast by broadcastId:

var promise = boxcast.getBroadcastHighlights(broadcastId, args);

Get an list of all highlights for all broadcasts within a channel by channelId:

var promise = boxcast.getChannelHighlights(channelId, args);

Loading Video Player for Single Broadcast

To embed the BoxCast JavaScript Player, you need to know the channel_id based on how user discovered the broadcast. If you are embedding a single broadcast, the broadcast.channel_id is sufficient, but if it has found through a channel listing, you should use the channel.id instead to ensure analytics are properly attributed to the channel and any channel content rules are properly applied.

var selector = '#my-element-id';
var broadcastChannelId = 'my-test-broadcast-channel'; // REPLACEME
var broadcastId = 'abcdefghijkl0123456789'; // REPLACEME
var context = boxcast(selector);
context.loadChannel(broadcastChannelId, {
  autoplay: true,
  showTitle: true,
  showDescription: true,
  showHighlights: true,
  showRelated: false,
  selectedBroadcastId: broadcastId
});

The `selectedBroadcastId` parameter is optional if the channel ID you specified is only for a single broadcast. But it is useful when you want to pre-select a broadcast within the context of another larger custom channel, especially when `showRelated` is `true`.

Loading Video Player for Channel (Multi-Broadcast)

var selector = '#my-element-id';
var channelId = 'my-test-multi-event-channel';
boxcast(selector).loadChannel(channelId, {
  autoplay: false,
  showTitle: true,
  showDescription: true,
  showHighlights: true,
  showPlaylist: true,  //<-- tells the widget to render a searchable/paginated listing of broadcasts in the channel
});

Loading Highlight Clips

The showHighlights flag when loading a single broadcast or channel tells the widget whether or not to check for highlights. When true, any highlight clips that you have generated on the BoxCast Broadcaster Dashboard will be made available to watch for viewers.

Controlling Video Player

Once you have loaded a broadcast, you can programatically control the video player if desired. First, you must access the player object, and then you can perform simple commands such as player.play(), player.pause(), and player.seek(60).

Get Player Reference - Option 1

The most reliable way to access the player is to use the onLoadPlayer callback.

var boxcastPlayer = null;
boxcast('#my-element-id').loadChannel('my-channel', {
  // ... options here ...
  onLoadPlayer: function(player) {
    boxcastPlayer = player;
  }
});

Get Player Reference - Option 2

If there is only 1 player on the page, you can access it by using the global boxcast object. Note that this may be null if the player has not yet loaded.

boxcast('#my-element-id').loadChannel('my-channel', {
  // ... options here ...
});

function getPlayer() {
  return boxcast.model.player;
}

Player Methods

Video Player Options

When requesting a video player, there are several options that can be specified:

When requesting a video player, there are several options that can be specified:

Unloading the Player

You must take care to properly unload the player from the DOM if you want to remove it while the user remains on the page. Simply removing the HTML element containing the player is not enough to unload it (it uses web workers and has other asynchronous javascript running that will not be stopped).

To properly dispose of the player reference, you must first maintain a reference to the original context. Then, using that context, call the context.unload().

var context = boxcast('#my-element');
context.loadChannel('mychannelid', {
  /* options */
});

// .... some time later ...
context.unload();