...
The client should call the MediaPlaySession based on user activity., as below:
| User action | API calls | Any additional logic to perform | Endpoint |
|---|---|---|---|
| Before the user is able to play media | GET an index of the current sessions | Check that the number of sessions does not equal or exceed the configured system value | Media play sessions#/Media%20Play%20Sessions/indexMediaPlaySession |
| When the user starts to play media | POST to create a new session | Store the id of the media playback session locally | Media play sessions#/Media%20Play%20Sessions/postMediaPlaySession |
| When the user stops playing media | DELETE the session | Use the id that was returned to you in the POST response to identify the resource | Media play sessions#/Media%20Play%20Sessions/deleteMediaPlaySession |
| Periodically | PATCH the session | Media play sessions#/Media%20Play%20Sessions/patchMediaPlaySession |
| Note |
|---|
| The user should not be able to manipulate their playback session count themselves; You should not provide the user with a direct means to access the API but rather call it as a side-effect of other user initiated actions. |
Periodical PATCH calls to the session
The client is expected to periodically PATCH the session to update the "last_updated_timestamp" field to the current unix timestamp.
This is used by the server to determine if a particular session is being actively watched.
Sessions that are not updated will be removed by the server after a set interval. Note that this will not affect playback, the client will still be able to watch the stream even if the MediaPlaybackSession is removed.
Therefore, it is essential that the client calls PATCH in order to prevent the server from incorrectly assuming the session is no longer active.
Example flow
| Description | URL | Number of MediaPlaySessions after call is made | |||
|---|---|---|---|---|---|
| User account is not watching anything | 0 | ||||
| User starts watching something on their set top box | POST /users/{user_id}/media_play_sessions | 1 | |||
| Another person in the household starts watching something on a their mobile | POST /users/{user_id}/media_play_sessions | 2 | |||
| The second user presses stop on their mobile device | 2 | ||||
| The first user switches off the set top box without giving the client a chance to delete their session | None | 2 | The second user presses stop on their mobile device | DELETE /media_play_sessions/{media_play_session_id} | 1 (zombie session) |
| Some time later the periodic clean up job runs on the server and deletes the zombie sessionN/A | 0 |