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​

By default, the server expects the client to respond to either an intentionally published message or an empty server "ping" (issued every 270s) within 290s. When this doesn't happen, the server will transition the UUID from "Join" to "Timeout." When this does happen as expected, there is no transition – the UUID stays in "Join."

Some customers require greater precision than 270s to detect UUID's Presence. To fulfill that requirement, an additional 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:

  • Subscribe calls and Heartbeat calls count as heartbeat signals to Presence—but only on the server RESPONSE does the heartbeat signal register.
  • Since a subscribe call can long poll, the server RESPONSE to the subscribe REQUEST may not be immediate (could be many minutes), so 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, using the heartbeat call, in concert with subscribe calls, is the perfect 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 Heartbeats and/or subscribe requests from this client within HEARTBEAT timeout seconds, you will remain "Present."
  • 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 the heartbeat or subscribes 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 subscribe or heartbeat requests 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 the heartbeat or subscribe within heartbeat seconds, the server will issue a "TIMEOUT" event for that client.