Advanced Usage

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

Method Notes
player.getCurrentTime() Returns a value in seconds representing the playhead timestamp
player.getDuration() Returns a value in seconds representing the total video duration
player.mute() -
player.pause() -
player.play() -
player.seek(time) Time should be a number between 0 and the video duration
player.seekPercentage(percent) Percent should be a number between 0 - 100
player.setVolume(percent) Percent should be a number between 0 - 100
player.stop() -
player.unmute() -

Video Player Options

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

Option Type Default Description
autoplay bool false If true, start the video immediately. Otherwise, show the “poster” image until the user clicks play.
showRelated bool false If true, show a playlist of other videos for the given channel. NOTE: A single broadcast “channel” will only have itself in its related videos.
showTitle bool false Display the broadcast title outside of the player window
showDescription bool false Display the broadcast description outside of the player window
showHighlights bool false Display any captured highlights for the selected broadcast
showCountdown bool false Display a countdown timer prior to the broadcast starting
customPoster URL null URL to an image you would like to use instead of the preview image BoxCast generates from a frame of the video
customPreroll URL null URL to a video you would like to show looping prior to a broadcast starting
debug bool false Whether or not to enable debug console logging
onLoadBroadcast function null Function that is called when a new broadcast is loaded. The function is given an argument that contains a Broadcast object
onLoadPlayer function null Function that is called when an instance of the Clappr player is available. The function is given an argument that contains a Player object
onLoadHighlight function null Function that is called when a new highlight is loaded. The function is given an argument that contains a Highlight object
onTicketPurchaseCompleted function null Callback from ticket purchase
onRefresh function null Callback when broadcast/playlist metadata is refreshed
onGeoBlockRestricted function null Callback when viewer is not allowed to view content due to region restriction
selectedBroadcastId int null If the channel has multiple broadcasts, use this to specify the id of the one that should be selected when loading the widget
selectedHighlightId int null If the selected broadcast has any highlights, use this to specify that the widget should play the highlight upon loading
messages object null Override certain user-facing messages and titles with your own text (Learn More)
relatedBroadcastsQuery object null  
selectedBroadcastId string null Allows you to pre-select a certain broadcast within a larger channel embed
hostname string window.location.host Override the URL used for reporting the playback host for metrics (useful if embedding inside webview in app)
defaultVideo string next Manages whether the next event is shown immediately (‘next’) or if we should rely on the server-side 50/50 logic (‘closest’). This changes the API playlist query to include or exclude timeframe:next
layout string null Set to “playlist-to-right” to have the playlist rendered on the right side of the video on large screens instead of below the title well like the normal layout.
onPlayerStateChanged function null Function that is called when the player’s state changes. Provides 2 arguments: the string event name (‘play’, ‘seek’, ‘pause’, ‘stop’, ‘ended’, ‘error’, ‘buffering’, ‘dvr’) and an optional event details

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

Option Type Default Description
autoplay bool false If true, start the video immediately. Otherwise, show the “poster” image until the user clicks play.
showRelated bool false If true, show a playlist of other videos for the given channel. NOTE: A single broadcast “channel” will only have itself in its related videos.
showTitle bool false Display the broadcast title outside of the player window
showDescription bool false Display the broadcast description outside of the player window
showHighlights bool false Display any captured highlights for the selected broadcast
showCountdown bool false Display a countdown timer prior to the broadcast starting
customPoster URL null URL to an image you would like to use instead of the preview image BoxCast generates from a frame of the video
customPreroll URL null URL to a video you would like to show looping prior to a broadcast starting
debug bool false Whether or not to enable debug console logging
onLoadBroadcast function null Function that is called when a new broadcast is loaded. The function is given an argument that contains a Broadcast object
onLoadPlayer function null Function that is called when an instance of the Clappr player is available. The function is given an argument that contains a Player object
onLoadHighlight function null Function that is called when a new highlight is loaded. The function is given an argument that contains a Highlight object
onTicketPurchaseCompleted function null Callback from ticket purchase
onRefresh function null Callback when broadcast/playlist metadata is refreshed
onGeoBlockRestricted function null Callback when viewer is not allowed to view content due to region restriction
selectedBroadcastId int null If the channel has multiple broadcasts, use this to specify the id of the one that should be selected when loading the widget
selectedHighlightId int null If the selected broadcast has any highlights, use this to specify that the widget should play the highlight upon loading
messages object null Override certain user-facing messages and titles with your own text (Learn More)
relatedBroadcastsQuery object null  
selectedBroadcastId string null Allows you to pre-select a certain broadcast within a larger channel embed
hostname string window.location.host Override the URL used for reporting the playback host for metrics (useful if embedding inside webview in app)
defaultVideo string next Manages whether the next event is shown immediately (‘next’) or if we should rely on the server-side 50/50 logic (‘closest’). This changes the API playlist query to include or exclude timeframe:next
layout string null Set to “playlist-to-right” to have the playlist rendered on the right side of the video on large screens instead of below the title well like the normal layout.
onPlayerStateChanged function null Function that is called when the player’s state changes. Provides 2 arguments: the string event name (‘play’, ‘seek’, ‘pause’, ‘stop’, ‘ended’, ‘error’, ‘buffering’, ‘dvr’) and an optional event details

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