Push Channels
Push channel messages are sent by the Epicenter platform about events related to Epicenter entities, such as world, group, run, or vault. These notifications can be received and handled in your application code. The type of entity the channel is related to is defined by the push category.
Epicenter's push channels use CometD and the BAYEUX protocol under the hood.
To facilitate messaging between the application users, use Chat rooms.
For a detailed description of how push channels are implemented in the Epicenter libs, read the push channel reference pages.
Example use cases
- When the facilitator changes a game setting, the participants need to know. The settings can be stored in a vault. If the channel is enabled on the vault, participants can be notified when settings change.
- The facilitator opens the game for play or closes it. The participants receive a notification in the application UI.
- In a multiplayer project, one of the players makes changes to a run variable. If the channel is enabled on the run, the other participants can be notified.
- When a new chat message arrives, Epicenter sends a notification to the channel with the push category
CHAT. - When a new user comes online, the facilitator and/or participants can be notified.
Epicenter handles sending out messages over push channels. To ensure that the users of your app receive messages, you need to enable channels in your project.
Enabling push channels
To enable push-channel notifications for specific entities, set allowChannel to true on those entities.
In projects with a Silent phylogeny, you must also set channelEnabled to true on the project level.
Push category
The push category is a property of an Epicenter push channel. It defines the category of the notifications sent to the channel.
The push category is implemented in the JS libraries with the PUSH_CATEGORY enum.
Channel scope
The scope and push category together comprise a channel scope, which defines what the messages on the channel are related to. For example, when users subscribe to a world-scoped channel with a VAULT category, they get vault-related messages about the world referenced by the scope key.
Path
The channel scope is reflected in the channel's path property
The push channel's path is set by the Channel class constructor as /{scope boundary}/{scope key}/{push category}.
Receiving messages
You will need to implement logic in your application to handle incoming messages from Epicenter.
Callback function
Create a callback function that displays the notification or takes another appropriate action when a new message is received on the channel. The callback function you write must take a ChannelMessage object as an argument.
Subscribing users
Call the Channel.subscribe() function and pass it the callback function along with optional arguments.
To unsubscribe a user, call Channel.unsubscribe() or Channel.unsubscribeAll().
Subscriber presence
The channels monitor subscribers' presence. The facilitators can use this information to regroup participants and form new worlds depending on who is online.
For more details, read about the Presence adapter.