Presence API for PubNub Cocoa Objective-C SDK
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 Cocoa 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 {
/**
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:
@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
Other Examples
- 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 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 }
- 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 settingUUIDs
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" }
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 Cocoa 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 iferror
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 iferror
occurred during request processing.
Basic Usage
[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
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
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 Cocoa 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.
Request can be resent using: [status retry];
*/
}
}];
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 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)
- (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
uuidon
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 foruuid
.block
PNSetStateCompletionBlock No State modification for user on channel
processing completionblock
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
uuidon
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 completionblock
which pass only one argument - request processing status to report about how data pushing was successful or not.
- (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 completionblock
which pass two arguments: result - in case of successful request processing data field will contain results of client state retrieve operation; status - in case iferror
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 foruuid
will be pulled out.block
PNChannelGroupStateCompletionBlock Yes State audition for user on cahnnel
group
processing completionblock
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
[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
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
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)
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 tonil
.state
NSDictionary No Data which should be bound to specified uuid
onchannels
/channelGroups
.channels
NSArray<NSString *> No List of the channel names which will store provided state
information foruuid
. Not required ifchannelGroups
is set.channelGroups
NSArray<NSString *> No List of channel group names which will store provided state
information foruuid
. Not required ifchannels
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.
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 tonil
.channels
NSArray<NSString *> No List of the channel names from which state information for uuid
will be pulled out. Not required ifchannelGroups
is set.channelGroups
NSArray<NSString *> No List of channel group names from which state information for uuid
will be pulled out. Not required ifchannels
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
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]
*/
}
});