Presence API for PubNub Dart SDK

Beta release

This is a beta release. There may be some feature disparity between this and other PubNub SDKs. For more information, visit our blog.

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 add-onRequires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-

Description

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.

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	Type	Required	Default	Description
`keyset`	`Keyset`	Optional		Override for the PubNub default keyset configuration.
`using`	`String`	Optional		Keyset name from the `keysetStore` to be used for this method call.
`channels`	`Set<String>`	Optional		The `channels` to get the 'here now' details of.
`channelGroups`	`Set<String>`	Optional		The `channelGroups` to get the 'here now' details of.
`stateInfo`	`StateInfo`	Optional	`false`	If `true`, the response will include the presence states of the users for `channels`/`channelGroups`.

Basic Usage

Get a list of UUIDs subscribed to channel

var result = await pubnub.hereNow(channels: {'my_channel'});

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:

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"
        },
        {
            "uuid" : "b9eb408c-bcec-uuid-b4c4-fabec057ad0d"
        },
        {
            "state" : {
                "abcd" : {
                    "age" : 15
                }
            },
            "uuid" : "myUUID2"
        },
        {
            "state" : {
                "abcd" : {
                    "age" : 24
                }
            },
            "uuid" : "myUUID9"
        }
    ],
    "occupancy" : 5
}

Return Occupancy Only:

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" ],
                "occupancy": 1
            }
        },
        "total_channels": 3,
        "total_occupancy": 3
    },
    "service": "Presence"
}

Here Now for Channel Groups:

var result = await pubnub.hereNow(channelGroups: {'cg1'});

Example response:

{
    occupancy : 4,
    uuids : ['123123234t234f34fuuid', '143r34f34t34fq34quuid', '23f34d3f4rq34r34ruuid', 'w34tcw45t45tcw435uuid']
}

Announce Heartbeat

Description

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	Type	Required	Description
`keyset`	`Keyset`	Optional	Override for the PubNub default keyset configuration.
`using`	`String`	Optional	Keyset name from the `keysetStore` to be used for this method call.
`channels`	`Set<String>`	Optional	The `channels` to notify.
`channelGroups`	`Set<String>`	Optional	The `channelGroups` to notify.
`heartbeat`	`int`	Optional	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

Description

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	Type	Required	Description
`keyset`	`Keyset`	Optional	Override for the PubNub default keyset configuration.
`using`	`String`	Optional	Keyset name from the `keysetStore` to be used for this method call.
`channels`	`Set<String>`	Optional	The `channels` to notify.
`channelGroups`	`Set<String>`	Optional	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`.