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.

Channel Background

Channel notifications are only available for team projects. There are two main use cases for the push channel: event notifications and chat messages.

Event Notifications

Within a multiplayer simulation or world, it is often useful for your project's model to alert the user interface (browser) that something new has happened.

Usually, this "something new" is an event within the project, group, or world, such as:

  • An end user comes online (logs in) or goes offline. (This is especially interesting in a multiplayer world; only available if you have enabled authorization for the channel.)
  • An end user is assigned to a world.
  • An end user updates a variable / makes a decision.
  • An end user creates or updates data stored in the Data API.
  • An operation (method) is called. (This is especially interesting if the model is advanced, for instance, the Vensim step operation is called.)

When these events occur, you often want to have the user interface for one or more end users automatically update with new information.

Chat Messages

Another reason to use the push channel is to allow players (end users) to send chat messages to other players, and to have those messages appear immediately.

Getting Started

For both the event notification and chat message use cases:

  • First, enable channel notifications for your project.
    • Channel notifications are only available for team projects. To enable notifications for your project, update your project settings to turn on the Push Channel setting, and optionally require authorization for the channel.
  • Then, instantiate an Epicenter Channel Manager.
  • Next, get the channel with the scope you want (user, world, group, data).
  • Finally, use the channel's subscribe() and publish() methods to subscribe to topics or publish data to topics.

Here's an example of those last three steps (instantiate, get channel, subscribe):

var cm = new F.manager.ChannelManager();
var gc = cm.getGroupChannel();
gc.subscribe('', function(data) { console.log(data); });
gc.publish('', { message: 'a new message to the group' });

For a more detailed example, see a complete publish and subscribe example.

For details on what data is published automatically to which channels, see Automatic Publishing of Events.

Creating an Epicenter Channel Manager

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

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. 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 group are also online.

Note that the presence channel is tracking all end users in a group. In particular, if the project additionally splits each group into worlds, this channel continues to show notifications for all end users in the group (not restricted by worlds).

Example

var cm = new F.manager.ChannelManager();
var pc = cm.getPresenceChannel(); 
pc.subscribe('', function (data) {
     // 'data' is the entire message object to the channel; 
     // parse for information of interest
     if (data.data.subType === 'disconnect') {
          console.log('user ', data.data.user.userName, 'disconnected at ', data.data.date);
     }
     if (data.data.subType === 'connect') {
          console.log('user ', data.data.user.userName, 'connected at ', data.data.date);
     }
});

Return Value

Parameters

  • groupName: String (Optional) Group the end user is 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.