Presence introduction

Presence​

Presence is what enables us to say who (UUID) is on where (channel), when, and how (state).

Identifying users with UUID​

Each REST call uses a URL parameter called UUID. A client's UUID is how the system differentiates one user from another. This is how the user Bob is being differentiated from the user Alice—by UUID.

Presence events​

If you are subscribed to a Presence channel for any given UUID, you will see Presence events occur in real time on that channel. Those events are named:

  • JOIN (joined)
  • LEAVE (explicitly left)
  • TIMEOUT (implicitly left)
  • STATE-CHANGE

Presence events are idempotent – that is, the event will not be repeated (alerted) until it transitions to another event.

Presence states​

For any user, an optional "state" object may be attached to that user's UUID. This state may be set/changed at subscribe (Join) time or anytime during the sustained Join lifecycle. Once a user transitions to TIMEOUT or LEAVE, that user's associated state (if any) is deleted from the server.

Different types of presence calls​

There are three main classes of Presence methods:

  • The streaming, real-time, subscribe-based presence calls, generally implemented as presence().
  • The ad-hoc, on-demand presence calls, such as here_now() and where_now(), get_state(), set_state(), and leave().
  • Long-running heartbeat calls, configured via subscribe initializer and/or via set_hb(), and set_hb_interval().

Streaming presence calls​

To get real-time Presence events as they occur, subscribe to the Presence variant of a channel name.

The variant name is the channel you wish to monitor events for, appended with "-pnpres". For example, to subscribe to Presence for channel foo, under the hood, we subscribe to channel "foo-pnpres."

Aside from the channel name (channel-pnpres) and the structured data that one can expect from a presence call (vs. the relatively random nature of the structured data from user data), nothing is technically different from a presence call vs. a subscribe call.

Ad-hoc, on-demand presence calls​

In addition to the "fire and forget" streaming presence calls, a group of calls can be called anytime to get the current presence and state information for a given UUID.

These methods are:

  • here_now - Who is here, now, on this channel.
  • where_now - Where (which channels) is this UUID currently subscribed on.
  • get_state - Give me the Presence state info for a given UUID.
  • set_state - Set the Presence state info for a given UUID.

Long-running heartbeat calls​

The server keeps a UUID in "Join" while it hears a heartbeat signal from the client within the client's heartbeat timeout, which is 300s by default. When no signal arrives in time, the server will transition the UUID from "Join" to "Timeout."

What counts as a heartbeat signal depends on the keyset's Subscribe heartbeats (implicit) setting, which is off on new keysets. For details, refer to Heartbeats decide when a timeout event fires.

  • When the setting is off, only heartbeat (HB) calls count. A client that subscribes without sending HB calls joins when it subscribes, and then times out while it's still subscribed.
  • When the setting is on, subscribe calls count too. The server expects the client to respond to either an intentionally published message or an empty server "ping" issued every 280s. When this happens as expected, there is no transition – the UUID stays in "Join."

With the setting off, every client needs HB calls to stay present. Some customers also require greater precision than the default timeout to detect UUID's Presence. For both, a heartbeat (HB) call can be set to "ping" from the client every n seconds. When this HB is enabled, a long-running HB process is started on the client, which will connect to the server every HB-Interval (HBI) seconds.

Using this HB scheme, it's possible to inform the Presence system "if you don't hear from me within x seconds, mark me as TIMEOUT." By default, if the client is set for a HB of x, the HBI is automatically set to x / 2 - 1. This enables, by default, that under excellent to average-bad network scenarios, the client should be able to "ping" the Presence server between 1 and 2 times before its HB timeout limit.

The user can always override the default HBI to a lower value, but it's important to remember that making this chattier demands extra battery and network resources.

Heartbeat has no functional effect on the performance or integrity of the client itself. It's only provided for the Presence functionality. Heartbeat is the mechanism used to "ping" back from the client to the server that the client is still online. The heartbeat is only germane to the Presence service.

It affects Presence in the following ways:

  • Heartbeat calls count as heartbeat signals to Presence. Subscribe calls count only when the keyset's Subscribe heartbeats (implicit) setting is on. In both cases, the heartbeat signal registers only on the server RESPONSE.
  • Since a subscribe call can long poll, the server RESPONSE to the subscribe REQUEST may not be immediate (could be many minutes), so even with the setting on, it's not always beneficial to rely on only the subscribe call as the heartbeat.
  • Since the server will RESPOND immediately to the client HB REST API call REQUEST, the heartbeat call is the reliable method for registering heartbeats with the Presence system.

Transitioning between presence events​

Non-Present to present (emitting a join event)​

  • To be "Present", you must go from "Non-Present" to "Present" by subscribing to a channel and/or sending heartbeats to that channel.
  • Going from "Non-Present" to "Present" emits a "JOIN" event within the Presence system.
  • If the system continues to hear heartbeat signals from this client within HEARTBEAT timeout seconds, you will remain "Present." Subscribe requests are heartbeat signals only when the keyset's Subscribe heartbeats (implicit) setting is on.
  • If the client is not currently "JOINED" to a channel, a client heartbeat or subscribe call will create a join event.
  • If the client is currently "JOINED" to a channel, and the server hears a heartbeat signal within HEARTBEAT seconds, the server resets the heartbeat timer and keeps the client "JOINED" to the channel.

Present back to not-present (emitting a timeout or leave event)​

  • The client issues a LEAVE REST call and stops sending subscribe requests and heartbeat requests. This will generate a "LEAVE" Presence event.
  • The client does not issue a LEAVE REST call, but the server no longer receives heartbeat signals from the client within heartbeat timeout seconds. This will generate a "TIMEOUT" Presence event.
  • Once "Not-Present," you can always be "Present" again by repeating this process by subscribing and/or sending a heartbeat.
  • If the client is currently "JOINED" to a channel, and the server does not hear a heartbeat signal within heartbeat seconds, the server will issue a "TIMEOUT" event for that client.