socket.io-client
How to use
npm i https://github.com/cantecim/socket.io-client.git#master -S
A standalone build of socket.io-client
is exposed automatically by the
socket.io server as /socket.io/socket.io.js
. Alternatively you can
serve the file socket.io.js
found at the root of this repository.
<script src="/socket.io/socket.io.js"></script>
<script>
var socket = io('http://localhost');
socket.on('connect', function(){});
socket.on('event', function(data){});
socket.on('disconnect', function(){});
</script>
Socket.IO is compatible with browserify.
Node.JS (server-side usage)
Add socket.io-client
to your package.json
and then:
var socket = require('socket.io-client')('http://localhost');
socket.on('connect', function(){});
socket.on('event', function(data){});
socket.on('disconnect', function(){});
API
IO(url:String, opts:Object):Socket
Exposed as the io
namespace in the standalone build, or the result
of calling require('socket.io-client')
.
When called, it creates a new Manager
for the given URL, and attempts
to reuse an existing Manager
for subsequent calls, unless the
multiplex
option is passed with false
.
The rest of the options are passed to the Manager
constructor (see below
for details).
A Socket
instance is returned for the namespace specified by the
pathname in the URL, defaulting to /
. For example, if the url
is
http://localhost/users
, a transport connection will be established to
http://localhost
and a Socket.IO connection will be established to
/users
.
IO#protocol
Socket.io protocol revision number this client works with.
IO#Socket
Reference to the Socket
constructor.
IO#Manager
Reference to the Manager
constructor.
IO#Emitter
Reference to the Emitter
constructor.
Manager(url:String, opts:Object)
A Manager
represents a connection to a given Socket.IO server. One or
more Socket
instances are associated with the manager. The manager
can be accessed through the io
property of each Socket
instance.
The opts
are also passed to engine.io
upon initialization of the
underlying Socket
.
Options:
reconnection
whether to reconnect automatically (true
)reconnectionAttempts
(Infinity
) before giving upreconnectionDelay
how long to initially wait before attempting a new reconnection (1000
). Affected by +/-randomizationFactor
, for example the default initial delay will be between 500 to 1500ms.reconnectionDelayMax
maximum amount of time to wait between reconnections (5000
). Each attempt increases the reconnection delay by 2x along with a randomization as aboverandomizationFactor
(0.5
), 0 <= randomizationFactor <= 1timeout
connection timeout before aconnect_error
andconnect_timeout
events are emitted (20000
)autoConnect
by setting this false, you have to callmanager.open
whenever you decide it's appropriate
Events
connect_error
. Fired upon a connection error. Parameters:Object
error object
connect_timeout
. Fired upon a connection timeout.reconnect
. Fired upon a successful reconnection. Parameters:Number
reconnection attempt number
reconnect_attempt
. Fired upon an attempt to reconnect.reconnecting
. Fired upon an attempt to reconnect. Parameters:Number
reconnection attempt number
reconnect_error
. Fired upon a reconnection attempt error. Parameters:Object
error object
reconnect_failed
. Fired when couldn't reconnect withinreconnectionAttempts
ping
. Fired when a ping packet is written out to the server.pong
. Fired when a pong is received from the server. Parameters:Number
number of ms elapsed sinceping
packet (i.e.: latency).
The events above are also emitted on the individual sockets that
reconnect that depend on this Manager
.
Manager#reconnection(v:Boolean):Manager
Sets the reconnection
option, or returns it if no parameters
are passed.
Manager#reconnectionAttempts(v:Boolean):Manager
Sets the reconnectionAttempts
option, or returns it if no parameters
are passed.
Manager#reconnectionDelay(v:Boolean):Manager
Sets the reconectionDelay
option, or returns it if no parameters
are passed.
Manager#reconnectionDelayMax(v:Boolean):Manager
Sets the reconectionDelayMax
option, or returns it if no parameters
are passed.
Manager#timeout(v:Boolean):Manager
Sets the timeout
option, or returns it if no parameters
are passed.
Socket
Socket#id:String
A property on the socket
instance that is equal to the underlying engine.io socket id.
The property is present once the socket has connected, is removed when the socket disconnects and is updated if the socket reconnects.
Socket#compress(v:Boolean):Socket
Sets a modifier for a subsequent event emission that the event data will
only be compressed if the value is true
. Defaults to true
when you don't call the method.
socket.compress(false).emit('an event', { some: 'data' });
Events
connect
. Fired upon a connection including a successful reconnection.error
. Fired upon a connection error Parameters:Object
error data
disconnect
. Fired upon a disconnection.reconnect
. Fired upon a successful reconnection. Parameters:Number
reconnection attempt number
reconnect_attempt
. Fired upon an attempt to reconnect.reconnecting
. Fired upon an attempt to reconnect. Parameters:Number
reconnection attempt number
reconnect_error
. Fired upon a reconnection attempt error. Parameters:Object
error object
reconnect_failed
. Fired when couldn't reconnect withinreconnectionAttempts