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.

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

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

* required

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 lines

Returns

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.

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

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 lines

Return Occupancy Only

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

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

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

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

* required

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.

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

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 {}}
) 

* required

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.

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

Clients can set a dynamic custom state (score, game state, location) for their users on one or more channels and store it on a channel as long as the user stays subscribed.

The state is not persisted, and when the client disconnects, the state data is lost. For more information, refer to Presence State.

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 {},
})

* required

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 {}
})

* required

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	Description
`stateByUUID()` Type: `Map<String, Object>`	Map of `UUIDs` and their associated user states.

Here Now​

Requires Presence

Cache

Method(s)​

Basic Usage​

Reference code

Get a list of UUIDs subscribed to channel​

Returns​

ChannelOccupancy​

OccupantInfo​

Other Examples​

Returning State​

Requires Presence

Return Occupancy Only​

Requires Presence

Here Now for Channel Groups​

Announce Heartbeat​

Requires Presence

Method(s)​

Basic Usage​

Announce heartbeat to a single channel​

Announce heartbeat to a channel group​

Returns​

Announce Leave​

Requires Presence

Method(s)​

Basic Usage​

Announce leave to a single channel​

Announce leave to a channel group​

Returns​

User State​

Requires Presence

Method(s)​

Set State​

Get State​

Basic Usage​

Set state​

Get state​

Returns​

Set state​

Get state​

Here Now

Method(s)

Basic Usage

Get a list of UUIDs subscribed to channel

Returns

ChannelOccupancy

OccupantInfo

Other Examples

Returning State

Return Occupancy Only

Here Now for Channel Groups

Announce Heartbeat

Method(s)

Basic Usage

Announce heartbeat to a single channel

Announce heartbeat to a channel group

Returns

Announce Leave

Method(s)

Basic Usage

Announce leave to a single channel

Announce leave to a channel group

Returns

User State

Method(s)

Set State

Get State

Basic Usage

Set state

Get state

Returns

Set state

Get state