Server Event APIs

Server Events is a capability of the Quantum Fabric run-time server that lets the back-end services generate and subscribe to events. Server Events are used to receive events asynchronously when the client app does not need to wait for a response. For example, processing a submitted order or invoking an activity that takes a long time.

Prerequisites

Enable the Server Event APIs on Visualizer. To enable the APIs, follow these steps:

1. From the left navigation bar of Visualizer, select Project Settings.
2. On the Project Settings window, in the Application section, select Enable Server Events APIs.

The following global callbacks are mandatory in the setServerEventsCallbacks API:

• onEventCallback
• onFailureCallback

setServerEventsCallbacks API

The setServerEventsCallbacks API sets the common callback for the Server Events API. The common callbacks are onEventCallback, onFailureCallback, and onCloseCallback.

IMPORTANT: Make sure this API is called once per application life cycle as the callbacks are common, and re-assigning can override the existing defined callbacks. Even if the connection is closed, the callbacks remain in the assigned application life cycle.

Syntax

KNYMobileFabric.setServerEventsCallbacks(options);

Parameters

Parameter	Type	Description
setupOptions	JSON	This parameter contains the following options: onEventCallback (Mandatory): Invoked when the server returns the response for a triggered event and whenever the connection is established for the first time, that is onOpen. onFailureCallback (Mandatory): Invoked when the server returns an error response. onCloseCallback (Optional): Invoked when the WebSocket connection is closed.

Sample Code

setupOptions =
{
	"onEventCallback": function(message)
	{
		//Handle the server event notification
	},

	"onFailureCallback": function(error)
	{
		//Handle the error that occurred
	},

	"onCloseCallback": function(message)
	{
		//Handle the closure of the connection
	}
};
KNYMobileFabric.setServerEventsCallbacks(setupOptions);

 

subscribeServerEvents API

The subscribeServerEvents API opens the WebSocket connection for the first time and sends a subscription message for the specified topics. After subscribing to the topics, the application starts receiving the relevant Server Events messages.

Syntax

KNYMobileFabric.subscribeServerEvents(topicsToSubscribe, subscribeOptions);

Parameters

Parameter	Type	Description
topicsToSubscribe	String/Array of Strings	Specifies the topics to be subscribed.
subscribeOptions	JSON	This parameter contains the following options: subscribeMode: Specifies the type of subscription. The default value is Private. The Public mode is not supported for client-server communication. onSubscribeCallback: A local callback that is invoked when the server sends a response for the subscription. Specifies whether the connection was successful, and also contains a list of events that were subscribed. The onSubscribeCallback is local to the subscribeServerEvents API. If a Network or Server error occurs during subscription, the error is sent to the global onFailureCallback function. As no events are subscribed due to the error, the onSubscribeCallback contains a No events subscribed message. If a partial subscription occurs, the subscribed events are listed in the onSubscribeCallback function.

Sample Code

var topicsToSubscribe = ["service1/operation1", "service1/operation2", "service2/operation1"];

subscribeOptions =
{
	onSubscribeCallback: function(message)
	{
		//Handle the response from the server
	}
};

KNYMobileFabric.subscribeServerEvents(topicsToSubscribe, subscribeOptions);

unsubscribeServerEvents API

The unsubscribeServerEvents API is used to unsubscribe from the Server Events messages for the specified topics.

NOTE: If the closeConnection option is passed as true along with events to be unsubscribed, the WebSocket internally closes the connection as all the topics from the server are unsubscribed automatically.

Syntax

KNYMobileFabric.unsubscribeServerEvents(topicsToUnsubscribe, unsubscribeOptions);

Parameters

