Presence API for PubNub Cocoa Swift SDK

This SDK has been replaced by a new PubNub Swift SDK written purely in Swift. Check it out here

Presence enables you to track the online and offline status of users and devices in real time, as well as 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-on Requires 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 hereNowForChannel function in your application.

Method(s)

To call Here Now you can use the following method(s) in the Swift SDK:

  1. open func hereNowForChannel(_ channel: String, withCompletion closure: PubNub.PNHereNowCompletionBlock)
    ParameterTypeRequiredDescription
    channelStringYesChannel name to retrieve the Here Now information.
    closurePNHereNowCompletionBlockYesThe completion closure has two arguments: result - in case of successful request processing (data field will contain results of presence audition operation); status - in case if error occurred during request processing (errorData contains error information).
     
  2. open func hereNowForChannel(_ channel: String, withVerbosity level: PNHereNowVerbosityLevel, completion closure: PubNub.PNHereNowCompletionBlock)
    ParameterTypeRequiredDescription
    channelStringYesChannel name to retrieve the Here Now information.
    levelPNHereNowVerbosityLevelYesPNHereNowVerbosityLevel enum filters the response based on the value selected.
    closurePNHereNowCompletionBlockYesThe completion closure has two arguments: result - in case of successful request processing (data field will contain results of presence audition operation); status - in case if error occurred during request processing (errorData contains error information).

Basic Usage

Get a list of uuids subscribed to channel: 

// With .UUID client will pull out list of unique identifiers and occupancy information.
self.client.hereNowForChannel("my_channel", withVerbosity: .UUID,
                              completion: { (result, status) in

    if status == nil {

        /**
         Handle downloaded presence information using:
            result.data.uuids - list of uuids.
            result.data.occupancy - total number of active subscribers.
         */
    }
    else {

        /**
         Handle presence audit error. Check 'category' property to find
         out possible reason because of which request did fail.
         Review 'errorData' property (which has PNErrorData data type) of status
         object to get additional information about issue.

         Request can be resent using: status.retry()
         */
    }
})

Response

Response objects which is returned by client when Here Now API for channel used:

open class PNPresenceGlobalHereNowData : PNServiceData {

    // Active channels list.
    open var channels: [String : [AnyHashable : Any]] { get }
    // Total number of active channels.
    open var totalChannels: NSNumber { get }
    // Total number of subscribers.
    open var totalOccupancy: NSNumber { get }
}

open class PNPresenceChannelGroupHereNowData : PNPresenceGlobalHereNowData {

}

open class PNPresenceChannelGroupHereNowResult : PNResult {

    // Stores reference on channel group presence request processing information.
    open var data: PNPresenceChannelGroupHereNowData { get }
}

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- 

    /**
 With .state client aside from occupancy and unique identifiers will will pull out
 state information associated with them.
 */
self.client.hereNowForChannel("my_channel", withVerbosity: .state,
                              completion: { (result, status) in

    if status == nil {

        /**
         Handle downloaded presence information using:
         result.data.uuids - list of uuids. Each uuid entry will have next
                              fields: "uuid" - identifier and "state" if it
                              has been provided.
         result.data.occupancy - total number of active subscribers.
         */
    }
    else {

        /**
         Handle presence audit error. Check 'category' property
         to find out possible reason because of which request did fail.
         Review 'errorData' property (which has PNErrorData data type) of status
         object to get additional information about issue.

         Request can be resent using: status.retry()
         */
    }
})

    Example Response: 

    {
    "status" : 200,
    "message" : "OK",
    "service" : "Presence",
    "uuids" : [
        {
            "uuid" : "myUUID0"
        },
        {
            "state" : {
                "abcd" : {
                    "age" : 15
                }
            },
            "uuid" : "myUUID1"
        },
        {
            "uuid" : "b9eb408c-bcec-4d34-b4c4-fabec057ad0d"
        },
        {
            "state" : {
                "abcd" : {
                    "age" : 15
                }
            },
            "uuid" : "myUUID2"
        },
        {
            "state" : {
                "abcd" : {
                    "age" : 24
                }
            },
            "uuid" : "myUUID9"
        }
    ],
    "occupancy" : 5
}

  2. Return Occupancy Only: Requires Presence add-on Requires 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:

    // With .occupancy client will pull out only occupancy information.
