Under the hood SockJS tries to use native WebSockets first. If that fails it can use a variety of browser-specific transport protocols and presents them through WebSocket-like abstractions.
SockJS is intended to work for all modern browsers and in environments which don't support the WebSocket protocol -- for example, behind restrictive corporate proxies.
SockJS-client does require a server counterpart:
Subscribe to SockJS mailing list for discussions and support.
Work in progress:
SockJS mimics the WebSockets API,
but instead of
WebSocket there is a
After the script is loaded you can establish a connection with the SockJS server. Here's a simple example:
var sock = '';console.log'open';;console.log'message' edata;;console.log'close';;socksend'test';sockclose;
Similar to the 'WebSocket' API, the 'SockJS' constructor takes one, or more arguments:
var sockjs = url _reserved options;
url may contain a query string, if one is desired.
options is a hash which can contain:
String to append to url for actual data connection. Defaults to a random 4 digit number.
transports (string OR array of strings)
Sometimes it is useful to disable some fallback transports. This option allows you to supply a list transports that may be used by SockJS. By default all available transports will be used.
sessionId (number OR function)
Both client and server use session identifiers to distinguish connections. If you specify this option as a number, SockJS will use its random string generator function to generate session ids that are N-character long (where N corresponds to the number specified by sessionId). When you specify this option as a function, the function must return a randomly generated string. Every time SockJS needs to generate a session id it will call this function and use the returned string directly. If you don't specify this option, the default is to use the default random string generator to generate 8-character long session ids.
Although the 'SockJS' object tries to emulate the 'WebSocket' behaviour, it's impossible to support all of its features. An important SockJS limitation is the fact that you're not allowed to open more than one SockJS connection to a single domain at a time. This limitation is caused by an in-browser limit of outgoing connections - usually browsers don't allow opening more than two outgoing connections to a single domain. A single SockJS session requires those two connections - one for downloading data, the other for sending messages. Opening a second SockJS session at the same time would most likely block, and can result in both sessions timing out.
Opening more than one SockJS connection at a time is generally a bad practice. If you absolutely must do it, you can use multiple subdomains, using a different subdomain for every SockJS connection.
|IE 6, 7||no||no||jsonp-polling|
|IE 8, 9 (cookies=no)||no||xdr-streaming †||xdr-polling †|
|IE 8, 9 (cookies=yes)||no||iframe-htmlfile||iframe-xhr-polling|
|Chrome 14+||hybi-10 / rfc6455||xhr-streaming||xhr-polling|
|Firefox <10||no ‡||xhr-streaming||xhr-polling|
|Firefox 10+||hybi-10 / rfc6455||xhr-streaming||xhr-polling|
|Opera 10.70+||no ‡||iframe-eventsource||iframe-xhr-polling|
†: IE 8+ supports XDomainRequest, which is essentially a modified AJAX/XHR that can do requests across domains. But unfortunately it doesn't send any cookies, which makes it inappropriate for deployments when the load balancer uses JSESSIONID cookie to do sticky sessions.
‡: Firefox 4.0 and Opera 11.00 and shipped with disabled Websockets "hixie-76". They can still be enabled by manually changing a browser setting.
Sometimes you may want to serve your html from "file://" address - for development or if you're using PhoneGap or similar technologies. But due to the Cross Origin Policy files served from "file://" have no Origin, and that means some of SockJS transports won't work. For this reason the SockJS transport table is different than usually, major differences are:
|IE 8, 9||same as above||iframe-htmlfile||iframe-xhr-polling|
|Other||same as above||iframe-eventsource||iframe-xhr-polling|
|websocket (rfc6455)||rfc 6455|
|xhr-streaming||Transport using Cross domain XHR streaming capability (readyState=3).|
|xdr-streaming||Transport using XDomainRequest streaming capability (readyState=3).|
|iframe-eventsource||EventSource used from an iframe via postMessage.|
|iframe-htmlfile||HtmlFile used from an iframe via postMessage.|
|xhr-polling||Long-polling using cross domain XHR.|
|xdr-polling||Long-polling using XDomainRequest.|
|iframe-xhr-polling||Long-polling using normal AJAX from an iframe via postMessage.|
|jsonp-polling||Slow and old fashioned JSONP polling. This transport will show "busy indicator" (aka: "spinning wheel") when sending data.|
Although the main point of SockJS is to enable browser-to-server connectivity, it is possible to connect to SockJS from an external application. Any SockJS server complying with 0.3 protocol does support a raw WebSocket url. The raw WebSocket url for the test server looks like:
You can connect any WebSocket RFC 6455 compliant WebSocket client to this url. This can be a command line client, external application, third party code or even a browser (though I don't know why you would want to do so).
You should use a version of sockjs-client that supports the protocol used by your server. For example:
For server-side deployment tricks, especially about load balancing and session stickiness, take a look at the SockJS-node readme.
cd sockjs-client npm install
Both commands output into the
Once you've compiled the SockJS-client you may want to check if your changes pass all the tests.
There are various browser quirks which we don't intend to address:
jsonp-pollingtransport will show a "spinning wheel" (aka. "busy indicator") when sending data.
onmessageor such is probably a bad idea, as it could be called by the built-in