forio Toggle navigation

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.

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.

Typically, you use the Epicenter Channel Manager to create or retrieve channels, then use the Channel Service subscribe() and publish() methods to listen to or update data. (For additional background on Epicenter's push channel, see the introductory notes on the Push Channel API page.)

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 });

The parameters for instantiating a Channel Service include:

  • options The options object to configure the Channel Service.
  • options.base The base topic. This is added as a prefix to all further topics you publish or subscribe to while working with this Channel Service.
  • options.topicResolver 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. Returns a String. By default, it just echoes the topic.
  • options.transport The instance of $.cometd to hook onto. See http://docs.cometd.org/reference/javascript.html for additional background on cometd.

Configuration Options

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.

transport

  • object

The instance of $.cometd to hook onto.

Methods

topicResolver

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.

Parameters

  • topic Topic to parse.

Return Value

  • String: This function should return a string topic.

  • topic: String topic to resolve

subscribe

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.)

Examples

 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);

Return Value

  • String Returns a token you can later use to unsubscribe.

Parameters

  • topic: String|Array List of topics to listen for changes on.

  • callback: Function Callback function to execute. Callback is called with signature (evt, payload, metadata).

  • context: Object Context in which the callback is executed.

  • options: Object (Optional) 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.

publish

Publish data to a topic.

Examples

 // 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 });

Parameters

  • topic: String Topic to publish to.

  • data: ** Data to publish to topic.

unsubscribe

Unsubscribe from changes to a topic.

Example

 cs.unsubscribe('sampleToken');

Parameters

  • token: String The token for topic is returned when you initially subscribe. Pass it here to unsubscribe from that topic.

on

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

off

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

Parameters

trigger

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

Parameters