Api Doc

Created by Yiftach Osher Freeman, Modified on Wed, 16 Nov, 2022 at 12:39 PM by Yiftach Osher Freeman

You can control the Reelbox Player through an interface accessible through the window.reelboxAPI object. This object gives you access to smart box clients, which expose calls and events to implement e.g. your own player control, adaptive UI or analytics logging.

Core Concepts

We call the running application a Reelbox. We hide all interfaces to this object, so you can only access it through the objects we expose with the window.reelboxAPI object.
We only expose a SmartBoxClient. You can think of it as an abstraction of a Reelbox, which only exposes a restriced set of calls.
You can get SmartBoxClient Objects though window.reelboxAPI or you can subscribe to window events that we trigger whenever a new Reelbox is created or destroyed. In these window events we also add the client to the payload.

Please see below for a schema of these objects.

Quickstart

This will help you to get a rough understanding of the API and get up and running quickly. See further below for more detailed documentation.

1: Install our Reelbox Player

Make sure you have your script tag installed in your page header. You can get your from https://app.reelbox.video/account

<head>
    <script
        type="text/javascript"
        src='<https://cdn.reelbox.video/YOUR_SELLER_ID>'>
    </script>

    <!-- Other header stuff... -->
</head>

2: Use the API

Let’s assume you have the following image that you linked with a reelbox, and you want to control the Reelbox through the API.

<img
    id="my-img-id"
    src="<https://images.unsplash.com/photo-1649709930042-dc613db1e5ac?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=2370&q=80>"
>

Access the SmartBoxClient

In this example, we use the window events to get the client as soon as it’s available.

let client = null;

window.addEventListener('reelboxcreate', (e) => {
    // We can make sure we get the right client by checking the target id:
    if (e.detail.smartBoxClient.target.id === "my-img-id") {
        // Save a reference
        client = e.detail.smartBoxClient;
    }
});

window.addEventListener('reelboxdestroy', (e) => {
    // Unset the client.
    if (e.detail.smartBoxClient.target.id === "my-img-id") {
        client = null;
    }
});

Alternatively, you can also use the window.reelboxAPI access. You can get the client relevant to you from an array of all active clients:

let client = window.reelboxAPI?.smartBoxClients[0];

If you use the latter approach make sure to check the array length and if the client actually exists at that index.

Play the Video

Let’s now assume you have some custom play, pause and close buttons somewhere in your web site to control the player. You can call the SmartBoxClient controls from their click handlers as such:

// PLAY
document
    .findElementById('my-play-button')
    .addEventListener('click', () => {
        // Call the SmartBoxClient controls
        client.play();
    });

// PAUSE
document
    .findElementById('my-pause-button')
    .addEventListener('click', () => {
        // Call the SmartBoxClient controls
        client.pause();
    });

// CLOSE
document
    .findElementById('my-close-button')
    .addEventListener('click', () => {
        // Call the SmartBoxClient controls
        client.close();
    });

Pro tip: You can use your Reelbox Dashboard set the Reelbox’s normal play button to invisible when using your own play button.

Optional: Subscribe to Reelbox Events

Now, to get access to some events you can register your listeners as shown here. We assume you have some logic in place to update your UI, I’ll just use some sample functions which could make sense:

client.addEventListener('canplay', (e) => {
    // Execute some custom code from your own web site.
    setCustomPlayButtonVisibility('visible');
});

smartBoxClient.addEventListener('videostart', (e) => {
    awesomeAnalytics.trackEvent('A video was started!');
});

smartBoxClient.addEventListener('videoend', (e) => {
    awesomeAnalytics.trackEvent('A video ended!');
});

smartBoxClient.addEventListener('close', (e) => {
    awesomeAnalytics.trackEvent('User closed the video!');
});

smartBoxClient.addEventListener('playbackend', (e) => {
      awesomeAnalytics.trackEvent('Video-playlist reached its end.');
});

Alrighty, let’s get more technical...

Reelbox Browser API Interfaces

`window.reelboxAPI`

window.reelboxAPI = {
    smartBoxClients: SmartBoxClient[]
}

`SmartBoxClient`

The clients that the window.reelboxAPI object exposes give you the following calls:

interface SmartBoxClient {
    // ID of the reelbox, which is shared with the SmartBoxClient.
    readonly id: number;
    
    // The HTML element that the reelbox is replacing.
  readonly target: HTMLElement;

    /**
        * Control the player:
        */
    play(): void;
  pause(): void;
  close(): void;
    
    /**
        * Register for event updates:
        */
    addEventListener(type: string, callback: EventListenerOrEventListenerObject | null, options?: AddEventListenerOptions | boolean): void;
  removeEventListener(type: string, callback: EventListenerOrEventListenerObject | null, options?: EventListenerOptions | boolean): void;
}

Reelbox Browser API Events

`window` Events

The window object is notified whenever a new Reelbox is added or removed from your page. You can use the following event listeners to subscribe to these events, and use event.detail.smartBoxClient to get the SmartBoxClient payload:

window.addEventListener('reelboxcreate', (e) => {
    console.log(e.detail.smartBoxClient);
    // e.detail.client is a SmartBoxClient.
});

window.addEventListener('reelboxdestroy', (e) => {
    console.log(e.detail.smartBoxClient);
    // e.detail.client is a SmartBoxClient.
});

// Unregister the listener when your done through window.removeEventListener()
// See <https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/removeEventListener>

When you capture an added Reelbox in such events, we deliver you a SmartBoxClient object that you can use to control the Reelbox. You can store this object somewhere as a variable in your code, but you should remember to unset it when the Reelbox is destroyed. You can identify SmartBoxClient objects through their ID, and you can use the SmartBoxClient.target object to figure out which HTML element the Reelbox is linked to. E.g. if you gave an ID to that HTML element, you can identify the Reelbox that is linked to that element.

`SmartBoxClient` Events

You can subscribe to the following events of the SmartBoxClient:

smartBoxClient.addEventListener('canplay', (e) => {
    // Dispatched when the reelbox is loaded and all required
  // data is available.

  // Note that a call to play() here would result in an error
  // because the user needs to interact with the video element
    // before browsers can actually play the video.
    // You might wonder why we have this event then: It is intended
    // so that you can adapt your UI to the new state, e.g. hiding a
    // progress indicator or showing a play button etc.
});

smartBoxClient.addEventListener('videostart', (e) => {
    // Dispatched whenever a video is started, either through a user
  // interaction or through the player itself. videostart events
    // might be dispatched multiple times for the same video, as the
    // video start might have multiple causes or simply because the
    // user starts the video multiple times.
    console.log(e.detail.playlistIndex);
    console.log(e.detail.video);
});

smartBoxClient.addEventListener('videoend', (e) => {
  // Dispatched when the video ends. Will not be dispatched
    // if the user closes the player or skips the video before
    // it ends.
    console.log(e.detail.video);

    // hasNext tells you if there is another video in the playlist
    // coming up.
    console.log(e.detail.hasNext);
});

smartBoxClient.addEventListener('close', (e) => {
    // Dispatched when the users directly interacts with the UI
    // to close the player. Calls to SmartBoxClient.close() will
    // also dispatch this event.
});

smartBoxClient.addEventListener('playbackend', (e) => {
  // Dispatched when the playback ended. This is the case when
    // the whole playlist ran through or if the player was closed.
    // isLoop tells you if the playlist will be looped.
    console.log(e.detail.isLoop);
});

// Unregister the listener when your done through smartBox.removeEventListener()
// See <https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/removeEventListener>