Channel Service

The Epicenter platform provides a push channel, which allows you to publish and subscribe to messages within a project, group, or multiplayer world. There are two main use cases for the channel: event notifications and chat messages.

If you are developing with Epicenter.js, you should use the Epicenter Channel Manager directly. The Epicenter Channel Manager documentation also has more background information on channels and their use.

The Channel Service is a building block for this functionality. It creates a publish-subscribe object, allowing you to publish messages, subscribe to messages, or unsubscribe from messages for a given 'topic' on a $.cometd transport instance.

You'll need to include the epicenter-multiplayer-dependencies.js library in addition to the epicenter.js library in your project to use the Channel Service. See Including Epicenter.js.

To use the Channel Service, instantiate it, then make calls to any of the methods you need.

var cs = new F.service.Channel();
cs.publish('/acme-simulations/supply-chain-game/fall-seminar/run/variables', { price: 50 });

If you are working through the Epicenter Channel Manager, when you ask to "get" a particular channel, you are really asking for an instance of the Channel Service with a topic already set, for example to the appropriate group or world:

var cm = new F.manager.ChannelManager();
var gc = cm.getGroupChannel();
// because we used an Epicenter Channel Manager to get the group channel,
// subscribe() and publish() here default to the base topic for the group
gc.subscribe('', function(data) { console.log(data); });
gc.publish('', { message: 'a new message to the group' });

Constructor options

Required?	Name	Type	Description
	base	string	The base topic. This is added as a prefix to all further topics you publish or subscribe to while working with this Channel Service.
	topicResolver	function(topic): string	A function that processes all 'topics' passed into the publish and subscribe methods. This is useful if you want to implement your own serialize functions for converting custom objects to topic names. By default, it just echoes the topic.
	transport	object	The instance of $.cometd to hook onto. See http://docs.cometd.org/reference/javascript.html for additional background on cometd.

Methods

subscribe(topic, callback, context[, options])

Subscribe to changes on a topic.

The topic should include the full path of the account id (Team ID for team projects), project id, and group name. (In most cases, it is simpler to use the Epicenter Channel Manager instead, in which case this is configured for you.)

Parameters

Required?	Name	Type	Description
Yes	topic	String / Array	List of topics to listen for changes on.
Yes	callback	Function	Callback function to execute. Callback is called with signature (evt, payload, metadata).
Yes	context	Object	Context in which the callback is executed.
	options	Object	Overrides for configuration options.
	options.priority	number	Used to control order of operations. Defaults to 0. Can be any +ve or -ve number.
	options.value	String / number / Function	The callback is only triggered if this condition matches. See examples for details.

Returns

object - Returns a subscription object you can later use to unsubscribe.

Example

var cb = function(val) { console.log(val.data); };

 // Subscribe to changes on a top-level 'run' topic
 cs.subscribe('/acme-simulations/supply-chain-game/fall-seminar/run', cb);

 // Subscribe to changes on children of the 'run' topic. Note this will also be triggered for changes to run.x.y.z.
 cs.subscribe('/acme-simulations/supply-chain-game/fall-seminar/run/*', cb);

 // Subscribe to changes on both the top-level 'run' topic and its children
 cs.subscribe(['/acme-simulations/supply-chain-game/fall-seminar/run',
     '/acme-simulations/supply-chain-game/fall-seminar/run/*'], cb);

 // Subscribe to changes on a particular variable
 subscribe('/acme-simulations/supply-chain-game/fall-seminar/run/variables/price', cb);

publish(topic, data)

Publish data to a topic.

Parameters

Required?	Name	Type	Description
Yes	topic	String	Topic to publish to.
Yes	data	any	Data to publish to topic.

Returns

Array - Responses to published data

Example

// Send data to all subscribers of the 'run' topic
cs.publish('/acme-simulations/supply-chain-game/fall-seminar/run', { completed: false });

// Send data to all subscribers of the 'run/variables' topic
cs.publish('/acme-simulations/supply-chain-game/fall-seminar/run/variables', { price: 50 });

unsubscribe(token)

Unsubscribe from changes to a topic.

Parameters

Required?	Name	Type	Description
Yes	token	String	The token for topic is returned when you initially subscribe. Pass it here to unsubscribe from that topic.

Returns

Object - reference to current instance

Example

cs.unsubscribe('sampleToken');

on(event)

Start listening for events on this instance. Signature is same as for jQuery Events: http://api.jquery.com/on/.

Supported events are: connect, disconnect, subscribe, unsubscribe, publish, error.

Parameters

Required?	Name	Type	Description
Yes	event	string	The event type. See more detail at jQuery Events: http://api.jquery.com/on/.

off(event)

Stop listening for events on this instance. Signature is same as for jQuery Events: http://api.jquery.com/off/.

Parameters

Required?	Name	Type	Description
Yes	event	string	The event type. See more detail at jQuery Events: http://api.jquery.com/off/.

trigger(event)

Trigger events and execute handlers. Signature is same as for jQuery Events: http://api.jquery.com/trigger/.

Parameters

Required?	Name	Type	Description
Yes	event	string	The event type. See more detail at jQuery Events: http://api.jquery.com/trigger/.