Skip to main content

Playlists

A page object will not yet give you assets to render, it defers that to the playlist objects. A page will give you the skeleton structure, after which for each section you'll get it's assets via the playlist API.

Getting the playlist​

A section object in a page will give you a value in one of it's following properties:

  • playlistId
  • computedPlaylist

When one is filled the other will be null.

The playlistId property can be directly plugged into /playlist/{id} API. The computed playlist API will need to be resolved from the computedPlaylist property.

Response​

Once you retrieved the playlist response via either the playlist or computed playlist API the response will contain an items property that contains all the assets that you need to render in your application.

A playlist can always contain any type of asset supported by Backstage.

Computed playlists​

When you receive a value in the computedPlaylist property you can expect one of the following playlists.

  • continue_watching
  • favorite
  • recommendations
  • watch_history
  • because_you_watched
  • live_now
  • primetime_today
  • primetime_yesterday
  • event_live_now
  • most_popular
  • purchased
  • expired_rentals
  • rentals

Continue Watching​

Identifier: continue_watching
API: /playlists/user-continue-watching
Authentication: Required

The continue watching playlist will give you all assets that the current profile of the user has watched but has not finished yet.

TODO: add link to user/player/heartbeat events for reference

Recommendations​

Identifier: recommendations
API: /playlists/user-recommmendations
Authentication: Required

The recommendation playlist will give you all assets given by the active recommendation engine for the current profile of the user.

TODO: add link to user/player/heartbeat events for reference

Watch History​

Identifier: watch_history
API: /playlists/watch-history
Authentication: Required

The recommendation playlist will give you all assets given by the active recommendation engine for the current profile of the user.

TODO: add link to user/player/heartbeat events for reference

Because you watched​

Identifier: because_you_watched
API: /playlists/because-you-watched
Authentication: Required

The because you watched will give you a list of recommendations based on your last watched asset.

Asset​

The asset the recommendations are based off will be returned in a property called becauseYouWatchedAsset and it will contain all of it's properties.

The fact that this asset is included in the playlist response does mean that you can only use it in the section title (if you so wish) after retrieving the content.

TODO: add link to user/player/heartbeat events for reference

Favorites​

Identifier: favorite
API: /playlists/user-favorites
Authentication: Required

The favorite playlist will give you all assets that the current profile of the user has favorited.

Identifier: most_popular
API: /playlists/most-popular
Authentication: Not Required

The most popular playlist will give you the items that have been played the most for the timeframe given to the call.

The usage of this playlist is a bit different than most, as additional parameters need to be provided:

  • from a UNIX timestamp dictating from which timestamp to gather most popular items
  • to a UNIX timestamp dictating up until which timestamp to gather most popular items

There are 2 ways you can construct the API URL based on the data in the section object:

_links.href will have a fully constructed URL ready to use. Backstage will interpolate any of the values given by the section and give you the URL you can use to grab the assets.

Parameters​

computedPlaylistParameters is an object that will contain parameters inputted in the CMS. It will contain the following properties:

type
Type can be either relative or date_range, when it's set to relative you will get some textual values that dictate how you need to construct the timestamps. In the case of date_range you will just receive UNIX timestamps to use.

to
In this case of type being relative, to will always be set to %now% which indicates you need to use the current timestamp for the to paramter in the call.

from
In this case of type being relative, the from parameter will contain a reference to how much time you'll need to subtract from the current timestamp. It will contain the amount + a unit, for example: 24h where you'd need to subtract 24 hours from the current timestamp.

Possible units for from are:

  • y - years (will likely never be given)
  • m - months
  • d - days
  • w - weeks
  • h - hours
  • m - minutes
  • s - seconds

It is generally recommended to use the _links.href property to grab the API URL, this will make sure a unified implementation exists across all front-ends and will ensure no edge cases can occur during parsing. You can however use the computedPlaylistParamters if you'd wish to slightly deviate from the Backstage implementation (use at your own risk).

Live Now​

Identifier: live_now
API: /playlists/live-now
Authentication: Not Required

The live now playlist will give you a list of broadcast items (EPG items) that are currently on-air.

Primetime Today​

Identifier: primetime_today
API: /playlists/primetime-today
Authentication: Not Required

The primetime today playlist will give you a list of broadcast items (EPG items) that will be aired during primetime hours (the primetime hours are configurable in the Backstage CMS).

Primetime Yesterday​

Identifier: primetime_yesterday
API: /playlists/primetime-yesterday
Authentication: Not Required

The primetime yesterday playlist will give you a list of broadcast items (EPG items) that aired during primetime hours of the previous day (the primetime hours are configurable in the Backstage CMS).

Live Now - Events​

Identifier: event_live_now
API: playlists/event-live-now
Authentication: Not Required

The event live now playlist will give you a list of live events that are currently on-air

Purchased​

Identifier: purchased
API: playlists/purchased
Authentication: Required

The purchased playlist will give you a list of all assets that have been purchased (permanently) by the current user.

Rentals​

Identifier: rentals
API: playlists/rentals
Authentication: Required

The rentals playlist will give you a list of all assets that have been rented by the current user.

Expired Rentals​

Identifier: expired_rentals
API: playlists/expired-rentals
Authentication: Required

The expired rentals playlist will give you a list of all assets that have been rented by the current user but have since expired.

Last updated on by Tomas1229