How to do error handling on Web

As a developer, you could be interested in error handling for any of the following reasons:

• You want to render human-friendly error messages inside the video player. Reading this error message,
  • the user can either remediate the issue by themselves (e.g. by refreshing the page, by checking again in some time, ...),
  • or contact a support service with this error code.
• You want to send error-data to an analytics service. (And this service helps you to identify frequent issues.)
• You want to self-remediate the issue. For example, if a stream is unavailable, you want to retry to load the stream, or load a different stream.
• ...

THEOplayer exposes different types of errors, and you can interact with them in two ways:

1. Through an event listener, and attaching an event handler to this listener.
2. Through a getter, which holds data when an error has occurred.

The sections below describe the "top-level", "generic", "player" error event. This event is fatal and prevents playback. There are also other error events, for example the one dispatched by the Chromecast API. You handle those error events in the same fashion.

Event listener

Subscribe to the error event of the player, and attach a callback function which implements the error handling.

player.addEventListener('error', function (errorEvent) {
  console.log(errorEvent.errorObject);
});

Other interfaces dispatch their own error event, for example the error event of the Chromecast API. You handle those in the same fashion.

Getter

You can query an occurred "generic player error" through the errorObject property of the player.

player.addEventListener('error', function () {
  console.log(player.errorObject);
});

Note that other types of errors are not available through this approach.

Types of errors

"Which error related events does the player expose" lists which types of errors there are. Note that generally speaking only the "generic error event" is fatal. Other events, like the "Chromecast error event" and the "ad error event", are considered non-fatal because some type of playback can still continue.

"Error codes" lists which error codes are available for the "generic error event".

Remarks

• We encourage you to use event listeners to handle errors. The data in this event can be processed (e.g. stringified) and transferred (e.g. sent to an analytics service).
• You could render your own error messages inside the video player. The demo at http://demo.theoplayer.com/using-custom-error-messages offers some help on this.