Player events

List of player events emitted and listening for events

Overview

The player emits various events that are processed by its RootController. You can listen to these events after they are processed.

Events have a set of fields that are always present and some events contain additional fields.

Example event

{
  id: "51178a37-d5a7-4d75-9a12-a26eabfe7839",
  type: "PressedPlaylistItem",
  description: "A playlist item was pressed.",
  index: 3,
  initiatedBy: "user",
  emittedFrom: "inline-player",
  status: "handled",
  createdAt: "2023-01-01T12:00:00.000Z",
  processedAt: "2023-01-01T12:00:00.005Z",
  changedProps: {
    contentIndex: { previousValue: 0, currentValue: 3 },
  },
}

For the above example, the ‘index’ field additional and is specific to the PressedPlaylistItem event.

All of the other fields are present in every event. Their schema is explained below.

Event schema

• id: a random UUID generated and assigned to the event at creation
• type: the type of event, see the table below for a listing of event types
• description: a short human-readable description of the event
• initiatedBy: who initiated the event, one of: { user, media, browser, media-session-api, google-ima-sdk }
• emittedFrom: which interface emitted the event, one of: { inline-player, bottom-widget, segment, segment-widget }
• status: the status of the event, one of: { handled, ignored-due-to-advert, ignored-due-to-scrubbing, ignored-due-to-precedence }
• createdAt: the time when the event was created in simplified extended ISO 8601 format
• processedAt: the time when the event was processed in simplified extended ISO 8601 format
• changedProps: an object listing the player properties that were changed by the event

It is recommended to not depend on changedProps and additional event fields (e.g. index) since these might change.

Instead, please query the player props directly using the Player SDK when listening to events.

Event types

The following table lists all event types emitted by the player.

Initiators denoted with a plus (+) can also be initiated by media-session-api, e.g. using playback controls on a phone lock screen.

Initiators denoted with a star (*) can also be initiated by google-ima-sdk when VAST adverts are playing.

To inspect the events further, it is recommended you listen to "<any>" event and console log them.

Type	Initiator	Description
IdentifiersChanged	browser	The Player’s content identifiers changed.
ContentAvailable	browser	Content was loaded into the player and is ready to be played.
NoContentAvailable	browser	No published and processed content is available for the identifiers.
FullScreenModeUpdated	browser	The browser entered or exited full screen mode.
PressedPlay	user+	The play button was pressed.
PressedPause	user+	The pause button was pressed.
PressedChangeRate	user	The change playback rate button was pressed.
PressedEnterOnChangeRate	user	The enter key was pressed while change playback rate was focussed.
PressedSpaceOnChangeRate	user	The space key was pressed while change playback rate was focussed.
PressedUpOnChangeRate	user	The up key was pressed while change playback rate was focussed.
PressedRightOnChangeRate	user	The right key was pressed while change playback rate was focussed.
PressedDownOnChangeRate	user	The down key was pressed while change playback rate was focussed.
PressedLeftOnChangeRate	user	The left key was pressed while change playback rate was focussed.
PressedPrevSegment	user+	The previous segment button was pressed.
PressedNextSegment	user+	The next segment button was pressed.
PressedSeekBack	user+	The seek backward button was pressed.
PressedSeekAhead	user+	The seek ahead button was pressed.
PressedPrevTrack	user+	The previous track button was pressed.
PressedNextTrack	user+	The next track button was pressed.
PressedAdvertLink	user	The advert link was pressed to open the click-through URL in a new tab.
PressedAdvertButton	user	The advert button was pressed to open the click-through URL in a new tab.
PressedAdvertImage	user	The advert image was pressed to open the advert in a new tab.
PressedAdvertVideo	user	The video background was pressed to open the advert in a new tab.
PressedBeyondWords	user	The BeyondWords logo was pressed to open the BeyondWords website in a new tab.
PressedSourceUrl	user	The source URL button was pressed to open the source article in a new tab.
VisibilityChanged	user	The player was scrolled into or out of view.
PressedVideoBackground	user	The video background was pressed.
PressedEnterOnProgressBar	user	The enter key was pressed while the progress bar was focussed.
PressedSpaceOnProgressBar	user	The space key was pressed while the progress bar was focussed.
PressedEnterOnProgressCircle	user	The enter key was pressed while the progress circle was focussed.
PressedSpaceOnProgressCircle	user	The space key was pressed while the progress circle was focussed.
PressedLeftOnProgressBar	user	The left key was pressed while the progress bar was focussed.
PressedRightOnProgressBar	user	The right key was pressed while the progress bar was focussed.
PressedLeftOnProgressCircle	user	The left key was pressed while the progress circle was focussed.
PressedRightOnProgressCircle	user	The right key was pressed while the progress circle was focussed.
PressedProgressBar	user	The progress bar was pressed at some ratio.
ScrubbedProgressBar	user+	The user pressed on the progress bar then dragged.
FinishedScrubbingProgressBar	user	The user let go after scrubbing the progress bar.
PressedMaximize	user	The maximize button was pressed.
PressedPlaylistItem	user	A playlist item was pressed.
PressedDownload	user	The download button next to a playlist item was pressed.
PressedTogglePlaylist	user	The toggle playlist button was pressed.
PressedCloseWidget	user	The close widget button was pressed.
PressedSegment	user	The user pressed on a segment in the article.
HoveredSegmentUpdated	user	The user hovered over a different segment in the article.
CurrentSegmentUpdated	media	The media’s current segment was updated.
MetadataLoaded	media	The media finished loading its metadata.
MediaLoaded	media	The media finished loading its first frame of data.
MediaSeeked	media	The media completed the seek operation.
DurationUpdated	media*	The media’s duration was updated.
CurrentTimeUpdated	media	The media’s current time was updated.
PlaybackPaused	media*	The media became paused at its current playback time.
PlaybackRateUpdated	media	The media’s playback rate was updated.
PlaybackPlaying	media	The media began playing from its current playback time.
PlaybackEnded	media*	The media finished playing because it reached the end.
PlaybackNotAllowed	media	The media cannot play because there was no user event.
PlaybackErrored	media*	The media failed to play.
CompanionAdvertChanged	media*	The companion advert associated with the VAST advert changed.

Listening to events

The player emits events in response to user actions, playback time updates, entering full screen, etc.

You can listen to these events in your JavaScript code:

const player = BeyondWords.Player.instances()[0];

player.addEventListener("<any>", console.log);

The code above registers an event listener that listens to any event and logs it to the console.

If you only want to listen to a single event type, provide its name:

player.addEventListener("PressedPlay", console.log);

player.addEventListener("PlaybackEnded", console.log);

Events contain a standard set of fields such as type and createdAt and some contain additional fields.

Please refer to Event schema and Event types for a full listing of event types and their fields.

Cleaning up

The return value of addEventListener is a string that is a handle to the listener.

This allows you remove the listener, for example, if a React component is unmounted:

useEffect(() => {
  const listener = player.addEventListener("<any>", console.log);
  return () => player.removeEventListener("<any>", listener);
}, []);

Or when your Svelte component is unmounted:

onMount(() => {
  const listener = player.addEventListener("<any>", console.log);
  return () => player.removeEventListener("<any>", listener);
});

Otherwise, the callback function will continue to be called which may result in an error in your application.