Presence API for PubNub Rust SDK

Presence enables you to track the online and offline status of users and devices in real time and store custom state information. Presence provides authoritative information on:

• When a user has joined or left a channel
• Who, and how many, users are subscribed to a particular channel
• Which channel(s) an individual user is subscribed to
• Associated state information for these users

Learn more about our Presence feature here.

Available in features

fullpresence

Here Now

Requires Presence add-on

This method requires that the Presence add-on is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.

You can obtain information about the current state of a channel including a list of unique user IDs currently subscribed to the channel and the total occupancy count of the channel by calling the here_now() function in your application.

Cache

This method has a 3 second response cache time.

Method(s)

To call here_now(), use the following method in the Rust SDK:

pubnub
    .here_now()
    .channels(Vec<String>)
    .channel_groups(Vec<String>)
    .include_state(bool)
    .include_user_ids(bool)
    .execute()

Parameter	Type	Required	Default	Description
channels()	Vec<String>	Either channels() or channel_groups() is required.		The channels to get the details of.
channel_groups()	Vec<String>	Either channels() or channel_groups() is required.		The channel groups to get the details of.
include_state()	bool	Optional	false	If true, the response will include the presence states of the users for channels/channelGroups.
include_user_ids()	bool	Optional	true	If true, the response will include the user IDs of the connected clients.

Basic Usage

Get a list of channels, their occupancy, and individual occupants' states

Returns

The here_now() operation returns a HereNowResult, which contains the following fields:

Field	Type	Description
total_channels	u32	Total number of channels.
total_occupancy	u32	Number of all users in the provided channels.
channels	Vec<HereNowChannel>	A vector with values of HereNowChannel for each channel. Refer to HereNowChannel for more details.

HereNowChannel

Field	Type	Description
name	String	Channel name.
occupancy	u32	Number of all users in the channel.
occupants	Vec<HereNowUser>	A vector of HereNowUser, refer to HereNowUser for more details.

HereNowUser

Field	Type	Description
user_id	String	Id of the user.
state	serde_json::Value	State of the user. If you're not using the default serde serialization framework, this field is of type Vec<u8>.

Where Now

Requires Presence add-on

This method requires that the Presence add-on is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.

You can obtain information about the current list of channels to which a user ID is subscribed to by calling the where_now() function in your application.

Timeout events

If the app is killed/crashes and restarted (or the page containing the PubNub instance is refreshed on the browser) within the heartbeat window no timeout event is generated.

Method(s)

To call where_now(), use the following method in the Rust SDK:

pubnub
    .where_now()
    .user_id(String)
    .execute()

Parameter	Type	Required	Default	Description
user_id()	String	Optional	User ID provided in PubNub config	User ID to get the current channel subscriptions for.

Basic Usage

Returns

The where_now() operation returns a WhereNowResult, which contains the following fields:

Field	Type	Description
channels	Vec<String>	List of channels where the user ID is present.

User State

Requires Presence add-on

This method requires that the Presence add-on is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.

The state API is used to set/get key/value pairs specific to a subscriber user ID.

State information is supplied as a JSON object of key/value pairs.

Presence state format

Presence state must be expressed as a JSON object.

Method(s)

To manage presence state, use any of the following method(s) in the Rust SDK:

Set State

pubnub
    .set_presence_state(T: Serialize)
    .channels(Vec<String>)
    .channel_groups(Vec<String>)
    .user_id(String)
    .execute()

Parameter	Type	Required	Default	Description
set_presence_state()	T: Serialize	Yes		The state to set expressed as a JSON object.
channels()	Vec<String>	Either channels() or channel_groups() is required.		Channels to set state on.
channel_groups()	Vec<String>	Either channels() or channel_groups() is required.		Channel groups to set state on.
user_id()	String	Optional	User ID provided in PubNub config	The user ID to set state for.

Get State

pubnub
    .get_presence_state()
    .channels(Vec<String>)
    .channel_groups(Vec<String>)
    .user_id(String)
    .execute()

Parameter	Type	Required	Default	Description
channels()	Vec<String>	Either channels() or channel_groups() is required.		Channels to get state of.
channel_groups()	Vec<String>	Either channels() or channel_groups() is required.		Channel groups to set state of.
user_id()	String	Optional	User ID provided in PubNub config	The user ID to get state for.

Basic Usage

Returns

The set_presence_state() operation returns a SetStateResult which contains the following fields:

Field	Type	Description
channel	String	The channel the state was set on.
state	serde_json::Value	State of the user. If you're not using the default serde serialization framework, this field is of type Vec<u8>.

The get_presence_state() operation returns a GetStateResult which contains the following fields:

Field	Type	Description
state	Vec<GetStateInfo>	Vector of GetStateInfo objects.

GetStateInfo

The GetStateInfo object contains the following fields:

Field	Type	Description
channel_name	String	The channel name the state was set on.
state	serde_json::Value	State of the user. If you're not using the default serde serialization framework, this field is of type Vec<u8>.