Created: 2011-07-16 19:24
Updated: 2014-03-02 23:05

README.markdown javascript client

The official javascript client library for

Include the Shove Library

Include the latest version of the shove javascript client.

<script type="text/javascript" src=""></script>



Connect the client to your app"s network to enable the client to publish or receive messages from the app and other clients.

$shove.connect("{{app_id}}", "{{connect_key}}");

Bind handlers to shove app networks

Allow your client-side app to respond to network events with the following types:

  • connect
  • connect_denied
  • connecting
  • disconnect
  • handshaking
  • failure
  • reconnect
$shove.on("connect", function() {
  console.log("shove network connected");

Unbind handlers from shove app networks

In the case of removing bound event handlers, the original function must be used for comparison.

var fn = function(){
  console.log("Shove Connected!");
  return true;
$shove.on("connect", fn);
$"connect", fn);


It's possible to grant clients publish and subscribe rights on one or more channels.

If your client needs publish/subscribe access on all channels, you can authenticate the client using the * channel. This is only recommended if the client is a trusted client.

$"*").authenticate("sub or channel key");

To generate keys see the Channel Keys section of the shove-ruby implementation.




Channels that do not exist will be created automatically by the Shove server. Bind handlers using the following event types:

  • message
  • publish_denied
  • publish_granted
  • subscribe
  • subscribing
  • subscribe_denied
  • unsubscribe
  • unsubscribing
var channel = $"channel_name");

channel.on("subscribe", function() {
  console.log("you are subscribed to this channel!");

channel.on("unauthorized", function() {
  console.log("channel subscribe failed, not authorized!");

As soon as you bind a handler to the channel you will start to receive messages.

Unsubscribe from Channels

A client will cease to receive messages from a channel when unsubscribed.


Add filters to easily modify incoming messages

Filters are applied to incoming messages before the "message" event is fired. Message processing can be halted if a filter returns false.

// replaces occurrences of "hello" with "HULLO" for all messages received
channel.filter(function(msg,from) {
  if(msg.hasOwnProperty("data") && typeof == "string") { ="hello","HULLO");
  return msg;

// Halt messages that contain profanity
channel.filter(function(msg,from) {
  if(msg.hasOwnProperty("data") && typeof == "string"){
    if(|words)/gi) >= 0)
      return false;
  return msg;

channel.on("message", function(msg) {
  // handle message as you see fit

Access to active filters

An array of bound filter functions can be obtained by omitting a function argument.

console.log(channel.filter().length + " filters are currently in the message pipeline.");

Publish Messages

If publishing is allowed on all channels by default, or if the client application has already authorized itself then sending messages is simple. Messages should be simple strings, if a message needs to be more complex use JSON.stringify() and JSON.parse() to encode and decode objects.

channel.publish("message here");

var complexMessage = {
  x: 0,
  y: 100,
  l: 42

A filter can be applied to all incoming messages to handle the decoding of data.

channel.filter(function(m,from) {
  return JSON.parse(m);

Or if not all messages need to be complex objects then perhaps multiple channels should be used.

var simpleChannel = $"channel-a");
var complexChannel = $"channel-b");

simpleChannel.on("message", function(message, from) { 
  // handle incoming simple (string) messages
  console.log(typeof message);

complexChannel.on("message", function(message, from) {
  // handle incoming object messages
  console.log(typeof message);

simpleChannel.publish("simple messages abound!");

complexChannel.filter(function(m,from) {
  return JSON.parse(m);

  x: 0,
  y: 100,
  l: 42
Cookies help us deliver our services. By using our services, you agree to our use of cookies Learn more