Presence API for 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

This method requires that the Presence add-on is enabled for your key in the Admin Portal.

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()

* required

Parameter	Description
channels() Type: Vec<String> Default: n/a	The channels to get the details of.
channel_groups() Type: Vec<String> Default: n/a	The channel groups to get the details of.
include_state() Type: bool Default: false	If true, the response will include the presence states of the users for channels/channelGroups.
include_user_ids() Type: bool Default: 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

This method requires that the Presence add-on is enabled for your key in the Admin Portal.

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()

* required

Parameter	Description
user_id() Type: String Default: 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

This method requires that the Presence add-on is enabled for your key in the Admin Portal.

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()

* required

Parameter	Description
set_presence_state() * Type: T: Serialize Default: n/a	The state to set expressed as a JSON object.
channels() Type: Vec<String> Default: n/a	Channels to set state on.
channel_groups() Type: Vec<String> Default: n/a	Channel groups to set state on.
user_id() Type: String Default: 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()

* required

Parameter	Description
channels() Type: Vec<String> Default: n/a	Channels to get state of.
channel_groups() Type: Vec<String> Default: n/a	Channel groups to set state of.
user_id() Type: String Default: 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>.