WebSocket API

WebSocket API

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:


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

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


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

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


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

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


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

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


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:

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.

    • Related Articles

    • REST API

      This section explains the basics of how to use the Cinema8 Rest API. Before You Begin You can access Cinema8 Rest API documentation and postman collection from this link. In order to access the rest services, you must create an API Key, you can ...
    • Javascript API

      We will explain the basics of how to use the Cinema8 Player JavaScript API component of Cinema8 Player. It uses the same interface for HTML5 video player API and extends it with advanced features. Download js from cdn Download Cinema8 Player ...
    • Widget API

      Widgets are key expansion points of any cinema8 interactive video. While You can use any widget from the widget library you can also develop your own customized widgets with the C8 Widget Development environment. This article  walks you through the  ...
    • Private Token API

      You can create private access URLs for private videos, you can define time-restricted access rights to your videos. You can also track users in reports and analytics screens with the private access link's 'referenceName' you defined. You can create ...
    • Generating API key for integrations

      Get an API Key New Users: Before you can start using the Cinema8 Platform APIs and SDKs, you must sign up and create a billing account. To learn more, see Get Started with Cinema8 Platform . Cinema8 supports OAuth specification to authorize API ...