Presence API for PubNub Objective-C 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-on

This method requires that the Presence add-on is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.

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.

Cache

This method has a 3 second response cache time.

Method(s)

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

- (void)hereNowForChannel:(NSString *)channel 
           withCompletion:(PNHereNowCompletionBlock)block;

Parameter	Type	Required	Description
`channel`	NSString	Yes	Reference on `channel` for which here now information should be received.
`block`	PNHereNowCompletionBlock	Yes	Here now processing completion `block` which pass two arguments: result - in case of successful request processing \c data field will contain results of here now operation; \c status - in case if error occurred during request processing.

- (void)hereNowForChannel:(NSString *)channel
            withVerbosity:(PNHereNowVerbosityLevel)level
               completion:(PNHereNowCompletionBlock)block;

Parameter	Type	Required	Description
`channel`	NSString	Yes	Reference on `channel` for which here now information should be received.
`level`	PNHereNowVerbosityLevel	Yes	Reference on one of PNHereNowVerbosityLevel fields to instruct what exactly data it expected in response.
`block`	PNHereNowCompletionBlock	Yes	Here now processing completion `block` which pass two arguments: result - in case of successful request processing \c data field will contain results of here now operation; \c status - in case if error occurred during request processing.

Basic Usage

Get a list of uuids subscribed to channel

