WebSocket powered widget development

The WebSocket api  within Cinema8 widget development environment  allows you to create real-time communication and collaboration tools for your interactive videos. By leveraging websockets, you can create interactive widgets that update in real-time.

Creating a WebSocket Instance

To create a new WebSocket instance, you can use the following code:

 
var socket = new c8PlayerApi.webSocket({
  persistent: true
});

The persistent option determines whether the data transmitted over the websocket is persistent or not.

Handling WebSocket Events

The WebSocket instance has several event handlers that you can use to handle different events that occur during the websocket connection. Here are the available event handlers:

onOpen

The onOpen event is fired when a connection with a WebSocket is opened.

 
socket.onOpen = function(){
    console.log("Socket Con. Open!");
}

onMessage

The onMessage event is fired when data is received through a WebSocket.

 
socket.onMessage = function(message){
    console.log(message.data)
}

onActiveConnectionsChange

The onActiveConnectionsChange event is fired when the number of active websocket connections changes.

socket.onActiveConnectionsChange = function(message){
    console.log(message.data)
}

onClose

The onClose event is fired when a connection with a WebSocket is closed.

 
socket.onClose = function(){
    console.log("Socket Con. Closed!")
}

onError

The onError event is fired when a connection with a WebSocket has been closed due to an error.

 
socket.onError = function(err){
    console.log("Socket Con. Error!", err)
}

Publishing Data

To publish data over the WebSocket, you can use the publish function.

 
socket.publish({
  msg: "Hi",
  user: "John",
});

Closing the WebSocket

The WebSocket should be closed in the widgetDestroy event.

 
c8PlayerApi.on("widgetDestroy", function(){
    socket.close();
});

WebSocket API Functions

The WebSocket API functions allow you to interact with the WebSocket-based widgets created within Cinema8. Here are the available API functions:

WebSocket Search

The search function allows you to search the persisted WebSocket data using a query object. Here's an example:

 
var queryFilter = {
  "sortField": "created",
  "sortOrder": "asc",
  "offset": 0,
  "limit": 10,
  "filters":[
    {
      "field": "created",
      "operator": ">",
      "value": 1678724096803
    },
    {
      "field": "data.score",
      "operator": ">",
      "value": 55
    }
  ]
};


socket.search({
  query: queryFilter,
  success: function( res ){
    console.log(res)        
  },
  error: function(error) {
    console.log(error)
  }
});

Here are the available query options for the queryFilter object:

• sortField: The field to sort the results by (e.g. "created" or "data.xxx")
• sortOrder: The order to sort the results by ("asc" or "desc")
• offset: The number of results to skip before returning data
• limit: The maximum number of results to return
• filters: An array of filter objects to apply to the query

Each filter object has the following properties

 

• field: The field to filter on (e.g. "created" or "data.xxx")
• operator: The comparison operator to use ("greater than", "less than", "equal to", etc.)
• value: The value to compare against.

You can also use the groupBy option to group the results by a specific field (e.g. "data.liked").

WebSocket Data Model

Every widget within a specific project has its own data model with a unique ID.

​

The Data model consists ;

• client_id: Unique ID for the widget instance.
• created: Create date.
• id: Inner ID of published data.
• data: Custom data model used in the widget.
• username: If the video has any authentication implementation, the API automatically injects the authenticated user's username into this field.

Overall, the WebSocket API functions allow you to interact with and retrieve data from WebSocket-based widgets within Cinema8. By leveraging these functions, you can create powerful real-time communication and collaboration tools for your website or application.