Presence API for Rust SDK

Presence lets you track who is online or offline and store custom state information. Presence shows:

• When a user has joined or left a channel
• How many users are subscribed to a particular channel (occupancy)
• Which channels a user or device is subscribed to
• Presence state associated with these users

Learn more about our Presence feature in the Presence overview.

Add any of the following features to Cargo.toml to use this API:

[dependencies]
# full
pubnub = { version = "0.8.0", features = ["full"] }
# Presence
pubnub = { version = "0.8.0", features = ["presence"] }

For a list of all features, refer to Available features.

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.

For information on how to receive presence events and what those events are, refer to Presence Events.

This method returns information about the current state of a channel, including a list of unique user IDs (universally unique identifiers, UUIDs) currently subscribed to the channel and the total occupancy count of the channel.

Cache

This method has a 3-second response cache time.

Method(s)

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

1pubnub
2    .here_now()
3    .channels(Vec<String>)
4    .channel_groups(Vec<String>)
5    .include_state(bool)
6    .include_user_ids(bool)
7    .limit(usize)
8    .offset(Option<usize>)
9    .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.
limit() Type: usize Default: 1000	Maximum number of occupants to return per channel. Valid range: 0-1000. Use 0 to get occupancy counts without user details.
offset() Type: Option<usize> Default: None	Zero-based starting index for pagination. Returns occupants starting from this position in the list. Must be >= 0. Requires limit > 0. Use with limit to paginate through large occupant lists. This parameter is only included in the request when offset > 0.

Sample code

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

1

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.

For information on how to receive presence events and what those events are, refer to Presence Events.

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:

1pubnub
2    .where_now()
3    .user_id(String)
4    .execute()

* required

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

Sample code

1

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.

For information on how to receive presence events and what those events are, refer to Presence Events.

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

1pubnub
2    .set_presence_state(T: Serialize)
3    .channels(Vec<String>)
4    .channel_groups(Vec<String>)
5    .user_id(String)
6    .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

1pubnub
2    .get_presence_state()
3    .channels(Vec<String>)
4    .channel_groups(Vec<String>)
5    .user_id(String)
6    .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.

Sample code

1

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>.