Registry / messaging / cordova-plugin-websocket

cordova-plugin-websocket

JSON →
library0.12.2jsnpmunverified

Cordova plugin that provides WebSocket (RFC6455) support for Android versions prior to 4.4 (KitKat) and Crosswalk environments where native WebSocket may be absent. Stable version 0.12.2, last updated in 2016. Based on Jetty 8, it implements both text and binary messages (binary requires API >= 14). Unlike alternative WebSocket plugins for Cordova, this one is specifically designed for older Android devices and is not used on Android 4.4+ by default. It requires cordova-android 3.6.0+ and a whitelist plugin for cordova-android 4.0.0+.

messaging
npm install cordova-plugin-websocket
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · CORDOVA-PLUGIN-WEB
C
cordova-plugin-websocket
messagingjavascriptv0.12.2
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

WebSocket
✓ // No import needed; global 'WebSocket' constructor is provided by the plugin after deviceready
The plugin patches the global WebSocket constructor upon deviceready. Use it directly without import.
WebSocket
✓ if (typeof WebSocket !== 'undefined') { var ws = new WebSocket('ws://example.com'); }
✗ var ws = new WebSocket('ws://example.com'); // This may fail if native WebSocket exists
Always check for native WebSocket availability before using this plugin's implementation.
WebSocket
✓ var ws = new WebSocket('ws://example.com', ['protocol1']);
✗ var ws = WebSocket('ws://example.com'); // Missing 'new' keyword
Must use 'new' operator. Protocols argument is optional.

Demonstrates how to use the plugin's WebSocket constructor after device ready, including event handlers and conditional check for native WebSocket.

document.addEventListener('deviceready', function () { // Ensure the plugin's WebSocket is used (Android < 4.4) if (typeof WebSocket !== 'undefined') { var ws = new WebSocket('wss://echo.websocket.org'); ws.onopen = function () { console.log('WebSocket opened'); ws.send('Hello via plugin!'); }; ws.onmessage = function (event) { console.log('Received: ' + event.data); ws.close(); }; ws.onerror = function (error) { console.error('WebSocket error: ' + error); }; ws.onclose = function (event) { console.log('WebSocket closed'); }; } else { console.log('Native WebSocket is available, plugin not used.'); } }, false);
Debug
Known issues
gotchaPlugin does not work on Android 4.4+ (KitKat) by default; native WebSocket takes precedence.
fix
Not required; native WebSocket is supported on those versions.
affects: >=0.0.0
gotchaINTERNET permission is added/removed automatically; removing plugin may remove permission needed by other plugins.
fix
Manually add INTERNET permission to AndroidManifest.xml if needed after removal.
affects: >=0.0.0
deprecatedPlugin uses Jetty 8, which is outdated and may have security vulnerabilities.
fix
Upgrade to a more modern WebSocket solution or target Android 4.4+.
affects: >=0.0.0
gotchaBinary messages are not supported on Android 2.3.x (API 10).
fix
Supports only text messages on API 10. Check Android version at runtime.
affects: >=0.0.0
gotchaWSS protocol supports only TLS, not SSL.
fix
Ensure server uses TLS (not SSL) for secure WebSocket connections.
affects: >=0.0.0
Errors
Common errors & fixes
Error: Cannot find module 'cordova-plugin-websocket'
Plugin not installed or not properly added to project.
fix
Run 'cordova plugin add cordova-plugin-websocket' and rebuild.
java.lang.ClassNotFoundException: Did not find class 'org.eclipse.jetty.websocket.WebSocketClient'
Missing dependency or corrupted plugin installation.
fix
Remove and reinstall the plugin: 'cordova plugin rm cordova-plugin-websocket && cordova plugin add cordova-plugin-websocket'
Refused to connect to 'ws://...' because it violates the document's Content Security Policy.
CSP connect-src directive missing for WebSocket URL.
fix
Add 'connect-src ws://example.com wss://example.com' to the CSP meta tag in index.html.
TypeError: WebSocket is not a constructor (evaluating 'new WebSocket(...)')
Plugin not loaded or native WebSocket does not exist, but WebSocket is undefined.
fix
Ensure code runs after deviceready event. Check if plugin is installed correctly.
Upgrade
Version history
0.12.2latest on npm
Audit
Dependencies
cordova-plugin-whitelistoptionalRequired for cordova-android 4.0.0+ to allow WebSocket connections through CSP
Agent activity
36 hits · last 30 days
node
34
OpenAI (training)
1
Resources
githubhttps://github.com/knowledgecode/WebSocket-for-Android ↗
packagecordova-plugin-websocket ↗
homepagehttps://github.com/knowledgecode/WebSocket-for-Android#readme ↗
cordova-plugin-websocket — npm install cordova-plugin-websocket · libregistry