Converse converse.js

Class: Connection

Connection()

Constructor: Strophe.Connection Create and initialize a Strophe.Connection object.

The transport-protocol for this connection will be chosen automatically based on the given service parameter. URLs starting with "ws://" or "wss://" will use WebSockets, URLs starting with "http://", "https://" or without a protocol will use BOSH.

To make Strophe connect to the current host you can leave out the protocol and host part and just pass the path, e.g.

let conn = new Strophe.Connection("/http-bind/");

Options common to both Websocket and BOSH:

cookies:

The cookies option allows you to pass in cookies to be added to the document. These cookies will then be included in the BOSH XMLHttpRequest or in the websocket connection.

The passed in value must be a map of cookie names and string values.

{ "myCookie": { "value": "1234", "domain": ".example.org", "path": "/", "expires": expirationDate } }

Note that cookies can't be set in this way for other domains (i.e. cross-domain). Those cookies need to be set under those domains, for example they can be set server-side by making a XHR call to that domain to ask it to set any necessary cookies.

mechanisms:

The mechanisms option allows you to specify the SASL mechanisms that this instance of Strophe.Connection (and therefore your XMPP client) will support.

The value must be an array of objects with Strophe.SASLMechanism prototypes.

If nothing is specified, then the following mechanisms (and their priorities) are registered:

 SCRAM-SHA-1 - 60
 PLAIN       - 50
 OAUTHBEARER - 40
 X-OAUTH2    - 30
 ANONYMOUS   - 20
 EXTERNAL    - 10

explicitResourceBinding:

If explicitResourceBinding is set to a truthy value, then the XMPP client needs to explicitly call Strophe.Connection.prototype.bind once the XMPP server has advertised the "urn:ietf:params:xml:ns:xmpp-bind" feature.

Making this step explicit allows client authors to first finish other stream related tasks, such as setting up an XEP-0198 Stream Management session, before binding the JID resource for this session.

WebSocket options:

protocol:

If you want to connect to the current host with a WebSocket connection you can tell Strophe to use WebSockets through a "protocol" attribute in the optional options parameter. Valid values are "ws" for WebSocket and "wss" for Secure WebSocket. So to connect to "wss://CURRENT_HOSTNAME/xmpp-websocket" you would call

let conn = new Strophe.Connection("/xmpp-websocket/", {protocol: "wss"});

Note that relative URLs NOT starting with a "/" will also include the path of the current site.

Also because downgrading security is not permitted by browsers, when using relative URLs both BOSH and WebSocket connections will use their secure variants if the current connection to the site is also secure (https).

worker:

Set this option to URL from where the shared worker script should be loaded.

To run the websocket connection inside a shared worker. This allows you to share a single websocket-based connection between multiple Strophe.Connection instances, for example one per browser tab.

The script to use is the one in src/shared-connection-worker.js.

BOSH options:

By adding "sync" to the options, you can control if requests will be made synchronously or not. The default behaviour is asynchronous. If you want to make requests synchronous, make "sync" evaluate to true.

let conn = new Strophe.Connection("/http-bind/", {sync: true});

You can also toggle this on an already established connection.

conn.options.sync = true;

The customHeaders option can be used to provide custom HTTP headers to be included in the XMLHttpRequests made.

The keepalive option can be used to instruct Strophe to maintain the current BOSH session across interruptions such as webpage reloads.

It will do this by caching the sessions tokens in sessionStorage, and when "restore" is called it will check whether there are cached tokens with which it can resume an existing session.

The withCredentials option should receive a Boolean value and is used to indicate wether cookies should be included in ajax requests (by default they're not). Set this value to true if you are connecting to a BOSH service and for some reason need to send cookies to it. In order for this to work cross-domain, the server must also enable credentials by setting the Access-Control-Allow-Credentials response header to "true". For most usecases however this setting should be false (which is the default). Additionally, when using Access-Control-Allow-Credentials, the Access-Control-Allow-Origin header can't be set to the wildcard "*", but instead must be restricted to actual domains.

The contentType option can be set to change the default Content-Type of "text/xml; charset=utf-8", which can be useful to reduce the amount of CORS preflight requests that are sent to the server.

Parameters: (String) service - The BOSH or WebSocket service URL. (Object) options - A hash of configuration options

Returns: A new Strophe.Connection object.