Parameter	Type	Description
topicsToUnsubscribe	String/Array of Strings	Specifies the topics to be unsubscribed.
unsubscribeOptions	JSON	This parameter must contain the following options: unSubscribeMode: Specifies the type of subscription. The default value is Private. The Public mode is not supported for client-server communication. closeConnection: Specifies whether the existing connection must be closed. The default value of this property is false. To close the existing connection, this property must be true. If the connection is closed successfully, the response is sent to the global onCloseCallback function. onUnsubscribeCallback: A local callback that is invoked when the server sends a response for the removal of subscriptions. Specifies all the events that have been unsubscribed. The onUnsubscribeCallback is local to the unsubscribeServerEvents API. If the closeConnection flag is true, the onUnsubscribeCallback is not invoked, and the server response is sent to the global onCloseCallback function. If a Network or Server error occurs during the removal of subscriptions, the error is sent to the global onFailureCallback function. As no events are unsubscribed due to the error, the onUnsubscribeCallback contains a No events unsubscribed message. If a partial unsubscribe occurs, the unsubscribed events are listed in the onUnsubscribeCallback function.

Sample Code

var topicsToUnsubscribe = ["service1/operation1", "service1/operation2", "service2/operation1"];
 
 unsubscribeOptions =
 {
 	"closeConnection": true, //The default value is false. To close the existing connection, this property must be true
 
 	"onUnsubscribeCallback": function(message)
 	{
 		//Handle the response from the server
 	}
 };
 
 KNYMobileFabric.unsubscribeServerEvents(topicsToUnsubscribe, unsubscribeOptions);

Reference: Response Codes

Response Code	Response
6201	Subscribe Success
6202	Subscribe Error
6203	Subscribe Partial Success
6207	Unsubscribe Success
6208	Unsubscribe Error
6209	Unsubscribe Partial Success
6210	On Event
7200	On Open
7201	On Error
7202	On Close

Notes and Expected Behaviors:

• SSL pinning Support for Server Events:

  From the V9 ServicePack 5 release, SSL Pinning is supported for the Android and iOS channels.

  For more information about SSL Pinning, refer to the following documents:

  • Apply Application Security
  • Certificate Pinning
  • Public Key Pinning
• Background behaviors:
  • Android: WebSocket connection is active max for 5 mins or until the OS does not kill the connection/app in the background.

    To enable usage of WebSocket in the background, use Foreground Service and Location services with background location services enabled (Location Always) to keep the app active in the background.

  • iOS: WebSocket connection is active max for 5 mins or until the OS does not kill the connection/app in the background.

    To enable usage of WebSocket in the background, use Background Mode with Location service which will further increase the background time for the WebSocket connection for 10 mins.

  NOTE: The WebSocket connection gets paused whenever the application is sent to the background, this is due to iOS OS limitation. After the app comes to foreground and if the app is not killed by the OS, relevant data would be received by the application.

• Network failures: When network connectivity goes OFF and WebSocket is still running.

  Platforms	Android	iOS	SPA
  			Chrome	Firefox	Safari	Edge	IE
  Expected Behaviors	Failure callback followed by Close callback.	Failure callback.	Failure callback.	Failure callback followed by Close callback.	Failure callback followed by Close callback.	Failure callback.	Failure callback followed by Close callback.

  NOTE: For network connectivity related issues, Re-Subscribing to the existing topics will establish the connection again if closed internally.

Frequently Asked Questions

• Can I subscribe to a topic more than once?

  Yes, you can subscribe to events for a topic multiple times. The events will be notified each time an application has subscribed to that topic.

• Can I unsubscribe from a partial list of topics?

  Yes, you can unsubscribe from a partial list of topics.

• Can I use different callbacks for every subscription?

  Currently, the API maintains only one callback and the events for all topics will be notified through the same callback. When a different callback is passed with another subscription, all the events will start invoking the latest callback provided in the subscription.

Limitations

• There is no support to reconnect to a topic if a connection fails or if the client app crashes. Therefore, the app will not receive notifications when an event is invoked.
• If the connection fails or if the app crashes, you need to use the subscribeServerEvents API to establish a connection with the WebSocket. Make sure that you call the API when the app is re-launched.