self.client.hereNowForChannel("my_channel", withVerbosity: .occupancy,
                              completion: { (result, status) in

    if status == nil {

        /**
         Handle downloaded presence information using:
             result.data.occupancy - total number of active subscribers.
         */
    }
    else {

        /**
         Handle presence audit error. Check 'category' property
         to find out possible reason because of which request did fail.
         Review 'errorData' property (which has PNErrorData data type) of status
         object to get additional information about issue.

         Request can be resent using: status.retry()
         */
    }
})

    Example Response: 

    {
    "status": 200,
    "message": "OK",
    "payload": {
        "channels": {
            "81d8d989-b95f-443c-a726-04fac323b331": {
                "uuids": [ "70fc1140-22b5-4abc-85b2-ff8c17b24d59" ],
                "occupancy": 1
            },
            "81b7a746-d153-49e2-ab70-3037a75cec7e": {
                "uuids": [ "91363e7f-584b-49cc-822c-52c2c01e5928" ],
                "occupancy": 1
            },
            "c068d15e-772a-4bcd-aa27-f920b7a4eaa8": {
                "uuids": [ "ccfac1dd-b3a5-4afd-9fd9-db11aeb65395" ],
                "occupancy": 1
            }
        },
        "total_channels": 3,
        "total_occupancy": 3
    },
    "service": "Presence"
}

  3. Returning UUIDs and occupancy for all channels: Requires Presence add-onRequires that the Presence add-on is enabled with Global Here Now checked 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 the list of UUIDs and occupancy for all channels by omitting the channel:

    // With .UUID client will pull out list of unique identifiers and occupancy information.
self.client.hereNowWithVerbosity(.UUID, completion: { (result, status) in

    if status == nil {

        /**
         Handle downloaded presence information using:
         result.data.channels - dictionary with active channels and presence
                                 information on each. Each channel will have
                                 next fields: "uuids" - list of subscribers;
                                 "occupancy" - number of active subscribers.
         result.data.totalChannels - total number of active channels.
         result.data.totalOccupancy - total number of active subscribers.
         */
    }
    else {

        /**
         Handle presence audit error. Check 'category' property
         to find out possible reason because of which request did fail.
         Review 'errorData' property (which has PNErrorData data type) of status
         object to get additional information about issue.

         Request can be resent using: status.retry()
         */
    }
})

    Example Response: 

    {
    "total_channels" : 2,
    "total_occupancy" : 3,
    "channels" : {
        "lobby" : {
            "occupancy" : 1,
            "uuids" : [
                "dara01"
            ]
        },
        "game01" : {
            "occupancy" : 2,
            "uuids" : [
                "jason01",
                "jason02"
            ]
        }
    }
}

  4. Return Occupancy for all channels: Requires Presence add-onRequires that the Presence add-on is enabled with Global Here Now checked 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 (Global Here Now) by omitting the channel name

    self.client.hereNowWithCompletion({ (result, status) in

    if status == nil {

        /**
         Handle downloaded presence information using:
            result.data.channels - dictionary with active channels and presence
                                   information on each. Each channel will have
                                   next fields: "uuids" - list of subscribers;
                                   "occupancy" - number of active subscribers.
                                   Each uuids entry has next fields:
                                   "uuid" - identifier and "state" if it has been
                                   provided.
            result.data.totalChannels - total number of active channels.
            result.data.totalOccupancy - total number of active subscribers.
         */
    }
    else {

        /**
         Handle presence audit error. Check 'category' property
         to find out possible reason because of which request did fail.
         Review 'errorData' property (which has PNErrorData data type) of status
         object to get additional information about issue.

         Request can be resent using: status.retry()
         */
    }
})

    Example Response: 

    {
    "status": 200,
    "message": "OK",
    "payload": {
        "channels": {
            "81d8d989-b95f-443c-a726-04fac323b331": {
                "uuids": [ "70fc1140-22b5-4abc-85b2-ff8c17b24d59" ],
                "occupancy": 1
            },
            "81b7a746-d153-49e2-ab70-3037a75cec7e": {
                "uuids": [ "91363e7f-584b-49cc-822c-52c2c01e5928" ],
                "occupancy": 1
            },
            "c068d15e-772a-4bcd-aa27-f920b7a4eaa8": {
                "uuids": [ "ccfac1dd-b3a5-4afd-9fd9-db11aeb65395" ],
                "occupancy": 1
            }
        },
        "total_channels": 3,
        "total_occupancy": 3
    },
    "service": "Presence"
}

Here Now for Channel Groups

Description

Request information about subscribers on specific channel group. This API method will retrieve the list of UUIDs along with their state for each remote data object and the number of subscribers.

Method(s)

