Playback Events

Backstage has the ability to receive what we call user events (or player heartbeats). Every X amount of time the player can send an event to Backstage letting us know where this user/profile has left off in a particular video or whether he/she finished it.

While you can send these events in any interval it is generally recommended that this happens no more than once every 5 seconds.

It is also recommended that this interval is the same across all applications for the service/project you're working on to ensure as little deviation as possible.

This data is used in backstage to govern things like:

• Continue Watching (playlist & list of offsets)
• Watch History
• Because you watched
• Most popular
• User recommendations
• Limit concurrent

API

The endpoint to send these events to is: /user/events, further documentation can be found here

Event

An event follows a fairly straight-forward structure and has the following properies:

• assetId this is the asset ID you want to record an event for
• assetType this is the asset type you want to record an event for (i.e. movie, episode etc)
• action the action performed by the player
• offset current place in the player timeline in seconds

Types of actions

play,stop,pause,forward,rewind

Play

The play action is the most used action, it is the one that will be sent every X amount of seconds (and at startup). It also will extend the current playback session Backstage records internally to govern things like limiting concurrent streams.

Stop

When the user has stopped watching the media (either because he/she finished or exists out of the player) this action needs to be sent.

By default Backstage will store these events in a queue that's consumed every minute. The "stop" action however triggers this queue to be moved to persistent storage immediately to make sure the assets will show up in playlists that utilize this data (continue watching / watch history).

This means that this event needs to be sent ONLY when the user actually stops watching

Pause

The pause action is to be sent when the user pauses the player.

Forward / Rewind

The forward or rewind action need to be sent when the user has finished his rewind action. It needs to contain the position of where the user has rewinded to.

Example:

• User plays regularly into 5 (offset is 300) minutes of the video
• User rewinds the player by 60 seconds
• Player sends an event with action rewind and an offset of 240