Cordova Plugin for using WebSockets

WebSocket plugin that supports custom headers, self-signed certificates, periodical sending of pings (ping-pong to keep connection alive and detect sudden connection loss when no closing frame is received).

Supported Platforms

• Android (uses OkHttp as underlaying library)
• iOS (uses SocketRocket as underlaying library)
• Browser (uses WebSocket Web API as underlaying library)

Android

OkHttp library is included as maven dependency with version 3.10.0

iOS

SocketRocket is included as CocoaPod library with version 0.5.1

To use it, you will need to install CocoaPods on your Mac:

sudo gem install cocoapods
pod setup --verbose

Installing

Cordova

$ cordova plugin add cordova-plugin-advanced-websocket-hostname-verifier

API

Methods

• CordovaWebsocketPlugin.wsConnect
• CordovaWebsocketPlugin.wsSend
• CordovaWebsocketPlugin.wsClose

wsConnect

Connecto to WebSocket using options

CordovaWebsocketPlugin.wsConnect(options, receiveCallback, successCallback, failureCallback);

Parameters

• options: Object containing WebSocket url and other properties needed for opening WebSocket:
  • url: string; Url of WebSocket you want to connect to. This is the only mandatory property in options.
  • timeout?: number; Request timeout in milliseconds. (optional, defaults to 0)
  • pingInterval?: number; Ping interval in milliseconds if you want to keep WebSocket open and detect automatically dead WebSocket when Pongs stop returning. If you set it to 0, Pings won't be sent. (optional, defaults to 0. iOS/Android only)
  • headers?: object; Object containing custom request headers you want to send when opening WebSocket. Object keys are used as Header names, and values are used as Header values. (optional. iOS/Android only)
  • acceptAllCerts?: boolean; Set this to true if you are using secure version of WebSocket (url starts with "wss://") and you want to accept all certificates regardles of their validity. Useful when your WebSocket is using self-signed certificates. (optional, defaults to false. iOS/Android only)
• receiveCallback: Receive callback function that is invoked with every message received through WebSocket and also when WebSocket is closed.
• successCallback: Success callback function that is invoked with successfull connect to WebSocket.
• failureCallback: Error callback function, invoked when connecting to WebSocket failed for whatever reason.

Callbacks

All three callback functions will get one object containing property webSocketId and some other properties depending on callback. successCallback and failureCallback callbacks will also get properties code and reason. Those two callback methods will be called only once and just one of them will be called depending on success of the outcome.

receiveCallback callback will be called multiple times during lifetime of the WebSocket. It will get object that will, appart from webSocketID property, contain also property callbackMethod so we know what type of callback is received from plugin. Possible values for callbackMethod are: onMessage, onClose, onFail. If callbackMethod has value onMessage you will also get property message which is the actual received message. If callbackMethod has value onClose you will get properties code and reason or exception. If callbackMethod has value onFail you will get properties code and exception.

webSocketId is unique reference to your WebSocket which is needed for later calls to wsSend and wsClose.

Quick Example

var accessToken = "abcdefghiklmnopqrstuvwxyz";
var wsOptions = {
    url: "wss://echo.websocket.org",
    timeout: 5000,
    pingInterval: 10000,
    headers: {"Authorization": "Bearer " + accessToken},
    acceptAllCerts: false
}

CordovaWebsocketPlugin.wsConnect(wsOptions,
                function(recvEvent) {
                    console.log("Received callback from WebSocket: "+recvEvent["callbackMethod"]);
                },
                function(success) {
                    console.log("Connected to WebSocket with id: " + success.webSocketId);
                },
                function(error) {
                    console.log("Failed to connect to WebSocket: "+
                                "code: "+error["code"]+
                                ", reason: "+error["reason"]+
                                ", exception: "+error["exception"]);
                }
            );

wsSend

Send message to WebSocket using webSocketId as a reference.

CordovaWebsocketPlugin.wsSend(webSocketId, message);

Parameters

• webSocketId: Unique reference of your WebSocket.
• message: Message that you want to send as a string.

Quick Example

CordovaWebsocketPlugin.wsSend(webSocketId, "Hello World!");

wsClose

Close WebSocket using webSocketId as a reference, specifying closing code and reason.

CordovaWebsocketPlugin.wsClose(webSocketId, code, reason);

Parameters

• webSocketId: Unique reference of your WebSocket.
• code: WebSocket closing code, see RFC6455. (optional, defaults to 1000)
• reason: WebSocket closing reason. (optional)

Quick Example

CordovaWebsocketPlugin.wsClose(webSocketId, 1000, "I'm done!");