To do Here Now for Channel Groups you can use the following method(s) in the Swift SDK:

  1. open func hereNowForChannelGroup(_ group: String, withCompletion closure: PubNub.PNChannelGroupHereNowCompletionBlock)
    ParameterTypeRequiredDescription
    groupStringYesChannel Group name to retrieve the Here Now information.
    closurePNChannelGroupHereNowCompletionBlockYesThe completion closure has two arguments: result - in case of successful request processing (data field will contain results of presence audition operation); status - in case if error occurred during request processing (errorData contains error information).
     
  2. open func hereNowForChannelGroup(_ group: String, withVerbosity level: PNHereNowVerbosityLevel, completion closure: PubNub.PNChannelGroupHereNowCompletionBlock)
    ParameterTypeRequiredDescription
    groupStringYesChannel Group name to retrieve the Here Now information.
    levelPNHereNowVerbosityLevelYesPNHereNowVerbosityLevel enum filters the response based on the value selected.
    closurePNChannelGroupHereNowCompletionBlockYesThe completion closure has two arguments: result - in case of successful request processing (data field will contain results of presence audition operation); status - in case if error occurred during request processing (errorData contains error information).

Basic Usage

Here Now for Channel Groups: 

self.client.hereNowForChannelGroup("my_group", withCompletion: { (result, status) in

    if status == nil {

        /**
         Handle downloaded presence information using:
            result.data.channels - dictionary with active channels and presence information on
                                   each. Each channel will have next fields: "uuids" - list of
                                   subscribers; occupancy - number of active subscribers.
                                   Each uuids entry has next fields: "uuid" - identifier and
                                   "state" if it has been provided.
            result.data.totalChannels - total number of active channels.
            result.data.totalOccupancy - total number of active subscribers.
         */
    }
    else {

        /**
         Handle presence audit error. Check 'category' property
         to find out possible reason because of which request did fail.
         Review 'errorData' property (which has PNErrorData data type) of status
         object to get additional information about issue.

         Request can be resent using: status.retry()
         */
    }
})

Response

Response objects which is returned by client when Here Now API for channel group used:

open class PNPresenceGlobalHereNowData : PNServiceData {

    // Active channels list.
    open var channels: [String : [AnyHashable : Any]] { get }
    // Total number of active channels.
    open var totalChannels: NSNumber { get }
    // Total number of subscribers.
    open var totalOccupancy: NSNumber { get }
}

open class PNPresenceChannelGroupHereNowData : PNPresenceGlobalHereNowData {

}

open class PNPresenceChannelGroupHereNowResult : PNResult {

    // Stores reference on channel group presence request processing information.
    open var data: PNPresenceChannelGroupHereNowData { get }
}

Global Here Now

Description

Return Occupancy for all channels by calling the hereNowWithCompletion function in your application.

Method(s)

To call Global Here Now you can use the following method(s) in the Swift SDK:

  1. open func hereNowWithCompletion(_ closure: PubNub.PNGlobalHereNowCompletionBlock)
    ParameterTypeRequiredDescription
    closurePNGlobalHereNowCompletionBlockYesThe completion closure has two arguments: result - in case of successful request processing (data field will contain results of presence audition operation); status - in case if error occurred during request processing (errorData contains error information).
     
  2. open func hereNowWithVerbosity(_ level: PNHereNowVerbosityLevel, completion closure: PubNub.PNGlobalHereNowCompletionBlock)
    ParameterTypeRequiredDescription
    levelPNHereNowVerbosityLevelYesPNHereNowVerbosityLevel enum filters the response based on the value selected.
    closurePNGlobalHereNowCompletionBlockYesThe completion closure has two arguments: result - in case of successful request processing (data field will contain results of presence audition operation); status - in case if error occurred during request processing (errorData contains error information).

Basic Usage

self.client.hereNowWithCompletion({ (result, status) in

    if status == nil {

        /**
         Handle downloaded presence information using:
            result.data.channels - dictionary with active channels and presence
                                   information on each. Each channel will have
                                   next fields: "uuids" - list of subscribers;
                                   "occupancy" - number of active subscribers.
                                   Each uuids entry has next fields:
                                   "uuid" - identifier and "state" if it has been
                                   provided.
            result.data.totalChannels - total number of active channels.
            result.data.totalOccupancy - total number of active subscribers.
         */
    }
    else {

        /**
         Handle presence audit error. Check 'category' property
         to find out possible reason because of which request did fail.
         Review 'errorData' property (which has PNErrorData data type) of status
         object to get additional information about issue.

         Request can be resent using: status.retry()
         */
    }
})

Response

Response objects which is returned by client when Gllobal Here Now API is used:

