Presence API for Dart 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.
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 hereNow()
function in your application.
Cache
This method has a 3 second response cache time.
Method(s)
To call Here Now
you can use the following methods in the Dart SDK:
pubnub.hereNow(
{Keyset? keyset,
String? using,
Set<String> channels = const {},
Set<String> channelGroups = const {},
StateInfo? stateInfo}
)
Parameter | Description |
---|---|
keyset Type: Keyset Default: n/a | Override for the PubNub default keyset configuration. |
using Type: String Default: n/a | Keyset name from the keysetStore to be used for this method call. |
channels Type: Set<String> Default: n/a | The channels to get the 'here now' details of. |
channelGroups Type: Set<String> Default: n/a | The channelGroups to get the 'here now' details of. |
stateInfo Type: StateInfo Default: false | If true , the response will include the presence states of the users for channels /channelGroups . |
Basic Usage
Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
Get a list of UUIDs subscribed to channel
import 'package:pubnub/pubnub.dart';
void main() async {
// Create PubNub instance with default keyset.
var pubnub = PubNub(
defaultKeyset: Keyset(
subscribeKey: 'demo',
publishKey: 'demo',
userId: UserId('myUniqueUserId'),
),
);
// Channel to get presence information
String channel = 'my_channel';
show all 28 linesReturns
The hereNow()
operation returns a HereNowResult
which contains the following operations:
Property Name | Type | Description |
---|---|---|
totalChannels | int | Total channels. |
totalOccupancy | int | Total occupancy. |
channels | Map<String?, ChannelOccupancy> | A map with values of ChannelOccupancy for each channel. See ChannelOccupancy for more details. |
ChannelOccupancy
Property Name | Type | Description |
---|---|---|
channelName | String | Channel name. |
count | int | Occupancy of the channel. |
uuids | Map<String, OccupantInfo> | A map of OccupantInfo , see OccupantInfo for more details. |
OccupantInfo
Property Name | Type | Description |
---|---|---|
uuid | String | UUID of the user. |
state | dynamic | State of the user. |
Other Examples
Returning State
Requires Presence
This method requires that the Presence add-on is enabled for your key in the Admin Portal.
var result =
await pubnub.hereNow(channels: {'my_channel'}, stateInfo: StateInfo.all);
Example response:
{
"status" : 200,
"message" : "OK",
"service" : "Presence",
"uuids" : [
{
"uuid" : "myUUID0"
},
{
"state" : {
"abcd" : {
"age" : 15
}
},
"uuid" : "myUUID1"
show all 38 linesReturn Occupancy Only
Requires Presence
This method requires that the Presence add-on is enabled for your key in the Admin Portal.
You can return only the occupancy
information for a single channel by specifying the channel and setting UUIDs
to false:
var result =
await pubnub.hereNow(channels: {'my_channel'});
Example response:
{
"status": 200,
"message": "OK",
"payload": {
"channels": {
"81d8d989-b95f-443c-a726-04fac323b331": {
"uuids": [ "70fc1140-uuid-4abc-85b2-ff8c17b24d59" ],
"occupancy": 1
},
"81b7a746-d153-49e2-ab70-3037a75cec7e": {
"uuids": [ "91363e7f-uuid-49cc-822c-52c2c01e5928" ],
"occupancy": 1
},
"c068d15e-772a-4bcd-aa27-f920b7a4eaa8": {
"uuids": [ "ccfac1dd-uuid-4afd-9fd9-db11aeb65395" ],
show all 23 linesHere Now for Channel Groups
var result = await pubnub.hereNow(channelGroups: {'cg1'});
Example response:
{
occupancy : 4,
uuids : ['123123234t234f34fuuid', '143r34f34t34fq34quuid', '23f34d3f4rq34r34ruuid', 'w34tcw45t45tcw435uuid']
}
Announce Heartbeat
Requires Presence
This method requires that the Presence add-on is enabled for your key in the Admin Portal.
A device linked to the UUID in the keyset can notify channels
and channelGroups
about its presence.
Method(s)
To call Announce Heartbeat
you can use the following methods in the Dart SDK:
pubnub.announceHeartbeat(
{Keyset? keyset,
String? using,
Set<String> channels = const {},
Set<String> channelGroups = const {},
int? heartbeat}
)
Parameter | Description |
---|---|
keyset Type: Keyset Default: n/a | Override for the PubNub default keyset configuration. |
using Type: String Default: n/a | Keyset name from the keysetStore to be used for this method call. |
channels Type: Set<String> Default: n/a | The channels to notify. |
channelGroups Type: Set<String> Default: n/a | The channelGroups to notify. |
heartbeat Type: int Default: n/a | It is used to set the presence timeout period. It overrides the default value of 300 for Presence Timeout. |
Basic Usage
Announce heartbeat to a single channel
var result = await pubnub.announceHeartbeat(channels: {'my_channel'});
Announce heartbeat to a channel group
var result = await pubnub.announceHeartbeat(channelGroups: {'cg1'});
Returns
The announceHeartbeat()
operation returns a HeartbeatResult
object which does not have actionable data.
Announce Leave
Requires Presence
This method requires that the Presence add-on is enabled for your key in the Admin Portal.
A device linked to the UUID in the keyset can notify channels
and channelGroups
that it has left (is no longer present).
Method(s)
To call Announce Leave
you can use the following methods in the Dart SDK:
pubnub.announceLeave(
{Keyset? keyset,
String? using,
Set<String> channels = const {},
Set<String> channelGroups = const {}}
)
Parameter | Description |
---|---|
keyset Type: Keyset | Override for the PubNub default keyset configuration. |
using Type: String | Keyset name from the keysetStore to be used for this method call. |
channels Type: Set<String> | The channels to notify. |
channelGroups Type: Set<String> | The channelGroups to notify. |
Basic Usage
Announce leave to a single channel
var result = await pubnub.announceLeave(channels: {'my_channel'});
Announce leave to a channel group
var result = await pubnub.announceLeave(channelGroups: {'cg1'});
Returns
The announceLeave()
operation returns a LeaveResult
object which has following property.
Property Name | Type | Description |
---|---|---|
action | String | Action name, for example leave . |
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 UUID
.
State information is supplied as a JSON object of key/value pairs.
Method(s)
Set State
To call Set State
you can use the following method in the Dart SDK:
pubnub.setState(
dynamic state, {
Keyset? keyset,
String? using,
Set<String> channels = const {},
Set<String> channelGroups = const {},
})
Parameter | Description |
---|---|
state *Type: dynamic Default: n/a | The state as a JSON object to set for the specified channels or channel groups. |
keyset Type: Keyset Default: n/a | Override for the PubNub default keyset configuration. |
using Type: String Default: n/a | Keyset name from the keysetStore to be used for this method call. |
channels Type: Set<String> Default: {} | Set of channels to set the state . |
channelGroups Type: Set<String> Default: {} | Set of channelGroups to set the state . |
Get State
To call Get State
you can use the following method in the Dart SDK:
pubnub.getState({
Keyset? keyset,
String? using,
Set<String> channels = const {},
Set<String> channelGroups = const {}
})
Parameter | Description |
---|---|
keyset Type: Keyset Default: n/a | Override for the PubNub default keyset configuration. |
using Type: String Default: n/a | Keyset name from the keysetStore to be used for this method call. |
channels Type: Set<String> Default: {} | Set of channels to fetch the state . |
channelGroups Type: Set<String> Default: {} | Set of channelGroups to fetch the state . |
Basic Usage
Set state
var state = {'is_typing': true};
var result = await pubnub.setState(
state,
channels: {'my_channel'}
);
Get state
var result = await pubnub.getState(
channels: {'ch1', 'ch2', 'ch3'},
channelGroups: {'cg1', 'cg2'}
);
Returns
Set state
The setState
operation returns a SetUserStateResult
object which indicates the success of the operation.
Get state
The getState
operation returns a GetUserStateResult
object which contains the following operations:
Method | Type | Description |
---|---|---|
stateByUUID() | Map<String, Object> | Map of UUIDs and their associated user states. |