SocketCluster

16.0.1

socketClusterClient

Properties

version The SocketCluster client version number.
AGClientSocket A reference to the SocketCluster client socket class.

Methods

create([options])

Creates and returns a new socket connection to the specified host (or origin if not specified). The options argument is optional - If omitted, the socket will try to connect to the origin server on the current port. For cross domain requests, a typical options object might look like this (example over HTTPS/WSS): 

{
  hostname: 'securedomain.com',
  secure: true,
  port: 443,
  // Only necessary during debug if using a self-signed certificate
  wsOptions: { rejectUnauthorized: false }
}

Here are some properties that you can provide to the options object:

  • hostname: String - Defaults to the current host (ready from the URL).
  • secure: Boolean - Defaults to false
  • port: Number - Defaults to 80 if !secure otherwise defaults to 443.
  • path: String - The URL which SocketCluster uses to make the initial handshake for the WebSocket. Defaults to '/socketcluster/'.
  • query: Object - A map of key-value pairs which will be used as query parameters for the initial HTTP handshake which will initiate the WebSocket connection.
  • connectTimeout: Number (milliseconds) - This is the timeout for establishing a connection.
  • ackTimeout: Number (milliseconds) - This is the timeout for getting a response to a AGClientSocket invoke action.
  • autoConnect: Boolean - Whether or not to automatically connect the socket as soon as it is created. Default is true.
  • autoReconnect: Boolean - Whether or not to automatically reconnect the socket when it loses the connection.
  • autoReconnectOptions: Object - Valid properties are: initialDelay (milliseconds), randomness (milliseconds), multiplier (decimal; default is 1.5) and maxDelay (milliseconds).
  • disconnectOnUnload: Boolean - Whether or not a client automatically disconnects on page unload. If enabled, the client will disconnect when a user navigates away from the page. This can happen when a user closes the tab/window, clicks a link to leave the page, or types a new URL into the address bar. Defaults to true.
  • wsOptions: Object - This object will be passed to the constructor of the ws WebSocket instance. The list of supported properties is here.
  • batchOnHandshake: Boolean - Whether or not to start batching messages immediately after the connection handshake completes. This is useful for handling connection recovery when the client tries to resubscribe to a large number of channels in a very short amount of time. Defaults to false.
  • batchOnHandshakeDuration: Number - The amount of time in milliseconds after the handshake completes during which all socket messages will be batched. Defaults to 100.
  • batchInterval: Number - The amount of milliseconds to wait before flushing each batch of messages. Defaults to 50.
  • timestampRequests: Boolean - Whether or not to add a timestamp to the WebSocket handshake request.
  • timestampParam: String - The query parameter name to use to hold the timestamp.
  • authEngine: Object - A custom engine to use for storing and loading JWT auth tokens on the client side.
  • authTokenName: String - The name of the JWT auth token (provided to the authEngine - By default this is the localStorage variable name); defaults to 'socketcluster.authToken'.
  • binaryType: String - The type to use to represent binary on the client. Defaults to 'arraybuffer'.
  • cloneData: Boolean - If you set this to true, any data/objects/arrays that you pass to the client socket will be cloned before being sent/queued up. If the socket is disconnected and you emit an event, it will be added to a queue which will be processed upon reconnection. The cloneData option is false by default; this means that if you emit/publish an object and that object changes somewhere else in your code before the queue is processed, then the changed version of that object will be sent out to the server.
  • autoSubscribeOnConnect: Boolean - This is true by default. If you set this to false, then the socket will not automatically try to subscribe to pending subscriptions on connect - Instead, you will have to manually invoke the processSubscriptions callback from inside the 'connect' event handler on the client side. See AGClientSocket API. This gives you more fine-grained control with regards to when pending subscriptions are processed after the socket connection is established (or re-established).
  • codecEngine: Object - Lets you set a custom codec engine. This allows you to specify how data gets encoded before being sent over the wire and how it gets decoded once it reaches the other side. The codecEngine must be an object which exposes an encode(object) and a decode(encodedData) function. The encode function can return any data type - Commonly a string or a Buffer/ArrayBuffer. The decode function needs to return a JavaScript object which adheres to the SC protocol. The idea of using a custom codec is that it allows you to compress SocketCluster packets in any format you like (optimized for any use case) - By decoding these packets back into their original protocol form, SocketCluster will be able process them appropriately. Note that if you provide a codecEngine when creating a client socket, you will need to make sure that the server uses the same codec by passing the same engine to the AGServer constructor (using the codecEngine option). The default codec engine used by SocketCluster is here.
← socketClusterServerAGClientSocket →