WebSocket: WebSocket() constructor

url

The URL of the target WebSocket server to connect to. The URL must use one of the following schemes: ws, wss, http, or https, and cannot include a URL fragment. If a relative URL is provided, it is relative to the base URL of the calling script.

protocols Optional

A single string or an array of strings representing the sub-protocol(s) that the client would like to use. If it is omitted, an empty array is used by default, i.e. [].

A single server can implement multiple WebSocket sub-protocols, and handle different types of interactions depending on the specified value. The allowed values are those that can be specified in the Sec-WebSocket-Protocol HTTP header.

Note that the connection is not established until the sub-protocol is negotiated with the server. The selected protocol can then be read from WebSocket.protocol.

SyntaxError DOMException

Thrown if:

• parsing of url fails
• url has a scheme other than ws, wss, http, or https
• url has a fragment
• any of the values in protocols occur more than once, or otherwise fail to match the requirements for elements that comprise the value of Sec-WebSocket-Protocol fields as defined by the WebSocket Protocol specification

The examples below show how you might connect to a WebSocket.

The code below shows how we can connect to a socket using an URL with the wss schema:

const httpsWebSocket = new WebSocket('wss://websocket.example.org');
console.log(httpsWebSocket.url); // 'wss://websocket.example.org'
... // Do something with socket
httpsWebSocket.close();

The code for connecting to an HTTPS URL is nearly the same. Under the hood the browser resolves this to a "WSS" connection, so the WebSocket.url will have the schema "wss:".

let wssWebSocket = new WebSocket('https://websocket.example.org');
console.log(wssWebSocket.url); // 'wss://websocket.example.org'
... // Do something with socket
wssWebSocket.close();

We can also resolve relative URLs. The absolute URL will depend on the base URL of the context in which it is called.

relativeWebSocket = new WebSocket('/local/url');
... // Do something with socket
relativeWebSocket.close();

• RFC 6455 (the WebSocket Protocol specification)