open class PNPresenceGlobalHereNowResult : PNResult {

    // Stores reference on global presence request processing information.
    open var data: PNPresenceGlobalHereNowData { get }
}

Where Now

Requires Presence add-on Requires 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 list of channels to which a UUID is subscribed to by calling the whereNowUUID function in your application.

Note

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 whereNowUUID you can use the following method(s) in the Swift SDK:

  1. open func whereNowUUID(_ uuid: String, withCompletion closure: PubNub.PNWhereNowCompletionBlock)
    ParameterTypeRequiredDescription
    uuidStringYesThe UUID for which request should be performed.
    closurePNWhereNowCompletionBlockYesThe completion closure which will be called when the processing is complete, has two arguments: result - in case of successful processing (data will contain results of presence operation); status - in case of error while processing (errorDatacontains error information).

Basic Usage

You simply need to define the uuid and the callback function to be used to send the data to as in the example below.

Get a list of channels a UUID is subscribed to: 

self.client.whereNowUUID(self.client.uuid(), withCompletion: { (result, status) in

    if status == nil {

        // Handle downloaded presence 'where now' information using: result.data.channels
    }
    else {

        /**
         Handle presence audit error. Check 'category' property
         to find out possible reason because of which request did fail.
         Review 'errorData' property (which has PNErrorData data type) of status
         object to get additional information about issue.

         Request can be resent using: status.retry()
         */
    }
})

Response

Response objects which is returned by client when Where Now API is used:

open class PNPresenceWhereNowData : PNServiceData {

    // List of channels on which client subscribed.
    open var channels: [String] { get }
}

open class PNPresenceWhereNowResult : PNResult {

    // Stores reference on client presence request processing information.
    open var data: PNPresenceWhereNowData { get }
}

User State

Requires Presence add-on Requires 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

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: 

  1. open func setState(_ state: [String : Any]?, forUUID uuid: String, onChannel channel: String, withCompletion closure: PubNub.PNSetStateCompletionBlock? = nil)
    ParameterTypeRequiredDescription
    state[String : Any]NoReference on dictionary which should be bound to uuid on specified channel.If value is nil, state will be removed for uuid on channel.
    uuidStringYesThe unique user identifier for which state should be bound.
    channelStringYesChannel name against which the store state information is stored.
    closurePNChannelStateCompletionBlockNoThe completion closure which will be called when the processing is complete, has one argument: request processing status - in case of error while processing (errorDatacontains error information).
     
  2. open func setState(_ state: [String : Any]?, forUUID uuid: String, onChannelGroup group: String, withCompletion closure: PubNub.PNSetStateCompletionBlock? = nil)
    ParameterTypeRequiredDescription
    state[String : Any]NoReference on dictionary which should be bound to uuid on specified channel group.If value is nil, state will be removed for uuid on group.
    uuidStringYesThe unique user identifier for which state should be bound.
    groupString!YesChannel Group name against which the store state information is stored.
    closurePNChannelStateCompletionBlockNoThe completion closure which will be called when the processing is complete, has one argument: request processing status - in case of error while processing (errorDatacontains error information).

Get State: 

  1. open func stateForUUID(_ uuid: String, onChannel channel: String, withCompletion closure: PubNub.PNChannelStateCompletionBlock)
    ParameterTypeRequiredDescription
    uuidStringYesThe unique user identifier for which state should be retrieved.
    channelStringYesChannel name to retrieve the state information.
    closurePNChannelStateCompletionBlockYesThe completion closure which will be called when the processing is complete, has two arguments: result - in case of successful processing (data will contain results of client state retrieve operation); status - in case of error while processing (errorDatacontains error information).
     
  2. open func stateForUUID(_ uuid: String, onChannelGroup group: String, withCompletion closure: PubNub.PNChannelGroupStateCompletionBlock)
    ParameterTypeRequiredDescription
    uuidStringYesThe unique user identifier for which state should be retrieved.
    groupStringYesChannel Group name to retrieve the state information.
    closurePNChannelGroupStateCompletionBlockYesThe completion closure which will be called when the processing is complete, has two arguments: result - in case of successful processing (data will contain results of client state retrieve operation); status - in case of error while processing (errorDatacontains error information).

Basic Usage

Set State : 

self.client.setState(["Key": "Value"], forUUID: self.client.uuid(), onChannel: "my_channel",
                     withCompletion: { (status) in

    if !status.isError {

        // Client state successfully modified on specified channel.
    }
    else {

        /**
         Handle client state modification error. Check 'category' property
         to find out possible reason because of which request did fail.
         Review 'errorData' property (which has PNErrorData data type) of status
         object to get additional information about issue.

         Request can be resent using: status.retry()
         */
    }
})

