WebSockets is a transmission protocol designed to permit bi-directional message passing over TCP connections using a single port.

Its most common implementation is in modern web browsers. This enables browsers to connect to a WebSocket and retrieve curated DataSift content in near-realtime, without the technical boundaries of an HTTP Stream.

This document describes the implementation of a WebSockets DataSift client in JavaScript, intended for a client web browser.

Authorization

Unlike the HTTP Streaming API, WebSockets cannot use custom headers for authentication (especially in the browser). Because of this authorization is done using GET parameters for username and API key.

The Request URI for WebSockets connections to DataSift is:

    wss://stream.datasift.com/<hash>?username=<username>&api_key=<api_key>

Events

WebSockets in JavaScript rely on using the following events on a WebSocket object:

  • onopen
  • onclose
  • onmessage
  • onerror

You must implement each of them in your code.

Also, be sure to initialize the WebSocket object with the WebSocket URI.

    var ws = new WebSocket('wss://stream.datasift.com/<hash>?username=<username>&api_key=<api_key>');

Open

The onopen event is triggered when the connection has been established.

The parameter is evt object - an object passed by the client automatically.

Close

The onclose event is triggered when the connection has been disconnected for any reason, this includes some error states.

The parameter is evt object - an object passed by the client automatically.

Messages

The onmessage event will be were all the data processing of the incoming stream is done.

The Parameter is evt object - An object passed by the client automatically.

Errors

In the event of an error, the onerror event will be triggered. Unfortunately, the WebSocket API (Draft 76) does not pass an event object to the onerror event.

JSON

The JSON objects returned by the onmessage event look like this:

 

For these messages there can also be an unlimited number of arbitrary keys, for example:

 

On initial connection, we send a tick with a status of "initialised":

 

Then if there is no data for 30 seconds, we send another tick, but with a status of "connected":

 

Note that error messages and ticks contain the "status" key whereas interactions (that is the data coming from a stream or Historics query) do not.

 

Protocol

We follow the WebSocket standard for Draft 76, a current version of the draft is specified at WebSocket API.

Despite following the standard, any messages sent to the DataSift WebSocket server will be ignored.

 

Supported Browsers

  • Safari 5+
  • Opera 10.70 (currently disabled)
  • Google Chrome 6+
  • Firefox 6+
  • iOS (Version 4.2+, iPod Touch, iPhone & iPad)