SSE: Data Synchronization
NOTE
This feature is only available for web apps that integrate with Console.
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:
When multiple tabs are opened for an app on one browser, Server-Sent Events can facilitate sharing a single connection for pushing data updates to each open tab, keeping their application state consistent. Rather than separate connections per tab, developers can enable inter-tab communication. Hence, all tabs process updates from a shared connection upon events instead of needing explicit coordination logic, allowing tabs to remain in sync.
Supported Browsers
The feature is expected to work fine while using Chrome, Firefox, Microsoft Edge, and Safari.
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:
- The first is props.console.authInitializer, which contains the authentication context or initialization parameters necessary for the client to make authenticated requests.
- The second argument is the process.env.BASE_URL is for the API endpoints that the application will communicate with.
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.
- Developers must set the interTabCommunicationRequired flag to true for their app
- They need to subscribe to the topic(s) they want to listen to for broadcasted messages.
- The maximum number of topics that can be broadcast at a time is five.
- We allow the following alphanumeric characters:
- Hyphen (-)
- Underscore (_)
- Colon (:)
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:
- The httpClient is an instance of os1HttpClient, that is instantiated above.
- The only argument that this function accepts is the array of strings.
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:
- Imports and instantiates the OS1HttpClient.
- Makes an API call with the {{SSE_Broadcast()}} placeholder.
- Console will swap the placeholder with the actual broadcast URL.
- Each tab will check whether it has been subscribed to that topic or not.
- If subscribed then it will listen for the SSECallbackEvent callback.
- The event data contains the response payload.
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:
- Imports and instantiates HTTP client.
- Calls the broadCastEvent for broadcasting response.
- Listens for SSECallbackEvent.
Broadcast Event payload
- If a user has subscribed to certain topics but their SSE connection is interrupted due to network issues, the browser will automatically try to re-establish the connection once the network is back. If the user is re-connected within 10 seconds, they will be re-subscribed to their chosen topics. However, if the reconnection takes longer than 10 seconds, the subscription will be lost.
- Each topic can have up to 10 subscribers.
- Each user can subscribe to 10 topics per application.
- Broadcasted message events are only raised on tabs that subscribed to that topic.