PubNub LogoDocs
SupportContact SalesLoginTry Our APIs

›API Reference

dart

  • Getting Started
  • API Reference

    • Configuration
    • Publish & Subscribe
    • Presence
    • Access Manager
    • Channel Groups
    • Message Persistence
    • Mobile Push
    • Objects
    • Files
    • Message Actions
    • Miscellaneous
  • Troubleshooting
  • Change Log
  • Feature Support
  • Platform Support

Presence API for PubNub 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 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}
) 
ParameterTypeRequiredDefaultDescription
keysetKeysetOptionalOverride for the PubNub default keyset configuration.
usingStringOptionalKeyset name from the keysetStore to be used for this method call.
channelsSet<String>OptionalThe channels to get the 'here now' details of.
channelGroupsSet<String>OptionalThe channelGroups to get the 'here now' details of.
stateInfoStateInfoOptionalfalseIf 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 NameTypeDescription
totalChannelsintTotal channels.
totalOccupancyintTotal occupancy.
channelsMap<String?, ChannelOccupancy>A map with values of ChannelOccupancy for each channel. See ChannelOccupancy for more details.

ChannelOccupancy

Property NameTypeDescription
channelNameStringChannel name.
countintOccupancy of the channel.
uuidsMap<String, OccupantInfo>A map of OccupantInfo, see OccupantInfo for more details.

OccupantInfo

Property NameTypeDescription
uuidStringUUID of the user.
statedynamicState of the user.

Other Examples

  1. Returning State: 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-

    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
    }
    
  2. Return Occupancy Only: 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-

    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"
    }
    
  3. 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 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

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}
) 
ParameterTypeRequiredDefaultDescription
keysetKeysetOptionalOverride for the PubNub default keyset configuration.
usingStringOptionalKeyset name from the keysetStore to be used for this method call.
channelsSet<String>OptionalThe channels to notify.
channelGroupsSet<String>OptionalThe channelGroups to notify.
heartbeatintOptionalIt 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 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

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 {}}
) 
ParameterTypeRequiredDescription
keysetKeysetOptionalOverride for the PubNub default keyset configuration.
usingStringOptionalKeyset name from the keysetStore to be used for this method call.
channelsSet<String>OptionalThe channels to notify.
channelGroupsSet<String>OptionalThe 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 NameTypeDescription
actionStringAction name, for example leave.
← Publish & SubscribeAccess Manager →
  • Here Now
    • Description
    • Method(s)
    • Basic Usage
    • Returns
    • Other Examples
  • Announce Heartbeat
    • Description
    • Method(s)
    • Basic Usage
    • Returns
  • Announce Leave
    • Description
    • Method(s)
    • Basic Usage
    • Returns
© PubNub Inc. - Privacy Policy