...
| 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
The client can call the GET method on the resource index to obtain a list of sessions that are currently registered.
This may be useful if the user has been denied starting a new playback session and wants to know which devices are currently watching.
| Tip |
|---|
| It is not possible for Amino to terminate a media playback session and the user will need to stop playback on the device. |
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.
...
When the client calls the API to create a new session the server will check the number of sessions that already exist.
The server will respond with the details of the session that has been opened. The client should store the id of the entity so that it can make future calls that reference it.
If the account is not allowed to play another stream then the API will respond with a "403 Forbidden" error, with a body as below:
| 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
...
Therefore, it is essential that the client calls PATCH in order to prevent the server from incorrectly assuming the session is no longer active.
Deleting a session when the user stops watching
The client is expected to call the DELETE method on the resource when the user stops watching the media.
We expect that clients will not give users the ability to delete a session without stopping playback.
We realize that it is not always possible for the client to call this endpoint; For example the client could switch off the device or there could be a physical failure in the network.
The server will regularly check for sessions that have not been updated and delete them automatically.
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 |
| 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 |