Get State : 

self.client.stateForUUID(self.client.uuid(), onChannel: "chat",
                         withCompletion: { (result, status) in

    if status == nil {

        // Handle downloaded state information using: result.data.state
    }
    else{

        /**
         Handle client state audit error. Check 'category' property
         to find out possible reason because of which request did fail.
         Review 'errorData' property (which has PNErrorData data type) of status
         object to get additional information about issue.

         Request can be resent using: status.retry()
         */
    }
})

Response

Set State :

Response objects which is returned by client when Set State API for channels used:

open class PNClientStateUpdateData : PNChannelClientStateData {

}

open class PNClientStateUpdateStatus : PNErrorStatus {

    // Stores reference on client state for channel request processing information.
    open var data: PNClientStateUpdateData { get }
}

Get State :

Response objects which is returned by client when Get State API for channel used:

open class PNChannelClientStateData : PNServiceData {

    // User-provided client state information.
    open var state: [String : Any] { get }
}

open class PNChannelClientStateResult : PNResult {

    // Stores reference on client state for channel request processing information.
    open var data: PNChannelClientStateData { get }
}

Response objects which is returned by client when Get State API for channel group used:

open class PNChannelGroupClientStateData : PNServiceData {

    // Multi channel client state information.
    open var channels: [String : [AnyHashable : Any]] { get }
}

open class PNChannelGroupClientStateResult : PNResult {

    // Stores reference on client state for channel group request processing information.
    open var data: PNChannelGroupClientStateData { get }
}

User State (Builder Pattern)

Requires Presence add-on Requires 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

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: 

  1. state().set().uuid(String).state([String: Any]).channels([String]).channelGroups([String]).performWithCompletion(PNSetStateCompletionBlock)
    ParameterTypeRequiredDescription
    uuidStringNoUnique user identifier for which state should be bound. Current PubNub user ID will be used by default if not set or set to nil.
    state[String: Any]NoData which should be bound to specified uuid on channels / channelGroups.
    channels[String]NoList of the channel names which will store provided state information for uuid. Not required if channelGroups is set.
    channelGroups[String]NoList of channel group names which will store provided state information for uuid. Not required if channels is set.
    completionPNSetStateCompletionBlockNoState modification for user on channel / channel group completion closure which pass only one argument - request status reports state change was successful or not (errorData contains error information in case of failure).
    Note

    This method uses the builder pattern, you can remove the arguments which are optional.

Get State: 

  1. state().audit().uuid(String).channels([String]).channelGroups([String]).performWithCompletion(PNGetStateCompletionBlock)
    ParameterTypeRequiredDescription
    uuidStringNoUnique user identifier for which state should be retrieved. Current PubNub user ID will be used by default if not set or set to nil.
    channels[String]NoList of the channel names from which state information for uuid will be pulled out. Not required if channelGroups is set.
    channelGroups[String]NoList of channel group names from which state information for uuid will be pulled out. Not required if channels is set.
    completionPNGetStateCompletionBlockYesState audition for user on channel / channel group completion closure which pass two arguments: result - in case of successful request processing data field will contain results of client state retrieve operation; status - in case of error occurred during request processing.
    Note

    This method uses the builder pattern, you can remove the arguments which are optional.

Basic Usage

Set State : 

self.client.state().set().state(["state": "test"])
    .channels(["channel1", "channel12"])
    .channelGroups(["group1", "group2"])
    .performWithCompletion({ (status) in

        if !status.isError {
            // Client state successfully modified on specified channels and groups.
        } else {
            /**
             Handle client state modification error. Check 'category' property
             to find out possible reason because of which request did fail.
             Review 'errorData' property (which has PNErrorData data type) of status
             object to get additional information about issue.

             Request can be resent using: status.retry()
            */
        }
    });

Get State : 

self.client.state().audit().uuid("PubNub")
    .channels(["channel1", "channel12"])
    .channelGroups(["group1", "group2"])
    .performWithCompletion({ (result, status) in

        if status == nil {
            // Handle downloaded state information using: result.data.channels
        } else {
            /**
             Handle client state audit error. Check 'category' property
             to find out possible reason because of which request did fail.
             Review 'errorData' property (which has PNErrorData data type) of status
             object to get additional information about issue.

             Request can be resent using: status.retry()
            */
        }
    });
← Publish & SubscribeChannel Groups →