CocoaCocoaiOSObjective-CCocoa Presence API Reference for Realtime Apps

Go to Publish & Subscribe


Requires Presence add-on XRequires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:

http://www.pubnub.com/knowledge-base/discussion/644/how-do-i-enable-add-on-features-for-my-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.
To call Here Now you can use the following method(s) in the Objective-C SDK:
  1. ParameterTypeRequiredDescription
    channelNSStringYesReference on channel for which here now information should be received.
    blockPNHereNowCompletionBlockYesHere 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.
  2. ParameterTypeRequiredDescription
    channelNSStringYesReference on channel for which here now information should be received.
    levelPNHereNowVerbosityLevelYes Reference on one of PNHereNowVerbosityLevel fields to instruct what exactly data it expected in response.
    blockPNHereNowCompletionBlockYesHere 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.
// 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 {

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


@interface PNPresenceChannelGroupHereNowResult : PNResult

// Stores reference on channel group presence request processing information.
@property (nonatomic, nonnull, readonly, strong) PNPresenceChannelGroupHereNowData *data;

@end
  1. Requires Presence add-on XRequires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:

    http://www.pubnub.com/knowledge-base/discussion/644/how-do-i-enable-add-on-features-for-my-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.
    			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];
    		 */
    	}
    }];
    {
    	"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. Requires Presence add-on XRequires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:

    http://www.pubnub.com/knowledge-base/discussion/644/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 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
    		 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];
    		 */
    	}
    }];
    {
        "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. Requires Presence add-on XRequires 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:

    http://www.pubnub.com/knowledge-base/discussion/644/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 PNHereNowUUID client will pull out list of unique identifiers and occupancy information.
    [self.client hereNowWithVerbosity:PNHereNowUUID
    					   completion:^(PNPresenceGlobalHereNowResult *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.
    			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];
    		 */
    	}
    }];
    {
        "total_channels" : 2,
        "total_occupancy" : 3,
        "channels" : {
            "lobby" : {
                "occupancy" : 1,
                "uuids" : [
                    "dara01"
                ]
            },
            "game01" : {
                "occupancy" : 2,
                "uuids" : [
                    "jason01",
                    "jason02"
                ]
            }
        }
    }
  4. Requires Presence add-on XRequires 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:

    http://www.pubnub.com/knowledge-base/discussion/644/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:^(PNPresenceGlobalHereNowResult *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.
    		 */
    	}
    	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];
    		 */
    	}
     }];
    {
        "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"
    }
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.
To do Here Now for Channel Groups you can use the following method(s) in the Objective-C SDK
  1. ParameterTypeRequiredDescription
    groupNSStringYesReference on channel group for which here now information should be received.
    blockPNChannelGroupHereNowCompletionBlockYesHere 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.
  2. ParameterTypeRequiredDescription
    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.
 [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.
		 */
	}
	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 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


@interface PNPresenceChannelGroupHereNowResult : PNResult

// Stores reference on channel group presence request processing information.
@property (nonatomic, nonnull, readonly, strong) PNPresenceChannelGroupHereNowData *data;

@end
Return Occupancy for all channels by calling the hereNowWithCompletion function in your application.
To call Global Here Now you can use the following method(s) in the Objective-C SDK:
  1. ParameterTypeRequiredDescription
    block PNGlobalHereNowCompletionBlockYesHere 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.
  2. ParameterTypeRequiredDescription
    levelPNHereNowVerbosityLevelYesReference on one of PNHereNowVerbosityLevel fields to instruct what exactly data it expected in response.
    blockPNGlobalHereNowCompletionBlockYesHere 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.
 [self.client hereNowWithCompletion:^(PNPresenceGlobalHereNowResult *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.
		 */
	}
	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 objects which is returned by client when Gllobal Here Now API is used:
@interface PNPresenceGlobalHereNowResult : PNResult

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

@end
Requires Presence add-on XRequires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:

http://www.pubnub.com/knowledge-base/discussion/644/how-do-i-enable-add-on-features-for-my-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.
 
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.
To call whereNowUUID you can use the following method(s) in the Objective-C SDK:
  1. ParameterTypeRequiredDescription
    uuidNSStringYes Reference on UUID for which request should be performed.
    blockPNWhereNowCompletionBlockYesWhere 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.
You simply need to define the uuid and the callback function to be used to send the data to as in the example below.
[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.

		 Request can be resent using: [status retry];
		 */
	}
 }];
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
Requires Presence add-on XRequires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:

http://www.pubnub.com/knowledge-base/discussion/644/how-do-i-enable-add-on-features-for-my-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.
  1. ParameterTypeRequiredDescription
    stateNSDictionaryNoReference on dictionary which should be bound to uuid on specified channel. If value is nil, state will be removed for uuid on channel.
    uuidNSStringYesReference on unique user identifier for which state should be bound.
    channelNSStringYesName of the channel which will store provided state information for uuid.
    blockPNSetStateCompletionBlockNo 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.
  2. ParameterTypeRequiredDescription
    stateNSDictionaryNoReference on dictionary which should be bound to uuid on specified channel group. If value is nil, state will be removed for uuid on group.
    uuidNSStringYesReference on unique user identifier for which state should be bound.
    groupNSStringYesName of channel group which will store provided state information for uuid.
    blockPNSetStateCompletionBlockNoState 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.
  1. ParameterTypeRequiredDescription
    uuidNSStringYesReference on unique user identifier for which state should be retrieved.
    channelNSStringYesName of channel from which state information for uuid will be pulled out.
    blockPNChannelStateCompletionBlockYesState 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.
  2. ParameterTypeRequiredDescription
    uuidNSStringYesReference on unique user identifier for which state should be retrieved.
    groupNSStringYesName of channel group from which state information for uuid will be pulled out.
    blockPNChannelGroupStateCompletionBlockYesState 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.
[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.

		 Request can be resent using: [status retry];
		 */
	}
}];
 [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.

		 Request can be resent using: [status retry];
		 */
	}
 }];
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
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
Requires Presence add-on XRequires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:

http://www.pubnub.com/knowledge-base/discussion/644/how-do-i-enable-add-on-features-for-my-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.
  1. ParameterTypeRequiredDescription
    uuidNSStringNoUnique user identifier for which state should be bound. Current PubNub user id will be used by default if not set or set to nil.
    stateNSDictionaryNoData which should be bound to specified uuid on channels / channelGroups.
    channelsNSArray<NSString *>NoList of the channel names which will store provided state information for uuid. Not required if channelGroups is set.
    channelGroupsNSArray<NSString *>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 block which pass only one argument - request status reports state change was successful or not (errorData contains error information in case of failure).
     

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

  1. ParameterTypeRequiredDescription
    uuidNSStringNoUnique user identifier for which state should be retrieved. Current PubNub user id will be used by default if not set or set to nil.
    channelsNSArray<NSString *>NoList of the channel names from which state information for uuid will be pulled out. Not required if channelGroups is set.
    channelGroupsNSArray<NSString *>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 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.
     

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

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]
            */
        }
    });
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]
            */
        }
    });

Go to Channel Groups