Faye

Browser client

Subscribing to channels

Clients receive data from other clients by subscribing to channels. Whenever any client sends a message to a channel you’re subscribed to, Faye will notify your client with the new message.

Channel names must be formatted as absolute path names whose segments may contain only letters, numbers, and the symbols -, _, !, ~, (, ), $ and @. Channel names may also end with wildcards:

• The * wildcard matches any channel segment. So /foo/* matches /foo/bar and /foo/thing but not /foo/bar/thing.
• The ** wildcard matches any channel name recursively. So /foo/** matches /foo/bar, /foo/thing and /foo/bar/thing.

So for example if you subscribe to /foo/* and someone sends a message to /foo/bar, you will receive that message.

Clients should subscribe to channels using the #subscribe() method:

var subscription = client.subscribe('/foo', function(message) {
  // handle message
});

The subscriber function will be invoked when anybody sends a message to /foo, and the message parameter will contain the sent message object. A client may bind multiple listeners to a channel, and the Faye client handles all the management of those listeners and makes sure the server sends it the right messages.

The subscribe() method returns a Subscription object, which you can cancel if you want to remove that listener from the channel.

subscription.cancel();

The Subscription object is a promise that is fulfilled when the subscription has been acknowledged by the server:

subscription.then(function() {
  alert('Subscription is now active!');
});

If you’re subscribing to a wildcard channel, you may want to receive the specific channel the message was published to in your subscriber function. You can do this using the `withChannel()` method:

client.subscribe('/foo/*').withChannel(function(channel, message) {
  // handle message
});