Configure Session Control

In this article, we will focus on configuring the session control mechanism by establishing a connection with the DRISC server. This module is the core of the DRISC system which is used to manage the number of concurrent sessions per user account.

To manage a seamless integration with the DRISC server, the client application needs to maintain a Websocket connection that allows bidirectional data flow between the application and DRISC 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 DRISC functionality in the Cleeng dashboard to complete the DRISC setup. You can find the DRISC settings in the Admin section of the Cleeng dashboard.

Without the DRISC 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.

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. In case of any doubt please contact our BSS team.

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 DRISC server and vice versa.

The client application must ensure the connection is always open so that DRISC 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 DRISC, you need to support the following messages to ensure DRISC 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.

Session Limit ExceededSession Limit Exceeded

Session Limit Exceeded

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, DRISC 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.


What’s Next
Did this page help you?