epicenter-channel-manager | Documentation

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.

Constructor options

Required?	Name	Type	Description
Yes	userName	`string`	Epicenter userName used for authentication.
	userId	`string`	Epicenter user id used for authentication. Optional; `options.userName` is preferred.
	allowAllChannels	`boolean`	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.
	account	`string`	The account id. In the Epicenter UI, this is the Team ID (for team projects) or User ID (for personal projects). Defaults to undefined. If left undefined, taken from the URL.
	project	`string`	The project id. Defaults to undefined. If left undefined, parsed from the URL.
	token	`string`	For projects that require authentication, pass in the user access token (defaults to undefined). If the user is already logged in to Epicenter, the user access token is already set in a cookie and automatically loaded from there. (See more background on access tokens). @see Authentication API Service for getting tokens.
	transport	JQueryAjaxOptions	Options to pass on to the underlying transport layer. All jquery.ajax options are supported.
	server	`object`
	server.host	`string`	The value of `host` is usually the string `api.forio.com`, the URI of the Forio API server. This is automatically set, but you can pass it explicitly if desired. It is most commonly used for clarity when you are hosting an Epicenter project on your own server
	server.protocol	https / http	Defaults to https

Methods

getChannel([options])

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.

Parameters

Required?	Name	Type	Description
	options	`Object / String`	If string, assumed to be the base channel url. If object, assumed to be configuration options for the constructor.

Returns

Channel - Channel instance

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

getGroupChannel([groupName])

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.

Parameters

Required?	Name	Type	Description
	groupName	`string`	Group to broadcast to. If not provided, picks up group from current session if end user is logged in.

Returns

Channel - Channel instance

Example

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

**Return Value**

* *Channel* Returns the channel (an instance of the [Channel Service](../channel-service/)).

getWorldChannel(world[, groupName])

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.

The list of available topics available to subscribe to are:

Topic	Description
ALL	All events
RUN	All Run events
RUN_VARIABLES	Variable sets only
RUN_OPERATIONS	Operation executions only
RUN_RESET	New run attached to the world
PRESENCE	All Presence events
PRESENCE_ONLINE	Online notifications only
PRESENCE_OFFLINE	Offline notifications only
ROLES	All role events
ROLES_ASSIGN	Role assignments only
ROLES_UNASSIGN	Role unassignments
CONSENSUS	Consensus topics

Parameters

Required?	Name	Type	Description
Yes	world	`String / Object`	The world object or id.
	groupName	`string`	Group the world exists in. If not provided, picks up group from current session if end user is logged in.

Returns

Channel - Channel instance

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(worldChannel.TOPICS.RUN, function (data) {
            console.log(data);
        });
     });

getUserChannel(world[, user, groupName])

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

Parameters

Required?	Name	Type	Description
Yes	world	`String / {"id":["string"]}`	World object or id.
	user	`String / Object`	User object or id. If not provided, picks up user id from current session if end user is logged in.
	groupName	`string`	Group the world exists in. If not provided, picks up group from current session if end user is logged in.

Returns

Channel - Channel instance

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

* *Channel* Returns the channel (an instance of the [Channel Service](../channel-service/)).

getPresenceChannel([groupName])

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

Parameters

Required?	Name	Type	Description
	groupName	`string`	Group the end user is in. If not provided, picks up group from current session if end user is logged in.

Returns

Channel - Channel instance

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

* *Channel* Returns the channel (an instance of the [Channel Service](../channel-service/)).

getDataChannel(collection)

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.

Parameters

Required?	Name	Type	Description
Yes	collection	`String`	Name of collection whose automatic notifications you want to receive.

Returns

Channel - Channel instance

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

* *Channel* Returns the channel (an instance of the [Channel Service](../channel-service/)).

getChannel
getGroupChannel
getWorldChannel
getUserChannel
getPresenceChannel
getDataChannel