Building a Custom Viewer Experience with the BoxCast API

SKILL LEVEL: Developer

This article is for programmers and developers who wish to build their own custom viewer experience leveraging the BoxCast API.

Common Use Cases

Building a custom channel/broadcast listing into your site or app
- For example, see https://github.com/boxcast/example_video_portal_vuejs
Using a non-BoxCast video player (e.g. video.js, JWPlayer, etc)
- For example, see https://boxcast.github.io/boxcast-sdk-js/#overview
Building a custom OTT app, or integrating BoxCast broadcasts into an existing OTT app (e.g. Roku, FireTV, etc)

BoxCast API Overview

The BoxCast API exists to provide partners and broadcasters with programmatic access to BoxCast's services, including scheduling broadcasts, managing channels, embedding video players, consuming viewer analytics, etc. In general, anything that a broadcaster can accomplish through the BoxCast web dashboard can be accomplished directly through the API.

There are 4 different BoxCast authentication mechanisms supported by the BoxCast API:

Public for read-only access to channels and public broadcasts
Client Credentials for individual account access only via a secure client (such as the account owner's server)
Authorization Code exchange with a secure client (such as a 3rd party app with a secure server)
Authorization Code plus PKCE with a public client (such as a mobile app or SPA with no secure server)

Answer a few questions to see if this article is for you:

Do you want to schedule broadcasts automatically or edit/create/delete any other BoxCast information as part of your integration?
--> If so, you cannot use the public API, so this article is not intended for your use case.
Are you trying to access BoxCast accounts that you do not own the rights to?
--> If so, you cannot use the public API, so this article is not intended for your use case.
Do you access any BoxCast resources other than Channels and Broadcasts?
--> If so, you cannot use the public API, so this article is not intended for your use case.

Getting Started with the BoxCast Public API

BoxCast supports public authentication on GET requests to certain resources. The data returned is limited to non-sensitive information, and a known Account, Channel, or Broadcast ID is required in order to access each resource. With public authentication, you can simply query the API resource with no Authorization header or token required. Any active account is able to use the Public API.

There are multiple SDKs available to guide your implementation depending on your language of choice. The SDKs will help with listing and watching broadcasts in your various account channels. You are strongly encouraged to use one of the following SDKs rather than building your own:

Finding Your Channel ID

You can find your account and channel IDs on the BoxCast Dashboard. Simply visit the Settings page of the Dashboard and look for your Account ID and Channel ID:

If you create custom channel(s), each one will be assigned a unique ID as well. Those Channel IDs can be found in the Channel Settings dialog, under the Advanced tab.

Public API Resource Endpoints

Channel Broadcasts

You can query for all broadcasts in a given channel using the following endpoint:

https://api.boxcast.com/channels/{channel_id}/broadcasts

Parameters:

q - search query (e.g. "timeframe:current")
p - page number (default 1)
l - page size limit (default 20)
s - sort (e.g. "-starts_at")

Broadcast Details

To retrieve additional fields on the broadcast beyond what the channel-broadcast list response provides, you can query for broadcast details using the following endpoint:

https://api.boxcast.com/broadcasts/{broadcast_id}

NOTES:

The response here does not provide a playable media file. In order to watch the broadcast, you will need to either (a) Embed the BoxCast Player, (b) Integrate a supported BoxCast SDK, or (c) build your own video player integration.
Embedded Video Player Documentation:
- BoxCast JS Player
- Example Vue.js Video Portal

Broadcast View

CAUTION: Before you attempt to use a custom video player using this route, please try to use one of the supported BoxCast SDKs or request assistance from BoxCast. This will provide the greatest playback quality, reliability, and allows for proper tracking of viewer analytics so you can better support and understand your audience. The SDKs also afford easier integration by simply requesting the playback of a given broadcast rather than manually looking up the playlist and processing the various states.

The broadcast "view" is required in order to access the HLS playlist (M3U8) for a given broadcast. It can be found by querying the following endpoint:

https://api.boxcast.com/broadcasts/{broadcast_id}/view