AppStax Realtime Channels

Introduction

This page provides a conceptual overview of how to enable realtime communications in your AppStax apps. For more details on how this is done in a particular SDK, check out the SDK in question (iOS, Android or JavaScript)

The underlying programming model for AppStax Realtime Channels is a publish/subscribe model, where a consumer subscribes to data pushed by a producer. The data pushed over a named channel (e.g., public/newsfeed) is received by every consumer who has expressed an interest in receiving it by subscribing to that channel.

AppStax Realtime Channels uses websockets as the underlying transport mechanism. While you could certainly use websockets directly yourself, AppStax gives you many powerful features that enables more rapid development and deployment.

Channel types

There are three types of realtime channels. Each of them serves a different use case.

  • public channels
  • private channels
  • object events

Public channels

Public channels are open to everyone. Data sent on a public channel will be made available to anyone who has subscribed.

Example use case:

  • news feeds
  • chat rooms

Naming of channels

Public channels are named within the namespace public/. Example names are:

  • public/newsfeeds/sports
  • public/newsfeeds/politics
  • public/games/20151020/barcelona_vs_realmadrid

So, whenever a client sends a message to one of these channels, any client who has subscribed to the channel will receive the message.

Public channels do not have to be created or initialized in any way before they can be used. A public channel only exists to the extent that someone is a subscriber. This is in contrast to private channels.

Pattern subscription

It is possible for a client to subscribe to multiple channels that belong to the same root path. For example, in the list of sample public channels above, the following is a pattern subscription that will receive messages to both the public/newsfeeds/sports and public/newsfeeds/politics channels:

  • public/newsfeeds/*

Private channels

Unlike public channels, private channels must be explicitly created.

Example names are :

  • private/devices/axUD13Dds
  • private/devices/mydevice
  • private/organizations/AppStax/rooms/social
  • private/organizations/AppStax/rooms/work

Private channels must be created by a particular enduser. They are then owned by that user. Only the owner of a private channel can grant read/write permissions on the channel, in order for other endusers to publish/subscribe data.

Possible actions on private channels:

Action Explanation
channel.create creates a private channel
channel.delete deletes a private channel
grant.read grants an enduser read/subscribe permissions on the channel
grant.write grants an enduser write/publish permissions on the channel
publish publish a message on the channel
subscribe subscribe to messages on the channel
revoke.read Revoke read/subscribe permissions on a private channel
revoke.write revoke write/publish permissions on a private channel

Private channels are persistent, in the sense that once created they will exist until they are deleted, regardless of whether the connection between the client and the server is closed.

Object channels

Object channels are not explicitly created, but exist independent of any users. Each collection of objects has associated with it a channel through which various object events (object.created, object.updated and object.deleted are published).

Whenever an object in a specific collection is created, updated or deleted, an event is published to all subscribers. In this way it is possible for users (and a ServerCode module!) to be notified of any changes to objects in realtime, without polling the object storage.

Anyone can subscribe to events on a collection, but events are only available to those with access to the specific object (depending on collection and object permissions.)

Event Explanation Example message
object.created An object in the collection was created. The collection is given in the channel property.
javascript {
            "channel":"authors", 
            "event":"object.created", 
            "data":{
                "sysObjectId":"bGVa1Rxh18DEd", 
                "age":42, 
                "title":"a title"
            }
        }
object.updated An object in the collection was updated
javascript {
            "channel":"authors", 
            "event":"object.deleted", 
            "data": {...}
        }
object.deleted An object in the collection was deleted
javascript {
            "channel":"authors", 
            "event":"object.deleted", 
            "data": {...}
        }

Example use cases:

  • update a data view whenever someone else changed the underlying data (See the Realtime Model)
  • notify someone when an object is created
  • push data to 3rd party component when an object is changed

Explore

Learn more about using AppStax Realtime Channels in these tutorials and guides:

JavaScript

Android

iOS

ServerCode