Home

Awesome

Engine.IO client

Build Status NPM version

This is the client for Engine.IO, the implementation of transport-based cross-browser/cross-device bi-directional communication layer for Socket.IO.

How to use

Standalone

You can find an engine.io.js file in this repository, which is a standalone build you can use as follows:

<script src="/path/to/engine.io.js"></script>
<script>
  // eio = Socket
  var socket = eio('ws://localhost');
  socket.on('open', function(){
    socket.on('message', function(data){});
    socket.on('close', function(){});
  });
</script>

With browserify

Engine.IO is a commonjs module, which means you can include it by using require on the browser and package using browserify:

  1. install the client package

    $ npm install engine.io-client

  2. write your app code

    var socket = require('engine.io-client')('ws://localhost');
socket.on('open', function(){
  socket.on('message', function(data){});
  socket.on('close', function(){});
});

  3. build your app bundle

    $ browserify app.js > bundle.js

  4. include on your page

    <script src="/path/to/bundle.js"></script>

Sending and receiving binary

<script src="/path/to/engine.io.js"></script>
<script>
  var socket = new eio.Socket('ws://localhost/');
  socket.binaryType = 'blob';
  socket.on('open', function () {
    socket.send(new Int8Array(5));
    socket.on('message', function(blob){});
    socket.on('close', function(){ });
  });
</script>

Node.JS

Add engine.io-client to your package.json and then:

var socket = require('engine.io-client')('ws://localhost');
socket.on('open', function(){
  socket.on('message', function(data){});
  socket.on('close', function(){});
});

Node.js with certificates

var opts = {
  key: fs.readFileSync('test/fixtures/client.key'),
  cert: fs.readFileSync('test/fixtures/client.crt'),
  ca: fs.readFileSync('test/fixtures/ca.crt')
};

var socket = require('engine.io-client')('ws://localhost', opts);
socket.on('open', function(){
  socket.on('message', function(data){});
  socket.on('close', function(){});
});

Node.js with extraHeaders

var opts = {
  extraHeaders: {
    'X-Custom-Header-For-My-Project': 'my-secret-access-token',
    'Cookie': 'user_session=NI2JlCKF90aE0sJZD9ZzujtdsUqNYSBYxzlTsvdSUe35ZzdtVRGqYFr0kdGxbfc5gUOkR9RGp20GVKza; path=/; expires=Tue, 07-Apr-2015 18:18:08 GMT; secure; HttpOnly'
  }
};

var socket = require('engine.io-client')('ws://localhost', opts);
socket.on('open', function(){
  socket.on('message', function(data){});
  socket.on('close', function(){});
});

Features

API

Socket

The client class. Mixes in Emitter. Exposed as eio in the browser standalone build.

Properties

Events

Methods

Transport

The transport class. Private. Inherits from EventEmitter.

Events

Tests

engine.io-client is used to test engine. Running the engine.io test suite ensures the client works and vice-versa.

Browser tests are run using zuul. You can run the tests locally using the following command.

./node_modules/.bin/zuul --local 8080 -- test/index.js

Additionally, engine.io-client has a standalone test suite you can run with make test which will run node.js and browser tests. You must have zuul setup with a saucelabs account.

Support

The support channels for engine.io-client are the same as socket.io:

Development

To contribute patches, run tests or benchmarks, make sure to clone the repository:

git clone git://github.com/socketio/engine.io-client.git

Then:

cd engine.io-client
npm install

See the Tests section above for how to run tests before submitting any patches.

License

MIT - Copyright (c) 2014 Automattic, Inc.