Skip to content

JavaScript Player version 1.0.0 Migration guide

Version 1.0.0 comes with major significant improvements to the internals of the player, as well as improved TypeScript types in general and for event listeners in particular.

We have also overseen our player API to improve the consistency of the player and to enable future improvements.

For that reason, when upgrading to RedBeePlayer v1.0.0 there are some changes you need to make to your implementation.

1. wrapper argument

This has been changed from a string containing a CSS selector to now taking an actual HTML element, and the name has been changed to wrapperElement.

Before:

const player = new RedBeePlayer({
  player: { wrapper: "div#video-wrapper" }
});

Now:

const player = new RedBeePlayer({
  player: { wrapperElement: document.querySelector("div#video-wrapper") }
});

This is better suited for client-side libraries when you have access to the element.

2. Changes to the player options in the constructor, and the load-method

We have made improvements to the consistency and flexibility for how you load the media source (usually asset).

In the new version, all the parameters that may differ between media sources have been moved from the constructor to the load method (if they weren't already in the load method).

The easiest way to call load is by passing a string with an asset id, external asset id or an external URL to a media stream manifests or media files.

We refer to that string argument as source.

player.load(source);

Note that when you pass an external asset id as a source string it needs the prefix external:.

player.load(`external:${externalAssetId}`);

Supported load options

For more advanced cases you need to pass an object of properties, including:

  • source (required), The asset id, manifest or media url.
  • startTime, time (in seconds) to start from. The player will continue where the user left off. If you do not want this, set this to 0.
  • audioOnly (default false), Set to true to only play the audio from the stream.
  • poster, URL for an image to show while the player is paused, stopped or during playback of audio only sources. Not normally needed as you can add a poster to the asset in our platform instead.
  • materialProfile, name of the specific video material profile to load (usually not needed).
  • ads (default undefined), See below for details.

Example

player.load({
  source: assetId,
  startTime: 0,
  poster: "https://example.com/poster.jpg",
  audioOnly: true, 
});

Playlists

To create a playlists, pass an array of sources to the load method. The source arguments can be either strings or objects.

player.load([
  "e720d1da-0915-411b-807c-3e83f451bbb7_29C72F",
  "external:e720d1da-0915-411b-807c-3e83f451bbb7",
  "https://dash.akamaized.net/akamai/bbb_30fps/bbb_30fps.mpd"
]);

Or pass an object (supports all the load arguments listed above).

player.load([
  { source: source1, startTime: 0 },
  { source: source2, poster: "https://example.com/poster.jpg" },
  { source: source3, audioOnly: true, startTime: 0 }
]);

3. player.load() no longer returns a promise

Please use event listeners instead:

const player = new RedBeePlayer({ player: playerOptions });
player.once(PlayerEvents.LOADED, () => {
  // player is loaded
});
player.on(PlayerEvents.ERROR, () => {
  // player has encountered an error
});
player.load();

The on method is an alias of addEventListener and once is a new method that only listens for the first occurrence of an event. See the documentation for "Events" for more non-breaking changes for the event methods.

4. PlayerEvents.ALL removed

As part of our efforts to improve our TypeScript types, this event has been substituted by a separate method:

Before:

player.addEventListener(PlayerEvents.ALL, (event, data) => {
  ...
});

Now:

player.onAll(({ event, data }) => {
  ...
});

The type of data will now differ depending on the event (see below).

5. Event listener changes

We have improved our Typescript types in general, and for events in particular. The handler method for event listeners is now fully typed. So if your development environment has TypeScript set up, you get the benefit of type checking and code completion for event listeners.

Some of the data (payload) arguments had to change slightly in the process.

Previously our event emitter added the properties currentTime, duration, utcCurrentTime, utcDuration, seekable, and utcSeekable to all event payloads. This created some problems, so we had to change that. Now instead we have a type DefaultPlayerEvent for these properties. Most of the events either emit this type, or a type that inherit from it. These should be backward compatible.

As of this version, some events will not have any payload (technically the payload is undefined): EMPTY_SLOT, AIRPLAY_START, AIRPLAY_STOP, LOAD_START, SESSION_ACQUIRED, PLAYER_SETUP_COMPLETED, ENTITLEMENT_GRANTED.

The event payloads no longer inherit from or include the DefaultPlayerEvent properties for the following events: STATE_CHANGED, BITRATE_CHANGED, LOADING, ERROR, AD_START, AD_COMPLETE, ADBLOCK_START, ADBLOCK_COMPLETE, CAST_START, CAST_STOP, PROGRAM_CHANGED, NOT_ENTITLED, BLACKOUT.

The ERROR event payload has changed so it emits our error type, rather than an object.

For the STATE_CHANGED event payload we renamed the property state to playbackState.

6. Moved or removed constructor options

Keyboard constructor option section have been moved into skin

Previously, the player constructor had a separate keyboard section. This only had one option disabled (default: false). This has now been moved into the skin section, and renamed to keyboardShortcuts (default: true)

Before:

new RedBeePlayer({
  keyboard: { disabled: true }
})

Now:

new RedBeePlayer({
  skin: { keyboardShortcuts: false }
})

locale has been moved from skin to player

When we initially added this argument it was only used for the skin, but now we also use it in the player, so it has been moved to that section.

Before:

new RedBeePlayer({
  skin: { locale }
})

Now:

new RedBeePlayer({
  player: { locale }
})

Analytics baseURL constructor option has been shortened

The name was inconsistent with how we name other options, so it has now been shortened from analytics.analyticsBaseUrl to analytic.baseUrl.

From:

new RedBeePlayer({
  analytics: { analyticsBaseUrl: "https://..." }
})

To:

new RedBeePlayer({
  analytics: { baseUrl: "https://..." }
})

limitedMemory and ads.gdprOptin have been removed from player options

These options were largely undocumented options we added temporarily, but which shouldn't be needed in the player. In the unlikely case that you were using any of them, contact us for alternatives.

7. Removed methods

The following methods have been removed from the player instance:

  • getExposureBaseUrl() (should not be needed)
  • getWrapperElement() (should not be needed)
  • getSeesion() (please use getSession()instead)

8. RedBeePlayerDeprecated has been removed

RedBeePlayerDeprecated was an older and deprecated version of the player that we haven't supported or documented how to use for a very long time. With the v1.0.0 release we removed this.