WebSocket API

WebSocket Powered Widget Development

The WebSocket API within Cinema8's widget development environment allows you to create real-time communication and collaboration tools for interactive videos. By using WebSockets, you can build interactive widgets that update in real time.

Creating a WebSocket Instance

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

The persistent option determines whether the data transmitted over the WebSocket is persistent.

Handling WebSocket Events

The WebSocket instance includes several event handlers for managing different events during the connection:

onOpen

The onOpen event is triggered when a WebSocket connection is opened.

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

onMessage

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

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

onActiveConnectionsChange

The onActiveConnectionsChange event occurs when the number of active WebSocket connections changes.

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

onClose

The onClose event is triggered when a WebSocket connection is closed.

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

onError

The onError event is triggered when a WebSocket connection closes due to an error.

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

Publishing Data

To publish data over the WebSocket, 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 interaction with WebSocket-based widgets in Cinema8. Here are some functions:

WebSocket Search

The search function allows querying persisted WebSocket data using a query object. Example:

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

Each query option has specific properties like sortField for sorting, offset to skip results, and filters for data filtering. The groupBy option groups results by a specified field (e.g., "data.liked").

WebSocket Data Model

Each widget within a project has a unique data model with:

• client_id: Unique ID for the widget instance.
• created: Creation date.
• id: Inner ID of published data.
• data: Custom data model used in the widget.
• username: Automatically populated with the authenticated user's username if applicable.

Overall, the WebSocket API functions allow users to build real-time communication and collaboration tools for Cinema8-based applications.