// With PNHereNowUUID client will pull out list of unique identifiers and occupancy information.
[self.client hereNowForChannel: @"my_channel" withVerbosity:PNHereNowUUID
                    completion:^(PNPresenceChannelHereNowResult *result,
                                 PNErrorStatus *status) {

    // Check whether request successfully completed or not.
    if (!status) {

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

Response

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

@interface PNPresenceGlobalHereNowData : PNServiceData

// Active channels list.
@property (nonatomic, readonly, strong) NSDictionary$lt;NSString *, NSDictionary *> *channels;
// Total number of active channels.
@property (nonatomic, readonly, strong) NSNumber *totalChannels;
// Total number of subscribers.
@property (nonatomic, readonly, strong) NSNumber *totalOccupancy;

@end

@interface PNPresenceChannelGroupHereNowData : PNPresenceGlobalHereNowData

@end

show all 21 lines

Other Examples

Returning State

Requires Presence add-on

This method requires that the Presence add-on is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.

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

    if (!status) {

        /**
            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.
show all 30 lines

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

This method requires that the Presence add-on is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.

You can return only the occupancy information for a single channel by specifying the channel and setting UUIDs to false:

// With PNHereNowOccupancy client will pull out only occupancy information.
[self.client hereNowForChannel: @"my_channel" withVerbosity:PNHereNowOccupancy
                    completion:^(PNPresenceChannelHereNowResult *result,
                                    PNErrorStatus *status) {
    if (!status) {

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

        /**
            Handle presence audit error. Check 'category' property
show all 23 lines

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" ],
show all 23 lines

Here Now for Channel Groups

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 Objective-C SDK:

- (void)hereNowForChannelGroup:(NSString *)group 
                withCompletion:(PNChannelGroupHereNowCompletionBlock)block;

Parameter	Type	Required	Description
`group`	NSString	Yes	Reference on `channel` `group` for which here now information should be received.
`block`	PNChannelGroupHereNowCompletionBlock	Yes	Here now processing completion `block` which pass two arguments: result - in case of successful request processing data field will contain results of here now operation; status - in case if `error` occurred during request processing.

- (void)hereNowForChannelGroup:(NSString *)group 
                 withVerbosity:(PNHereNowVerbosityLevel)level 
                    completion:(PNChannelGroupHereNowCompletionBlock)block;

Parameter	Type	Required	Description
`group`	NSString	Yes	Reference on `channel` `group` for which here now information should be received.
`level`	PNHereNowVerbosityLevel	Yes	Reference on one of `PNHereNowVerbosityLevel` fields to instruct what exactly data it expected in response.
`block`	PNChannelGroupHereNowCompletionBlock	Yes	Here now processing completion `block` which pass two arguments: result - in case of successful request processing data field will contain results of here now operation; status - in case if `error` occurred during request processing.

Basic Usage

Here Now for Channel Groups

[self.client hereNowForChannelGroup:@"my_group"
                      withCompletion:^(PNPresenceChannelGroupHereNowResult *result,
                                       PNErrorStatus *status) {

    if (!status) {

        /**
         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.
show all 29 lines

Response

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

@interface PNPresenceGlobalHereNowData : PNServiceData

// Active channels list.
@property (nonatomic, readonly, strong) NSDictionary$lt;NSString *, NSDictionary *> *channels;
// Total number of active channels.
@property (nonatomic, readonly, strong) NSNumber *totalChannels;
// Total number of subscribers.
@property (nonatomic, readonly, strong) NSNumber *totalOccupancy;

@end

@interface PNPresenceChannelGroupHereNowData : PNPresenceGlobalHereNowData

@end

show all 21 lines

Where Now

Requires Presence add-on

This method requires that the Presence add-on is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.

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.

Timeout events

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 Objective-C SDK:

- (void)whereNowUUID:(NSString *)uuid 
      withCompletion:(PNWhereNowCompletionBlock)block;

Parameter	Type	Required	Description
`uuid`	NSString	Yes	Reference on `UUID` for which request should be performed.
`block`	PNWhereNowCompletionBlock	Yes	Where now processing completion `block` which pass two arguments: result - in case of successful request processing data field will contain results of where now operation; status - in case if error occurred during request processing.

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:^(PNPresenceWhereNowResult *result,
                                                            PNErrorStatus *status) {

    if (!status) {

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

show all 19 lines

Response

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

@interface PNPresenceWhereNowData : PNServiceData

// List of channels on which client subscribed.
@property (nonatomic, readonly, strong) NSArray<NSString *> *channels;

@end

@interface PNPresenceWhereNowResult : PNResult

// Stores reference on client presence request processing information.
@property (nonatomic, readonly, strong) PNPresenceWhereNowData *data;

@end

User State

Requires Presence add-on

This method requires that the Presence add-on is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.

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

- (void)setState:(nullable NSDictionary<NSString *, id> *)state 
         forUUID:(NSString *)uuid 
       onChannel:(NSString *)channel 
  withCompletion:(nullable PNSetStateCompletionBlock)block;

Parameter	Type	Required	Description
`state`	NSDictionary	No	Reference on dictionary which should be bound to `uuid` on specified channel.`If value is nil, state will be removed for` uuid `on` channel.
`uuid`	NSString	Yes	Reference on unique user identifier for which `state` should be bound.
`channel`	NSString	Yes	Name of the `channel` which will store provided state information for `uuid`.
`block`	PNSetStateCompletionBlock	No	State modification for user on `channel` processing completion `block` which pass only one argument - request processing status to report about how data pushing was successful or not.

- (void)setState:(nullable NSDictionary<NSString *, id> *)state 
           forUUID:(NSString *)uuid
    onChannelGroup:(NSString *)group
    withCompletion:(nullable PNSetStateCompletionBlock)block;

Parameter	Type	Required	Description
`state`	NSDictionary	No	Reference on dictionary which should be bound to `uuid` on specified channel group.`If value is nil, state will be removed for` uuid `on` group.
`uuid`	NSString	Yes	Reference on unique user identifier for which `state` should be bound.
`group`	NSString	Yes	Name of channel group which will store provided state information for `uuid`.
`block`	PNSetStateCompletionBlock	No	State modification for user on `channel` processing completion `block` which pass only one argument - request processing status to report about how data pushing was successful or not.

Get State

- (void)stateForUUID:(NSString *)uuid
           onChannel:(NSString *)channel
      withCompletion:(PNChannelStateCompletionBlock)block;

Parameter	Type	Required	Description
`uuid`	NSString	Yes	Reference on unique user identifier for which state should be retrieved.
`channel`	NSString	Yes	Name of channel from which state information for `uuid` will be pulled out.
`block`	PNChannelStateCompletionBlock	Yes	State audition for user on `cahnnel` processing completion `block` which pass two arguments: result - in case of successful request processing data field will contain results of client state retrieve operation; status - in case if `error` occurred during request processing.

- (void)stateForUUID:(NSString *)uuid
      onChannelGroup:(NSString *)group
      withCompletion:(PNChannelGroupStateCompletionBlock)block;

Parameter	Type	Required	Description
`uuid`	NSString	Yes	Reference on unique user identifier for which state should be retrieved.
`group`	NSString	Yes	Name of `channel` `group` from which state information for `uuid` will be pulled out.
`block`	PNChannelGroupStateCompletionBlock	Yes	State audition for user on `cahnnel` `group` processing completion `block` which pass two arguments: result - in case of successful request processing data field will contain results of client state retrieve operation; status - in case if error occurred during request processing.

Basic Usage

Set State

[self.client setState: @{@"Key": @"Value"} forUUID:self.client.uuid onChannel: @"my_channel"
       withCompletion:^(PNClientStateUpdateStatus *status) {

    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.

show all 19 lines

Get State

[self.client stateForUUID:self.client.uuid onChannel:@"chat"
            withCompletion:^(PNChannelClientStateResult *result, PNErrorStatus *status) {

    if (!status) {

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

show all 19 lines

Response

Set State

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

@interface PNClientStateUpdateData : PNChannelClientStateData

@end

@interface PNClientStateUpdateStatus : PNErrorStatus

// Stores reference on client state for channel request processing information.
@property (nonatomic, nonnull, readonly, strong) PNClientStateUpdateData *data;

@end

Get State

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

@interface PNChannelClientStateData : PNServiceData

// User-provided client state information.
@property (nonatomic, readonly, strong) NSDictionary<NSString *, id> *state;

@end

@interface PNChannelClientStateResult : PNResult

// Stores reference on client state for channel request processing information.
@property (nonatomic, readonly, strong) PNChannelClientStateData *data;

@end

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

@interface PNChannelGroupClientStateData : PNServiceData

// Multi channel client state information.
@property (nonatomic, readonly, strong) NSDictionary<NSString *, NSDictionary *> *channels;

@end

@interface PNChannelGroupClientStateResult : PNResult

// Stores reference on client state for channel group request processing information.
@property (nonatomic, readonly, strong) PNChannelGroupClientStateData *data;

@end

User State (Builder Pattern)

Requires Presence add-on

This method requires that the Presence add-on is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.

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

state()
    .set()
    .uuid(NSString *)
    .state(NSDictionary *)
    .channels(NSArray<NSString *> *)
    .channelGroups(NSArray<NSString *> *)
    .performWithCompletion(PNSetStateCompletionBlock);

Parameter	Type	Required	Description
`uuid`	NSString	No	Unique 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`	NSDictionary	No	Data which should be bound to specified `uuid` on `channels` / `channelGroups`.
`channels`	`NSArray<NSString *>`	No	List of the channel names which will store provided `state` information for `uuid`. Not required if `channelGroups` is set.
`channelGroups`	`NSArray<NSString *>`	No	List of channel group names which will store provided `state` information for `uuid`. Not required if `channels` is set.
`completion`	PNSetStateCompletionBlock	No	State modification for user on channel / channel group completion block 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

state()
    .audit()
    .uuid(NSString *)
    .channels(NSArray<NSString *> *)
    .channelGroups(NSArray<NSString *> *)
    .performWithCompletion(PNGetStateCompletionBlock);

Parameter	Type	Required	Description
`uuid`	NSString	No	Unique 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`	`NSArray<NSString *>`	No	List of the channel names from which state information for `uuid` will be pulled out. Not required if `channelGroups` is set.
`channelGroups`	`NSArray<NSString *>`	No	List of channel group names from which state information for `uuid` will be pulled out. Not required if `channels` is set.
`completion`	PNGetStateCompletionBlock	Yes	State audition for user on channel / channel group completion block 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(^(PNClientStateUpdateStatus *status) {

        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]
show all 18 lines

Get State

self.client.state().audit().uuid(@"PubNub")
    .channels(@[@"channel1", @"channel12"])
    .channelGroups(@[@"group1", @"group2"])
    .performWithCompletion(^(PNClientStateGetResult *result, PNErrorStatus *status) {

        if (!status.isError) {
            // 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]
show all 18 lines

Here Now​

Requires Presence add-on

Cache

Method(s)​

Basic Usage​

Get a list of uuids subscribed to channel​

Response​

Other Examples​

Returning State​

Requires Presence add-on

Example Response​

Return Occupancy Only​

Requires Presence add-on

Example Response​

Here Now for Channel Groups​

Method(s)​

Basic Usage​

Here Now for Channel Groups​

Response​

Where Now​

Requires Presence add-on

Timeout events

Method(s)​

Basic Usage​

Get a list of channels a UUID is subscribed to​

Response​

User State​

Requires Presence add-on

Method(s)​

Set State​

Get State​

Basic Usage​

Set State​

Get State​

Response​

Set State​

Get State​

User State (Builder Pattern)​

Requires Presence add-on

Method(s)​

Set State​

Note

Get State​

Note

Basic Usage​

Set State​

Get State​

Here Now

Method(s)

Basic Usage

Get a list of uuids subscribed to channel

Response

Other Examples

Returning State

Example Response

Return Occupancy Only

Example Response

Here Now for Channel Groups

Method(s)

Basic Usage

Here Now for Channel Groups

Response

Where Now

Method(s)

Basic Usage

Get a list of channels a UUID is subscribed to

Response

User State

Method(s)

Set State

Get State

Basic Usage

Set State

Get State

Response

Set State

Get State

User State (Builder Pattern)

Method(s)

Set State

Get State

Basic Usage

Set State

Get State