{"id":22296447,"url":"https://github.com/knowledgecode/websocket-for-android","last_synced_at":"2025-04-30T21:23:05.589Z","repository":{"id":6783891,"uuid":"8031099","full_name":"knowledgecode/WebSocket-for-Android","owner":"knowledgecode","description":"Cordova/PhoneGap plugin that makes WebSocket available on Android","archived":false,"fork":false,"pushed_at":"2017-01-27T15:10:16.000Z","size":2712,"stargazers_count":144,"open_issues_count":2,"forks_count":52,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-04-17T02:49:28.063Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/knowledgecode.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-02-05T14:54:42.000Z","updated_at":"2025-02-18T02:48:37.000Z","dependencies_parsed_at":"2022-09-18T11:02:17.670Z","dependency_job_id":null,"html_url":"https://github.com/knowledgecode/WebSocket-for-Android","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knowledgecode%2FWebSocket-for-Android","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knowledgecode%2FWebSocket-for-Android/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knowledgecode%2FWebSocket-for-Android/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knowledgecode%2FWebSocket-for-Android/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/knowledgecode","download_url":"https://codeload.github.com/knowledgecode/WebSocket-for-Android/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251783525,"owners_count":21643125,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-03T17:45:36.062Z","updated_at":"2025-04-30T21:23:05.563Z","avatar_url":"https://github.com/knowledgecode.png","language":"Java","readme":"# cordova-plugin-websocket [![GitHub version](https://badge.fury.io/gh/knowledgecode%2FWebSocket-for-Android.svg)](http://badge.fury.io/gh/knowledgecode%2FWebSocket-for-Android)\r\nThis is a Cordova plugin, which is being developed based on [Jetty 8](https://github.com/eclipse/jetty.project/tree/jetty-8), makes WebSocket (RFC6455) available on Android.  \r\n\r\n## Requirements\r\n - Android 2.3 or later (recommended 4.1 or later)  \r\n - `cordova-android@3.6.0` or later, or compatible framework  \r\n - `cordova-plugin-whitelist` or `cordova-plugin-legacy-whitelist` if using `cordova-android@4.0.0` and later  \r\n\r\nThe plugin for Cordova 2.x can be found [here](https://github.com/knowledgecode/WebSocket-for-Android/tree/2.x). However it is no longer maintained.  \r\n\r\n## Supported Features\r\n| version         | WS protocol | WSS protocol | text message | binary message |\r\n|:---------------:|:-----------:|:------------:|:------------:|:--------------:|\r\n| 2.3.x (API 10)  | ✓          | ✓           | ✓           |                |\r\n| 4.0.x (API 14)  | ✓          | ✓           | ✓           | ✓             |\r\n| 4.0.x (API 15)  | ✓          | ✓           | ✓           | ✓             |\r\n| 4.1.x (API 16)  | ✓          | ✓           | ✓           | ✓             |\r\n| 4.2.x (API 17)  | ✓          | ✓           | ✓           | ✓             |\r\n| 4.3.x (API 18)  | ✓          | ✓           | ✓           | ✓             |\r\n| 4.4.x and later | -           | -            | -            | -              |\r\n\r\n#### Notes\r\n - Since Android 4.4.x (KitKat) and later support WebSocket, this plugin is **NOT** used on there by default.  \r\n - WSS protocol is only supported TLS. SSL is not supported.  \r\n - Android 3.x (Honeycomb) are not supported (might work but is not tested).  \r\n - In `cordova-android@4.0.0` and later, this plugin can be used together with [Crosswalk](https://crosswalk-project.org/). In this case also it is not used on there by default since that supports WebSocket.  \r\n - In order to support Android 5.x (Lollipop) and later, would be better to build with `cordova-android@3.7.1` or later.  \r\n\r\n## Installation\r\nUse Cordova Command-Line Interface (CLI). At first check your CLI version:\r\n```sh\r\n$ cordova --version\r\n5.0.0\r\n```\r\nIf using 5.0.0 and later, you can install it via npm:\r\n```sh\r\n$ cordova plugin add cordova-plugin-websocket\r\n```\r\nIf using other old versions, you can install it via GitHub:\r\n```sh\r\n$ cordova plugin add https://github.com/knowledgecode/WebSocket-for-Android.git\r\n```\r\n\r\n#### Setting a Content-Security-Policy (CSP)\r\n`cordova-android@4.0.0` and later support SCP. In order to permit WebSocket access using `cordova-plugin-whitelist`, append `connect-src` directive in `index.html`:\r\n```html\r\nconnect-src ws://example.com wss://example.com\r\n```\r\nFor example:\r\n```html\r\n\u003chead\u003e\r\n  \u003cmeta http-equiv=\"Content-Security-Policy\" content=\"default-src 'self' data: gap: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *; connect-src ws://example.com wss://example.com\"\u003e\r\n```\r\n\r\n## Upgrading from previous versions\r\nRemove and then reinstall:\r\n```sh\r\n$ cordova plugin rm cordova-plugin-websocket\r\n$ cordova plugin add cordova-plugin-websocket\r\n```\r\n\r\n#### Caveats\r\n- When install this plugin, it adds `INTERNET` permission to `platforms/android/AndroidManifest.xml`. If remove this plugin, the permission is also removed at the same time even if it is required for other plugins.  \r\n- It has not supported `cordova-android@3.5.x` and earlier since v0.12.0. Please make sure Android platform version is more than that:\r\n```sh\r\n$ cordova platform\r\nInstalled platforms: android 4.1.1\r\n```\r\n\r\n## Usage\r\n### *WebSocket(url[, protocols])*\r\nThe 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.  \r\nA simple code is as follows:  \r\n```javascript\r\ndocument.addEventListener('deviceready', function () {\r\n    var ws = new WebSocket('ws://echo.websocket.org');\r\n\r\n    ws.onopen = function () {\r\n        console.log('open');\r\n        this.send('hello');         // transmit \"hello\" after connecting\r\n    };\r\n\r\n    ws.onmessage = function (event) {\r\n        console.log(event.data);    // will be \"hello\"\r\n        this.close();\r\n    };\r\n\r\n    ws.onerror = function () {\r\n        console.log('error occurred!');\r\n    };\r\n\r\n    ws.onclose = function (event) {\r\n        console.log('close code=' + event.code);\r\n    };\r\n}, false);\r\n```\r\n#### Options\r\nThis plugin has the following options. All these parameters are optional. Of course these don't affect built-in WebSocket.  \r\n\r\n| key                  | type    | default value       | supported version        |\r\n|:---------------------|:--------|:--------------------|:-------------------------|\r\n| origin               | string  | file:// (usually)   | \u003e=v0.3.0                 |\r\n| maxConnectTime       | number  | 75000               | \u003e=v0.4.0                 |\r\n| maxTextMessageSize   | number  | -1                  | \u003e=v0.4.0 (except v0.8.x) |\r\n| maxBinaryMessageSize | number  | -1                  | \u003e=v0.4.0 (except v0.8.x) |\r\n| override             | boolean | false               | \u003e=v0.8.0                 |\r\n| agent                | string  | (depends on device) | \u003e=v0.9.0                 |\r\n| perMessageDeflate    | boolean | true                | \u003e=v0.10.0                |\r\n\r\n`origin` is a value to set a request header field. Default value is usually `file://`. This is the same value as when using built-in WebSocket.  \r\n\r\n`maxConnectTime` is time to wait for connection. A unit is millisecond.  \r\n\r\n`maxTextMessageSize` and `maxBinaryMessageSize` are receivable maximum size from a server. Default value is -1 (unlimited. depends on heap size of devices). A unit is byte.  \r\n\r\n`override` is a flag to force WebView to use this plugin even if it supports WebSocket. However in most cases it will be slower than built-in WebSocket.  \r\n\r\n`agent` is user-agent to set a request header field. Default value depends on devices. This is the same value as when using built-in WebSocket.  \r\n\r\n`perMessageDeflate` is a flag whether to use permessage-deflate extension. Default value is true. Sends data with compression if a server also supports permessage-deflate. However if mainly sending compressed binary like JPEG images, recommended to set to false.  \r\n\r\nIf change these parameters, need to do before creating a instance:  \r\n```javascript\r\nWebSocket.pluginOptions = {\r\n    origin: 'http://example.com',\r\n    maxConnectTime: 5000,\r\n    override: true\r\n};\r\n\r\nvar ws = new WebSocket('ws://echo.websocket.org');\r\n```\r\n### *send(data)*\r\nTransmits data to the server over the WebSocket connection. The data takes a string, a blob, or an arraybuffer.  \r\n\r\n#### Notes\r\nAn upper limit of the message size depends on heap size of devices. It would be better to consider a way to split the message if it is quite large.  \r\n### *close([code[, reason]])*\r\nCloses the WebSocket connection or connection attempt, if any.  \r\n\r\n### For debug\r\nThis plugin has been available logging for debug since v0.12.0. The logging level can be adjusted with `config.xml` that is in your project directory:  \r\n```xml\r\n\u003cplatform name=\"android\"\u003e\r\n    \u003cpreference name=\"LogLevel\" value=\"DEBUG\" /\u003e\r\n\u003c/platform\u003e\r\n```\r\nIf don't specify this parameter, default level is `DEBUG`. So at first you may be surprised to see many debug logs on logcat. To stop logs except errors, change the level to `ERROR`.  \r\n\r\n## Change Log\r\nSee [CHANGELOG.md](https://github.com/knowledgecode/WebSocket-for-Android/blob/master/CHANGELOG.md).\r\n\r\n## License\r\nThis plugin is available under the terms of the Apache License Version 2.0.\r\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknowledgecode%2Fwebsocket-for-android","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fknowledgecode%2Fwebsocket-for-android","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknowledgecode%2Fwebsocket-for-android/lists"}