SSE: Data Broadcasting

The Server Side Events (SSE) feature enables app developers to build more responsive web applications with the ability to receive real-time response data directly from the Console UI. This is achieved through a Server-Sent Event communication, enabling a seamless and immediate data flow from the Console to the web app upon initiating an API request. The native push-based data delivery not only enables faster, real-time frontend experiences but also streamlines infrastructure efficiency.

We’ve enhanced SSE to support these additional features:

To Implement SSE, you need to instantiate the OS1HttpClient from the Console UI. The OS1HttpClient is a wrapper HTTP client provided by the Console UI to make it easier to support all HTTP methods necessary for RESTful API calls. It is a pre-configured instance of Axios that handles authentication, base URLs, and other HTTP client best practices.

The OS1HttpClient takes two arguments:

To enable inter-tab data synchronization, set the interTabCommunicationRequired flag to true, while initializing the console UI. If not set, it defaults to false and each tab will have its own connection, which may result in unsynchronized data.

See the example below:

This section details the integration of Server-Side Events (SSE) using the OS1HttpClient class provided by the Console, allowing for real-time communication from server to client in your application. There are two ways to implement the Server Side Events (SSE) coherent views feature in your application.

For example, to broadcast dispatch updates to all the users who have opened a particular dispatch, the developer can create and subscribe to a topic using the dispatch ID (e.g., dispatch:1234). This subscription should be made when the page loads for the dispatch. Messages can then be sent to this broadcast topic as described below.

Developers can select specific topics to follow by calling the subscribeBroadcastTopic function. Please note that each app has a maximum of 10 topics and 10 subscribers per topic. To maximize the results, it is suggested to create specific topics that reflect the events they represent. This will enable targeted events within the limits while ensuring accuracy. Therefore, it's important to use topic names that accurately reflect the context and stay within the subscriber limits.

To unsubscribe from a topic, call unsubscribeBroadcastTopic.

Example:

Here:

This is the simplest option if using the Console’s Axios client.

When making an API call, developers need to specify the attribute where the broadcast url is expected on the backend. To set the value of this attribute, us the placeholder {{SSE_BROADCAST(topicNames)}}. After setting the attribute, the Console will automatically detect and replace this placeholder with the actual broadcast URL. Developers can pass the callback attribute in the request URL, headers, or the request body.

The example below adds {{SSE_BROADCAST(topicNames)}} to the header for the createVehicles request.

The OS1HttpClient manages the SSE connection and retrieves the callback URL from the server. It replaces the {{SSE_BROADCAST(topicNames)}} placeholder with the broadcast URL needed in the API request. If you need to pass multiple topics, separate them using a comma, like this {{SSE_BROADCAST(topicName1,topicName2)}}. Note that you can only pass up to 5 topics.

Once a callback is received from the server, the Console will emit a custom event, SSECallBackEvent. Your application needs to listen to this event in your UI code and handle the data when the API response is pushed from the server.

If any internal errors occur during the connection setup, the Console will throw an error, and an API call will be made with null as the callback URL. Only non-retriable errors will be thrown to the user.

The following sample code demonstrates the full implementation for using the {{SSE_BROADCAST}} placeholder:

The implementation does the following:

This option works with any HTTP client and is not limited to Console’s Axios client.

Before making an API call, call the broadcastEvents function to broadcast events. This function accepts the topicNames on which events should be broadcasted and the "payload" to be passed. Please refer to the example code below:

Once a callback is received from the server, the Console will emit a custom event, SSECallBackEvent. Your application can listen to this event in your UI code and handle the data when the API response is pushed from the server.

The following example shows how to implement SSE into an application by manually calling the getEventBrokerUrl:

The implementation does the following:

Broadcast Event payload