Awareness

The Awareness Service is responsible for tracking the location of users within a client-side application. As users navigate within a client-side application, they are seamlessly joined and removed from channels (or rooms). As users enter and leave a channel, event handling is triggered, allowing the client-side application to learn of other users who are in a channel or when other users enter or leave a channel.

The Awareness Service uses Socket.IO under the hood to provide support for real-time Web Sockets. This allows the client-side application to receive event notifications and results immediately using Web Sockets. The Awareness Service also supports other transport protocols including HTTP polling for compatibility with some HTTP-only architectures such as AWS Elastic Load Balancers.

The Awareness Service is an optional service. Once enabled, it is the responsibility of the client application to send messages back to the Awareness Service to indicate when a principal has joined a channel or left a channel.

Essential Configuration

{
    "awareness": {
        "enabled": <boolean>,
        "type": "<type>",
        "config": {
            ...configuration
        }
    }
}

Enable the Awareness Service

To enable the Awareness Service, including the following config in your configuration:

{
    "awareness": {
        "enabled": true
    }
}

Storage Provider

The Awareness Service requires a backend storage provider to be configured so that channel state can be stored and shared across the servers in your cluster (if you have one).

Memory Provider

By default, the Awareness Service will use a memory provider. This works for a standalone server instance where all requests are routing to the same process. The configuration essentially looks like this:

{
    "awareness": {
        "enabled": true,
        "type": "memory",
        "config": {}
    }
}

Redis Provider

If you are running the Cloud CMS application server in cluster mode, you will want to configure the Redis provider, like this:

{
    "awareness": {
        "enabled": true,
        "type": "redis",
        "config": {
            "host": "{host}",
            "port": {port}
        }
    }
}

Where host and port point to your Redis Server.

Environment Variables

You can also configure the Awareness Service using the following environment variables:

  • CLOUDCMS_AWARENESS_TYPE - either memory or redis

You can configure the Awareness Redis Provider using the following settings:

  • CLOUDCMS_AWARENESS_REDIS_DEBUG_LEVEL - either info, warn, error or debug
  • CLOUDCMS_AWARENESS_REDIS_ENDPOINT - the host
  • CLOUDCMS_AWARENESS_REDIS_PORT - the port

Further, the Awareness Redis Provider will automatically draw from the following global Redis environment variables if you've set them:

  • CLOUDCMS_REDIS_DEBUG_LEVEL - either info, warn, error or debug
  • CLOUDCMS_REDIS_ENDPOINT - the host
  • CLOUDCMS_REDIS_PORT - the port