WebSocket for Android is a Cordova/PhoneGap plugin that allows WebSockets (RFC 6455) to be used on Android.
This is using Jetty 8 under the terms of the Apache License v2.0.
- Java 1.6 or higher
- Android 2.2 or higher (recommended 4.0 or higher)
- Cordova/PhoneGap 3.0.0 or higher
The version for Cordova/Phonegap 2.x, see here.
version | WS protocol | WSS protocol | text message | binary message |
---|---|---|---|---|
2.2 (API 8) | ✓ | ✓ | ||
2.3.3 (API 10) | ✓ | ✓ | ✓ | |
4.0 (API 14) | ✓ | ✓ | ✓ | ✓ |
4.0.3 (API 15) | ✓ | ✓ | ✓ | ✓ |
4.1.2 (API 16) | ✓ | ✓ | ✓ | ✓ |
4.2.2 (API 17) | ✓ | ✓ | ✓ | ✓ |
4.3.1 (API 18) | ✓ | ✓ | ✓ | ✓ |
4.4.2 (API 19) | ✓ | ✓ | ✓ | ✓ |
- The WSS protocol is now available on 2.3 or higher (SSLv3 is not supported. TLS only.).
- 3.x devices are not supported (maybe work, but not tested).
- The WebView has officially supported WebSockets since 4.4 (KitKat). Therefore this plugin is not used on those devices by default.
Use the Cordova/PhoneGap Command-Line interface:
$ cordova plugin add https://github.com/knowledgecode/WebSocket-for-Android.git
or
$ phonegap plugin add https://github.com/knowledgecode/WebSocket-for-Android.git
This plugin is for Android. However if install this via the CLI, it also affects all other platforms (such as iOS). This is a specification.
In fact, it writes only an installation history in those platforms. (There are no tangible ill effects.)
If you mind this thing, recommended to use Cordova Plugman that can specify an installation platform. Execute this on a project root:
$ plugman install --platform android --project platforms/android --plugin https://github.com/knowledgecode/WebSocket-for-Android.git --plugins_dir plugins
Just remove and reinstall.
$ cordova plugin remove com.knowledgecode.cordova.websocket
$ cordova plugin add https://github.com/knowledgecode/WebSocket-for-Android.git
or
$ phonegap plugin remove com.knowledgecode.cordova.websocket
$ phonegap plugin add https://github.com/knowledgecode/WebSocket-for-Android.git
in the case of Plugman:
$ plugman uninstall --platform android --project platforms/android --plugin com.knowledgecode.cordova.websocket --plugins_dir plugins
$ plugman install --platform android --project platforms/android --plugin https://github.com/knowledgecode/WebSocket-for-Android.git --plugins_dir plugins
Try to delete all files (cache) in platforms/android/ant-build/.
When install this plugin, it adds INTERNET
permission to AndroidManifest.xml
. If remove this plugin, the permission is also removed at the same time even if it is required for other plugins.
The WebSocket(url, protocols) constructor takes one or two arguments. The first argument, url, specifies the URL to which to connect. The second, protocols, is either a string or an array of strings.
A simple code is as follows:
document.addEventListener('deviceready', function () {
var ws = new WebSocket('ws://echo.websocket.org');
ws.onopen = function () {
console.log('open');
this.send('hello'); // transmit "hello" after connecting
};
ws.onmessage = function (event) {
console.log(event.data); // will be "hello"
this.close();
};
ws.onerror = function () {
console.log('error occurred!');
};
ws.onclose = function (event) {
console.log('close code=' + event.code);
};
}, false);
This plugin has the following options. All these parameters are omissible. Of course these don't affect the native WebSocket.
key | default value | remarks |
---|---|---|
origin | (empty) | |
maxConnectTime | 75000 | |
override | false | since v0.8.0 |
The origin
is a value to set the request header field.
The maxConnectTime
is time to wait for connection. The default value will be 75,000 milliseconds if omit it.
The override
is a flag to override the native WebSocket on 4.4 or higher devices. The default value will be false if omit it. Set to true if you want to enable the plugin WebSocket even though those support WebSockets.
If you want to change these parameters, need to do before creating a instance:
WebSocket.pluginOptions = {
origin: 'http://example.com',
maxConnectTime: 5000,
override: true
};
var ws = new WebSocket('ws://echo.websocket.org');
Transmits data to the server over the WebSocket connection. The data takes a string, a blob, or an arraybuffer.
The size of messages that can transmit and receive at a time depends on the heap memory on devices. You would be better to consider a way to split messages if those are large (hundreds of kilobytes).
Closes the WebSocket connection or connection attempt, if any.
- performance tuning (about 5% to 15% faster than previous versions)
- deployed the sources of Jetty directly (instead the jar file)
- abolished the maxTextMessageSize/maxBinaryMessageSize options
- added the "override" option
- refactoring
- resolved the issue of SSL on 4.0 and 2.3 (thanks to @agalazis and koush/AndroidAsync)
- fixed a bug of a receiving binary size
- limit installation target to Android (thanks to @peli44)
- updated Jetty WebSocket library
- added escaping of special characters (thanks to @odbol)
- cookie support (thanks to @ericfong)
- removed a second argument from the send() method
- clobbered buggy websockets on 4.3 or lower (thanks to @rpastorvargas and @punj)
- bug fix
- bug fix
- change the way to set plugin options
- multiple subprotocol support
- readyState property support (thanks to @jrpereirajr)
- Cordova/Phonegap 3 support
- binary support
- event listener support
- more compliant with the WebSocket API requirements
- license change from MIT to Apache v2.0
- bug fix
- bug fix
- origin support (thanks to @rgillan)
- comply with the WebSocket API requirements
- first release
This plugin is available under the terms of the Apache License Version 2.0.