Configure Session Control
In this article, we will focus on configuring the session control mechanism by establishing a connection with the Simultaneous Session Control server. This module is the core of the Simultaneous Session Control system which is used to manage the number of concurrent sessions per user account.
To manage a seamless integration with the Simultaneous Session Control server, the client application needs to maintain a Websocket connection that allows bidirectional data flow between the application and the Simultaneous Session Control server.
For fully functional integration it is crucial to:
Allow content stream / playback only when connection is established and server responded with Message - OK
Respond to server Message - PING with the Message - PONG to ensure DRISC can keep track of disconnected sessions.
Enable DRISC
Before starting the integration or after completing the integration, you should enable the Simultaneous Session Control functionality in the Cleeng dashboard to complete the Simultaneous Session Control setup. You can find the Simultaneous Session Control settings in the Admin section of the Cleeng dashboard.
Without the Simultaneous Session Control enabled in the dashboard, you will get a 200 "DRISC Disabled" response while trying to create a new session. Refer to Disable DRISC for more details.
Initiating a new session
Creating a new session depends on the broadcasters to define at what moment you want to initiate a session. It could be as soon as the end-user login, or it could be when the end-user wants to stream the paid content.
Once the point of initiation has been decided then during that time, the client application needs to send an HTTP request under the following endpoint: Initiate Session to create a new session using either tag or offerId
. These properties exclude each other.
Note: A tag must exist on a specific offer for a session to be initiated. Please note that tags are case-sensitive.
In addition, this endpoint can be used to receive Session Connection Details, DRISC disabled status, or LimitExceeded error.
The code below is meant to guide you through the process, it’s up to you to ensure needed messages and HTTP requests are being fired in the right moments.
Requesting new session with offerId
In order to create a new session, you need to submit a valid Initiate Session request with Cleeng offerId
and the content title in the sessionName
as below,
Note
Session Name is used to let the end-user know what are the active concurrent sessions in his/her account. Hence it's your choice to pass what information to be available to your end-user. Some examples are operating devices, content titles, custom template names, and so on. To see how the session name looks in the FE application, please refer to the figure here
const token = 'JWT-CleengToken'
const sessionDetails = {
sessionName: 'Peaky Blinders S01E03',
offerId: 'S567921766_NL'
};
const res = await fetch('https://drisc.cleeng.com/sessions', {
method: "POST",
headers: {
Authorization: `Bearer ${token}`
},
body: JSON.stringify(sessionDetails),
});
Requesting new session with tag
Alternatively, you can also create a new session using tags. To do so, you need to submit a valid Initiate Session request with Cleeng offer tags and the content title in the sessionName
as below,
const token = 'JWT-CleengToken'
const sessionDetails = {
sessionName: 'Peaky Blinders S01E03',
tag: 'Drama'
};
const res = await fetch('https://drisc.cleeng.com/sessions', {
method: "POST",
headers: {
Authorization: `Bearer ${token}`
},
body: JSON.stringify(sessionDetails),
});
Handling newly created session
Upon successful initiation of the new session, the Initiate Session endpoint will respond with the following response:
Note
The token and
sessionId
will be generated for each API call!
{
endpoint: "wss://drisc-cleeng.com?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoiNCIsInNlc3Npb25JZCI6IjdhMDUxMDRlLTNlMzktNDY2OC04NDZiLTY5ZjQwNjUzYzhiZCIsImlhdCI6MTYzNTE3MDk0NCwiZXhwIjoxNjM1MzQzNzQ0fQ.UbEHd8jKqutxjJnlFP4NTYdrnM0QE_qdya-aL08h_6I"
sessionId: "7a05104e-3e39-4668-846b-69f40653c8bd"
}
As per the technical requirement, we believe that you have already constructed the Websocket client. This client will be used to exchange messages from the client application to the Simultaneous Session Control server and vice versa.
The client application must ensure the connection is always open so that the Simultaneous Session Control server can ping all sessions that are alive. Once the session is created WebSocket client needs to send Message - REQUESTED to the received WebsocketEndpoint
It is optional to persist WebsocketEndpoint for example using LocalStorage or SessionStorage in order to be able to reconnect in case of network failure.
Below you can find an example updated with Websocket client logic:
// ... create session API call
const data = await res.json();
if (res.status === 200) {
if (data?.status === "disabled") {
// start content stream as if new session was created
}
if (data?.endpoint) {
websocketEndpoint = data.endpoint;
sessionStorage.setItem("CLEENG_WEBSOCKET_ENDPOINT", websocketEndpoint)
// here we construct websocket client used to communicate with DRISC
websocketClient = new WebSocket(websocketEndpoint);
websocketClient.addEventListener("open", () => {
websocketClient.send(JSON.stringify({action: 'REQUESTED'}))
});
}
}
Handling Websocket messages
Once you establish a WebSocket connection with the Simultaneous Session Control server, you need to support the following messages to ensure the Simultaneous Session Control mechanism can determine which sessions are alive exchange communication.
websocketClient.addEventListener("message", (data) => {
const message = JSON.parse(data.data);
switch (message.action) {
case 'TERMINATE':
// Stop playback
break;
case 'OK':
// grant access to resource
break;
case 'PING':
// respond with PONG message
break;
case 'TAKE_OVER':
// Display takeover message in UI
break;
case 'EXPIRED':
// request new session from https://drisc.cleeng.com/sessions
// (Optionally) clear cached websocketEndpoint
break;
default:
// display generic error (in case of for example ServerError)
console.warn(`Unhandled message ${JSON.stringify(message)}`);
}
});
Session Limit Exceeded
If the session limit is exceeded, then Initiate Session endpoint will return the following response:
{
statusCode: 409,
error: "SessionLimitExceededError"
message: "Sessions limit exceeded"
details: {
activeSessions: [
{
name: string;
sessionId: string;
}
]
offerUpgradeAvailable: boolean
takeOverEnabled: boolean
takeOverOnlyWhenUpgradeNotAvailable: boolean
}
}
It allows the client application to display corresponding notifications on User Interface. Use this message to show the error message as displayed below.
If you are not using takeover, then tailor your error message accordingly.
Ending the session
Once the end-user has stopped streaming the content, the client application should send Message - FINISHED and clear persisted WebSocketEndpoint as well as stop maintaining Websocket client open state (in our example stop interval).
If the connection is broken before Message - FINISHED is sent, Simultaneous Session Control mechanism will be able to find out which session is not alive by sending Message - PING
So far we have covered all aspects of configuring session control mechanisms. We went through the REST endpoint that is required to be called together with WebSocket messages. Further, continue the documentation for the Takeover tutorial.
Updated about 2 years ago