forio Toggle navigation

Epicenter Channel Manager

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 Epicenter Channel Manager is a wrapper around the (more generic) Channel Manager, to instantiate it with Epicenter-specific defaults. If you are interested in including a notification or chat feature in your project, using an Epicenter Channel Manager is probably the easiest way to get started.

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

To use the Epicenter Channel Manager: instantiate it, get the channel of the scope you want (user, world, or group), then use the channel's subscribe() and publish() methods to subscribe to topics or publish data to topics.

var cm = new F.manager.ChannelManager();
var gc = cm.getGroupChannel();
gc.subscribe('broadcasts', callback);

For additional background on Epicenter's push channel, see the introductory notes on the Push Channel API page.

The parameters for instantiating an Epicenter Channel Manager include:

  • options Object with details about the Epicenter project for this Epicenter Channel Manager instance.
  • options.account The Epicenter account id (Team ID for team projects, User ID for personal projects).
  • options.project Epicenter project id.
  • options.userName Epicenter userName used for authentication.
  • options.userId Epicenter user id used for authentication. Optional; options.userName is preferred.
  • options.token Epicenter token used for authentication. (You can retrieve this using authManager.getToken() from the Authorization Manager.)
  • options.allowAllChannels If not included or if set to false, all channel paths are validated; if your project requires Push Channel Authorization, you should use this option. If you want to allow other channel paths, set to true; this is not common.

Methods

getChannel

Creates and returns a channel, that is, an instance of a Channel Service.

This method enforces Epicenter-specific channel naming: all channels requested must be in the form /{type}/{account id}/{project id}/{...}, where type is one of run, data, user, world, or chat.

Example

 var cm = new F.manager.EpicenterChannelManager();
 var channel = cm.getChannel('/group/acme/supply-chain-game/');

 channel.subscribe('topic', callback);
 channel.publish('topic', { myData: 100 });

Parameters

  • options: Object|String (Optional) If string, assumed to be the base channel url. If object, assumed to be configuration options for the constructor.

getGroupChannel

Create and return a publish/subscribe channel (from the underlying Channel Manager) for the given group. The group must exist in the account (team) and project provided.

There are no notifications from Epicenter on this channel; all messages are user-originated.

Example

var cm = new F.manager.ChannelManager();
var gc = cm.getGroupChannel();
gc.subscribe('broadcasts', callback);

Return Value

Parameters

  • groupName: String (Optional) Group to broadcast to. If not provided, picks up group from current session if end user is logged in.

getWorldChannel

Create and return a publish/subscribe channel (from the underlying Channel Manager) for the given world.

This is typically used together with the World Manager.

Example

var cm = new F.manager.ChannelManager();
var worldManager = new F.manager.WorldManager({
    account: 'acme-simulations',
    project: 'supply-chain-game',
    group: 'team1',
    run: { model: 'model.eqn' }
});
worldManager.getCurrentWorld().then(function (worldObject, worldAdapter) {
    var worldChannel = cm.getWorldChannel(worldObject);
    worldChannel.subscribe('', function (data) {
        console.log(data);
    });
 });

Return Value

Parameters

  • world: String|Object The world object or id.

  • groupName: String (Optional) Group the world exists in. If not provided, picks up group from current session if end user is logged in.

getUserChannel

Create and return a publish/subscribe channel (from the underlying Channel Manager) for the current end user in that user's current world.

This is typically used together with the World Manager. Note that this channel only gets notifications for worlds currently in memory. (See more background on persistence.)

Example

var cm = new F.manager.ChannelManager();
var worldManager = new F.manager.WorldManager({
    account: 'acme-simulations',
    project: 'supply-chain-game',
    group: 'team1',
    run: { model: 'model.eqn' }
});
worldManager.getCurrentWorld().then(function (worldObject, worldAdapter) {
    var userChannel = cm.getUserChannel(worldObject);
    userChannel.subscribe('', function (data) {
        console.log(data);
    });
 });

Return Value

Parameters

  • world: String|Object World object or id.

  • user: String|Object (Optional) User object or id. If not provided, picks up user id from current session if end user is logged in.

  • groupName: String (Optional) Group the world exists in. If not provided, picks up group from current session if end user is logged in.

getPresenceChannel

Create and return a publish/subscribe channel (from the underlying Channel Manager) that automatically tracks the presence of an end user, that is, whether the end user is currently online in this group and world. Notifications are automatically sent when the end user comes online, and when the end user goes offline (not present for more than 2 minutes). Useful in multiplayer games for letting each end user know whether other users in their shared world are also online.

Example

var cm = new F.manager.ChannelManager();
var worldManager = new F.manager.WorldManager({
    account: 'acme-simulations',
    project: 'supply-chain-game',
    model: 'model.eqn'
});
worldManager.getCurrentWorld().then(function (worldObject, worldService) {
    var presenceChannel = cm.getPresenceChannel(worldObject);
    presenceChannel.on('presence', function (evt, notification) {
         console.log(notification.online, notification.userId);
     });
 });

Return Value

Parameters

  • world: String|Object World object or id.

  • userid: String|Object (Optional) User object or id. If not provided, picks up user id from current session if end user is logged in.

  • groupName: String (Optional) Group the world exists in. If not provided, picks up group from current session if end user is logged in.

getDataChannel

Create and return a publish/subscribe channel (from the underlying Channel Manager) for the given collection. (The collection name is specified in the root argument when the Data Service is instantiated.) Must be one of the collections in this account (team) and project.

There are automatic notifications from Epicenter on this channel when data is created, updated, or deleted in this collection. See more on automatic messages to the data channel.

Example

var cm = new F.manager.ChannelManager();
var dc = cm.getDataChannel('survey-responses');
dc.subscribe('', function(data, meta) {
     console.log(data);

     // meta.date is time of change,
     // meta.subType is the kind of change: new, update, or delete
     // meta.path is the full path to the changed data
     console.log(meta);
});

Return Value

Parameters

  • collection: String Name of collection whose automatic notifications you want to receive.