...
| Code Block | ||||
|---|---|---|---|---|
| ||||
{
"data": [
{
"type": "MediaPlaySession",
"id": "6b6bf3e1-555b-45cb-b5d3-63a2ff7be9e3 ",
"attributes": {
"service": "live",
"ip4_address": "86.190.137.158",
"userdevice_agenttype": "Set Top Boxstb",
"play_started_timestamp": 1551091684,
"last_updated_timestamp": 1551091736
}
}
]
} |
Note that the IP address is not sufficient to identify a session; A person watching on the STB at home may have the same IP address as somebody watching on their mobile phone upstairs on the same home router Wi-Fi network.
Authentication
Calls to the API must be authenticated by passing your access token in the HTTP headers.
We accept this as a bearer token in the Authorization header.
Managing sessions
The client should call the MediaPlaySession based on user activity, as below:
...
| 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. |
Device type and limits
The limit is applied per device type, meaning the user is allowed a set number of MediaPlaySessions per device type. If the limit needs to apply across different types of devices, then all clients sharing a limit should use the same value for device_type with this API.
Showing a list of playback sessions
...
Creating a new session
The client should could retrieve an index of the current sessions so that it is able to tell the user whether she can start a new stream or not.
...
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"id": 56071904,
"code": "df1e80a",
"title": "Too many sessions",
"details": "You have tried to open a new playback session but you are already at the maximum allowable limit. You need to stop playing content on another device in order to watch on this one."
} |
| Note |
|---|
Clients should allow streaming on any other response code that "403 Forbidden". This strategy will make the component non-critical and prevent outages in case of e.g. storage failures. |
Periodical PATCH calls to the session
...
| 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 |
| Each device periodically tells the server that the session is still active | PATCH /users/{user_id}/media_play_sessions/{media_play_session_id} | 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 | DELETE /users/{user_id}/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 session | 0 |