Configuration API for Objective-C SDK

Complete API reference for building real-time applications on PubNub with the Objective-C Software Development Kit (SDK). This page covers configuration, initialization, and event handling with concise, working examples.

Configuration

PNConfiguration stores settings that control the client's behavior. It includes credentials and options to tailor how the client connects, retries, and processes messages.

Privacy

MAU billing tracks users (Device and MAU) for analytics and billing. PubNub does not track customers using transactions with random UUIDs/UserIDs.

Method(s)

Create a configuration instance with:

1+ (instancetype)configurationWithPublishKey:(NSString *)publishKey 
2                               subscribeKey:(NSString *)subscribeKey;
3                                     userID:(NSString *)userID

* required

Parameter	Description
publishKey * Type: NSString	Publish key. Example: "demo".
subscribeKey * Type: NSString	Subscribe key. Example: "demo".
userID * Type: NSString	User ID. UTF‑8 string, up to 92 characters. Required.
heartbeatNotificationOptions Type: PNHeartbeatNotificationOptions	Heartbeat notifications. Success, Failure (default), All, or None.
stripMobilePayload Type: BOOL	If YES, remove push payload metadata (APNs/FCM) from received messages.
subscribeMaximumIdleTime Type: NSTimeInterval	Max seconds to wait for events. Default: 310.
nonSubscribeRequestTimeout Type: NSTimeInterval	Timeout for non‑subscribe ops, in seconds. Default: 10.
presenceHeartbeatValue Type: NSInteger	Presence timeout (seconds). Defaults to 300. Triggers timeout if no heartbeat.
presenceHeartbeatInterval Type: NSInteger	Heartbeat interval (seconds). Typical: (presenceHeartbeatValue / 2) - 1. Min 3.
keepTimeTokenOnListChange Type: BOOL	Keep previous timetoken on subscribe list change. Default: YES.
catchUpOnSubscriptionRestore Type: BOOL	Catch up on missed events after restore. Default: YES.
applicationExtensionSharedGroupIdentifier Type: NSString	Shared App Group ID for extensions (iOS 8.0+, macOS 10.10+).
requestMessageCountThreshold Type: NSUInteger	Max messages per response before PNRequestMessageCountExceededCategory.
maximumMessagesCacheSize Type: NSUInteger	De‑duplication cache size. Default: 100.
completeRequestsBeforeSuspension Type: BOOL	Finish in‑flight API calls before suspension. Default: YES.
suppressLeaveEvents Type: BOOL	If YES, don’t send presence leave events on unsubscribe.
origin Type: NSString	Custom origin (domain). Example: "ps.pndsn.com".
requestRetry Type: PNRequestRetryConfiguration	Retry policy settings. See requestRetry.
cryptoModule Type: [PNCryptoModule AESCBCCryptoModuleWithCipherKey: NSString randomInitializationVector: BOOL]; [PNCryptoModule legacyCryptoModuleWithCipherKey: NSString randomInitializationVector: BOOL];	Encrypt/decrypt module. Takes cipherKey and useRandomInitializationVector. See cryptoModule.
logLevel Type: PNLogLevel	Minimum log level to capture. Values: PNNoneLogLevel (disabled), PNTraceLogLevel, PNDebugLogLevel, PNInfoLogLevel, PNWarnLogLevel, PNErrorLogLevel. Default: PNNoneLogLevel. See Logging.
enableDefaultConsoleLogger Type: BOOL	Enable the built-in console logger. Default: YES. When YES, log entries print to the Xcode console. When NO, the SDK uses only custom loggers. See Logging.
loggers Type: NSArray<id<PNLogger>>	Array of custom logger implementations conforming to the PNLogger protocol. Custom loggers receive log entries alongside the built-in console logger if the console logger is enabled. See Custom Loggers.
cipherKey Type: NSString	This way of setting this parameter is deprecated, pass it to cryptoModule instead. Key which is used to encrypt messages pushed to PubNub service and decrypt messages received from live feeds on which client subscribed at this moment.
useRandomInitializationVector Type: BOOL	This way of setting this parameter is deprecated, pass it to cryptoModule instead. When YES the initialization vector (IV) is random for all requests (not just for file upload). When NO the IV is hard-coded for all requests except for file upload. By default, using the random initialization vector is enabled.

Disabling random initialization vector

Disable random initialization vector (IV) only for backward compatibility (<4.16.0) with existing applications. Never disable random IV on new applications.

requestRetry

Use PNRequestRetryConfiguration to control retry behavior. For policy details, see Reconnection Policy.

Create a default linear retry policy

1+ (instancetype)configurationWithLinearDelay;

Example

1configuration.requestRetry = [PNRequestRetryConfiguration configurationWithLinearDelay];

Create a linear retry policy with excluded endpoints

1+ (instancetype)configurationWithLinearDelayExcludingEndpoints:(PNEndpoint)endpoints, ...;

Parameter	Description
endpoints Type: PNEndpoint	The endpoints to exclude. For a list of endpoints, inspect NS_ENUM(NSUInteger, PNEndpoint) in the PNStructures file.

Example

1configuration.requestRetry = [PNRequestRetryConfiguration configurationWithLinearDelayExcludingEndpoints:PNMessageSendEndpoint, 0];

Create a linear retry policy with excluded endpoints and custom parameters

1+ (instancetype)configurationWithLinearDelay:(NSTimeInterval)delay
2                                maximumRetry:(NSUInteger)maximumRetry
3                           excludedEndpoints:(PNEndpoint)endpoints, ...;

Parameter	Description
delay Type: NSTimeInterval	Delay in seconds between failed requests.
maximumRetry Type: NSUInteger	How many times to retry before throwing an error.
excludedEndpoints Type: PNEndpoint	The endpoints to exclude. For a list of endpoints, inspect NS_ENUM(NSUInteger, PNEndpoint) in the PNStructures file.

Example

1/// example
2configuration.requestRetry = [PNRequestRetryConfiguration configurationWithLinearDelay:3.f
3                                                                          maximumRetry:3
4                                                                     excludedEndpoints:PNMessageSendEndpoint, PNMessageStorageEndpoint, 0];

Create a default exponential retry policy

1+ (instancetype)configurationWithExponentialDelay;

Example

1configuration.requestRetry = [PNRequestRetryConfiguration configurationWithExponentialDelay];

Create an exponential retry policy with excluded endpoints

1+ (instancetype)configurationWithExponentialDelayExcludingEndpoints:(PNEndpoint)endpoints, ...;

Parameter	Description
endpoints Type: PNEndpoint	The endpoints to exclude. For a list of endpoints, inspect NS_ENUM(NSUInteger, PNEndpoint) in the PNStructures file.

Example

1configuration.requestRetry = [PNRequestRetryConfiguration configurationWithExponentialDelayExcludingEndpoints:PNMessageSendEndpoint, 0];

Create an exponential retry policy with excluded endpoints and custom parameters

1+ (instancetype)configurationWithExponentialDelay:(NSTimeInterval)minimumDelay
2                                     maximumDelay:(NSTimeInterval)maximumDelay
3                                     maximumRetry:(NSUInteger)maximumRetry
4                                excludedEndpoints:(PNEndpoint)endpoints, ...;

Parameter	Description
minimumDelay Type: NSTimeInterval	Base delay in seconds used to calculate the next delay.
maximumDelay Type: NSTimeInterval	Maximum allowed computed delay in seconds between retry attempts.
maximumRetry Type: NSUInteger	How many times to retry before throwing an error.
excludedEndpoints Type: PNEndpoint	The endpoints to exclude. For a list of endpoints, inspect NS_ENUM(NSUInteger, PNEndpoint) in the PNStructures file.

Example

configuration.requestRetry = [PNRequestRetryConfiguration configurationWithExponentialDelay:3.f
                                                                               maximumDelay:120.f
                                                                               maximumRetry:3
                                                                          excludedEndpoints:PNMessageSendEndpoint, PNMessageStorageEndpoint, 0];

cryptoModule

cryptoModule encrypts and decrypts messages and files. From 5.1.3, you can configure the algorithms it uses.

Each SDK includes two options: legacy 128‑bit encryption and recommended 256‑bit AES‑CBC. For background, see Message Encryption and File Encryption.

If you don't set cryptoModule but set cipherKey and useRandomInitializationVector in config, the client uses legacy encryption.

For configuration details and examples, see Encryption.

Legacy encryption with 128-bit cipher key entropy

You don't have to change your encryption configuration if you want to keep using the legacy encryption. If you want to use the recommended 256-bit AES-CBC encryption, you must explicitly set that in PubNub config.

Sample code

Required User ID

Always set the User ID (userID) to uniquely identify the user or device that connects to PubNub. Persist the value and keep it stable for the lifetime of the user or device. If you don't set the userID, the client cannot connect.

1// Basic configuration
2PNConfiguration *config = [PNConfiguration configurationWithPublishKey:@"demo"
3                                                          subscribeKey:@"demo"
4                                                                userID:@"myUniqueUserID"];
5

6// Create a PubNub client instance
7PubNub *client = [PubNub clientWithConfiguration:config];
8

9// Add listener for PubNub events
10[client addListener:self];
11

12// Subscribe to a test channel
13PNSubscribeRequest *subscribeRequest = [PNSubscribeRequest requestWithChannels:@[@"test-channel"]
14                                                                 channelGroups:nil];
15subscribeRequest.observePresence = YES;
16

17[client subscribeWithRequest:subscribeRequest];
18

19// Publish a test message
20PNPublishRequest *publishRequest = [PNPublishRequest requestWithChannel:@"test-channel"];
21publishRequest.message = @{@"message": @"Hello PubNub!"};
22

23[client publishWithRequest:publishRequest withCompletion:^(PNPublishStatus *status) {
24    if (!status.isError) {
25        NSLog(@"✅ Successfully published message! Connection is working.");
26    } else {
27        NSLog(@"❌ Failed to publish message. Error: %@", status.errorData.information);
28    }
29}];
30

31// Required PNEventsListener methods
32- (void)client:(PubNub *)client didReceiveStatus:(PNStatus *)status {
33    // Checking connectivity only using subscribe operation.
34    if (status.operation != PNSubscribeOperation) return;
35    
36    if (status.category == PNConnectedCategory) {
37        NSLog(@"✅ Successfully connected to PubNub!");
38    } else if (status.isError) {
39        NSLog(@"❌ PubNub connection error: %@", status);
40    } else {
41        NSLog(@"Received status: %@", status);
42    }
43}
44

45- (void)client:(PubNub *)client didReceiveMessage:(PNMessageResult *)message {
46    NSLog(@"✅ Received message: %@ on channel: %@", message.data.message, message.data.channel);
47}
48

49- (void)client:(PubNub *)client didReceivePresenceEvent:(PNPresenceEventResult *)event {
50    NSLog(@"Presence event: %@", event);
51}

show all 51 lines

Returns

Returns a configured client configuration instance.

Other examples

Configure logging

Enable logging to monitor SDK (Software Development Kit) activity and troubleshoot issues.

Basic logging configuration

1PNConfiguration *config = [PNConfiguration configurationWithPublishKey:@"demo" 
2                                                          subscribeKey:@"demo"
3                                                                userID:@"myUniqueUserID"];
4

5// Set minimum log level
6config.logLevel = PNDebugLogLevel;
7

8PubNub *client = [PubNub clientWithConfiguration:config];

Change log level at runtime

1// Adjust logging detail after initialization
2[client setLogLevel:PNErrorLogLevel];

Disable console logger

1PNConfiguration *config = [PNConfiguration configurationWithPublishKey:@"demo" 
2                                                          subscribeKey:@"demo"
3                                                                userID:@"myUniqueUserID"];
4config.logLevel = PNDebugLogLevel;
5config.enableDefaultConsoleLogger = NO;  // Disable default logger output to the Xcode console
6

7PubNub *client = [PubNub clientWithConfiguration:config];

Add custom loggers

1PNConfiguration *config = [PNConfiguration configurationWithPublishKey:@"demo" 
2                                                          subscribeKey:@"demo"
3                                                                userID:@"myUniqueUserID"];
4config.logLevel = PNDebugLogLevel;
5config.loggers = @[myCustomLogger];  // Add your PNLogger implementation
6

7PubNub *client = [PubNub clientWithConfiguration:config];

For custom logger implementation examples and best practices, see Logging.

Configure heartbeat notifications

PNConfiguration

1PNConfiguration *config = [PNConfiguration configurationWithPublishKey:@"<pub key>" subscribeKey:@"<sub key>"];
2/**
3    This is where you need to adjust the PNConfiguration object for the types of heartbeat notifications you want.
4    This is a bitmask of options located at https://github.com/pubnub/objective-c/blob/1f1c7a41a3bd8c32b644a6ad98fe179d45397c2b/PubNub/Misc/PNStructures.h#L24
5    */
6config.heartbeatNotificationOptions = PNHeartbeatNotifyAll;
7

8self.client = [PubNub clientWithConfiguration:config];
9[self.client addListener:self];

Listener

1- (void)client:(PubNub *)client didReceiveStatus:(PNStatus *)status {
2

3    if (status.operation == PNHeartbeatOperation) {
4

5        /**
6            Heartbeat operations can in fact have errors, so it is important to check first for an error.
7            For more information on how to configure heartbeat notifications through the status
8            PNObjectEventListener callback, consult http://www.pubnub.com/docs/sdks/objective-c/api-reference/configuration#configuration_basic_usage
9            */
10

11        if (!status.isError) { /* Heartbeat operation was successful. */ }
12        else { /* There was an error with the heartbeat operation, handle here. */ }
13    }
14}

Initialization

Install CocoaPods and follow the Getting Started guide. Then:

1. Create a new Xcode project.

2. Create a Podfile in a new Xcode project root folder

   1pod init

   1platform :ios, '9.0'
   2
   
   3target 'application-target-name' do
   4    use_frameworks!
   5
   
   6    pod "PubNub", "~> 4"
   7end

If you need more pods or targets (for example, a test target), add them to the same Podfile. See the CocoaPods documentation for details.

• Install your pods by running pod install via the command line from the directory that contains your Podfile.

Note

After installing your Pods, you should only be working within the workspace generated by CocoaPods or specified by you in Podfile. Always open the newly generated workspace file, not the original project file!

Import the SDK headers where you use them:

1#import <PubNub/PubNub.h>

Complete application delegate configuration

Add the PNObjectEventListener protocol to AppDelegate in the implementation file's anonymous category:

Required User ID

Always set the User ID (userID) to uniquely identify the user or device that connects to PubNub. Persist the value and keep it stable for the lifetime of the user or device. If you don't set the userID, the client cannot connect.

1#import <PubNub/PubNub.h>
2

3@interface AppDelegate () <PNObjectEventListener>
4

5// Stores reference on PubNub client to make sure what it won't be released.
6@property (nonatomic, strong) PubNub *client;
7

8@end

Description

Initialize the client API before calling any SDK methods. This sets account-level credentials such as publishKey and subscribeKey.

Method(s)

Initialize PubNub with:

Initialize PubNub

1+ (instancetype)clientWithConfiguration:(PNConfiguration *)configuration;

* required

Parameter	Description
configuration * Type: PNConfiguration	Reference on instance which store all user-provided information about how client should operate and handle events.

Initialize with callback queue

1+ (instancetype)clientWithConfiguration:(PNConfiguration *)configuration callbackQueue:(dispatch_queue_t)callbackQueue;

* required

Parameter	Description
configuration * Type: PNConfiguration	Reference on instance which store all user-provided information about how client should operate and handle events.
callbackQueue Type: dispatch_queue_t	Reference on queue which should be used by client for completion block and delegate calls.

Sample code

Initialize the PubNub client API

Required User ID

Always set the User ID (userID) to uniquely identify the user or device that connects to PubNub. Persist the value and keep it stable for the lifetime of the user or device. If you don't set the userID, the client cannot connect.

1PNConfiguration *config = [PNConfiguration configurationWithPublishKey:@"demo"
2                                                                                                      subscribeKey:@"demo"
3                                                                                                                  userID:@"myUserID"];
4config.TLSEnabled = YES;
5self.client = [PubNub clientWithConfiguration:configuration];

Configuration instance

Ensure the same configuration instance (config) is passed to clientWithConfiguration: that you created above. The TLSEnabled property refers to Transport Layer Security (TLS).

Returns

Returns the client instance for invoking APIs such as publish, subscribeToChannels, historyForChannel, and hereNowForChannel.

Other examples

Initialize the client

Required User ID

Always set the User ID (userID) to uniquely identify the user or device that connects to PubNub. Persist the value and keep it stable for the lifetime of the user or device. If you don't set the userID, the client cannot connect.

1PNConfiguration *configuration = [PNConfiguration configurationWithPublishKey:@"demo"
2                                                                    subscribeKey:@"demo"
3                                                                          userID:@"myUserID"];
4

5self.client = [PubNub clientWithConfiguration:configuration];

Initialization for a Read-Only client

In the case where a client will only read messages and never publish to a channel, you can simply omit the publishKey when initializing the client:

Required User ID

Always set the User ID (userID) to uniquely identify the user or device that connects to PubNub. Persist the value and keep it stable for the lifetime of the user or device. If you don't set the userID, the client cannot connect.

1PNConfiguration *configuration = [PNConfiguration configurationWithPublishKey:@""
2                                                                    subscribeKey:@"demo"
3                                                                          userID:@"myUserID"];
4self.client = [PubNub clientWithConfiguration:configuration];

Event listeners

Use listeners to receive connectivity, message, presence, object, and file events. Add listeners before you subscribe or publish.

Add listeners

Your listener class must conform to the PNEventsListener protocol to receive callbacks.

1// Adding listener.
2[pubnub addListener:self];
3

4// Callbacks listed below.
5

6- (void)client:(PubNub *)pubnub didReceiveMessage:(PNMessageResult *)message {
7    NSString *channel = message.data.channel; // Channel on which the message has been published
8    NSString *subscription = message.data.subscription; // Wild-card channel or channel on which PubNub client actually subscribed
9    NSNumber *timetoken = message.data.timetoken; // Publish timetoken
10    id msg = message.data.message; // Message payload
11    NSString *publisher = message.data.publisher; // Message publisher
12}
13

14- (void)client:(PubNub *)pubnub didReceiveSignal:(PNSignalResult *)signal {
15    NSString *channel = message.data.channel; // Channel on which the signal has been published
16    NSString *subscription = message.data.subscription; // Wild-card channel or channel on which PubNub client actually subscribed
17    NSNumber *timetoken = message.data.timetoken; // Signal timetoken
18    id msg = message.data.message; // Signal payload
19    NSString *publisher = message.data.publisher; // Signal publisher
20}
21

22- (void)client:(PubNub *)pubnub didReceiveMessageAction:(PNMessageActionResult *)action {
23    NSString *channel = action.data.channel; // Channel on which the message has been published
24    NSString *subscription = action.data.subscription; // Wild-card channel or channel on which PubNub client actually subscribed
25    NSString *event = action.data.event; // Can be: added or removed
26    NSString *type = action.data.action.type; // Message action type
27    NSString *value = action.data.action.value; // Message action value
28    NSNumber *messageTimetoken = action.data.action.messageTimetoken; // Timetoken of the original message
29    NSNumber *actionTimetoken = action.data.action.actionTimetoken; // Timetoken of the message action
30    NSString *uuid = action.data.action.uuid; // UUID of user which added / removed message action
31}
32

33- (void)client:(PubNub *)pubnub didReceivePresenceEvent:(PNPresenceEventResult *)event {
34    NSString *channel = message.data.channel; // Channel on which presence changes
35    NSString *subscription = message.data.subscription; // Wild-card channel or channel on which PubNub client actually subscribed
36    NSString *presenceEvent = event.data.presenceEvent; // Can be: join, leave, state-change, timeout or interval
37    NSNumber *occupancy = event.data.presence.occupancy; // Number of users subscribed to the channel (not available for state-change event)
38    NSNumber *timetoken = event.data.presence.timetoken; // Presence change timetoken
39    NSString *uuid = event.data.presence.uuid; // UUID of user for which presence change happened
40

41    // Only for 'state-change' event
42    NSDictionary *state = event.data.presence.state; // User state (only for state-change event)
43

44    // Only for 'interval' event
45    NSArray<NSString *> *join = event.data.presence.join; // UUID of users which recently joined channel
46    NSArray<NSString *> *leave = event.data.presence.leave; // UUID of users which recently leaved channel
47    NSArray<NSString *> *timeout = event.data.presence.timeout; // UUID of users which recently timed out on channel
48}
49

50- (void)client:(PubNub *)pubnub didReceiveObjectEvent:(PNObjectEventResult *)event {
51    NSString *channel = event.data.channel; // Channel to which the event belongs
52    NSString *subscription = event.data.subscription; // Wild-card channel or channel on which PubNub client actually subscribed
53    NSString *event = event.data.event; // Can be: set or delete
54    NSString *type = event.data.type; // Entity type: channel, uuid or membership
55    NSNumber *timestamp = event.data.timestamp; // Event timestamp
56

57    PNChannelMetadata *channelMetadata = event.data.channelMetadata; // Updated channel metadata (only for channel entity type)
58    PNUUIDMetadata *uuidMetadata = event.data.uuidMetadata; // Updated channel metadata (only for uuid entity type)
59    PNMembership *membership = event.data.membership; // Updated channel metadata (only for membership entity type)
60}
61

62- (void)client:(PubNub *)pubnub didReceiveFileEvent:(PNFileEventResult *)event {
63    NSString *channel = event.data.channel; // Channel to which file has been uploaded
64    NSString *subscription = event.data.subscription; // Wild-card channel or channel on which PubNub client actually subscribed
65    id message = event.data.message; // Message added for uploaded file
66    NSString *publisher = event.data.publisher; // UUID of file uploader
67    NSURL *fileDownloadURL = event.data.file.downloadURL; // URL which can be used to download file
68    NSString *fileIdentifier = event.data.file.identifier; // Unique file identifier
69    NSString *fileName = event.data.file.name; // Name with which file has been stored remotely
70}
71

72- (void)client:(PubNub *)pubnub didReceiveStatus:(PNStatus *)status {
73    PNStatusCategory category = status.category; // One of PNStatusCategory fields to identify status of operation processing
74    PNOperationType operation = status.operation; // One of PNOperationType fields to identify for which operation status received
75    BOOL isError = status.isError; // Whether any kind of error happened.
76    NSInteger statusCode = status.statusCode; // Related request processing status code
77    BOOL isTLSEnabled = status.isTLSEnabled; // Whether secured connection enabled
78    NSString *uuid = status.uuid; // UUID which configured for passed client
79    NSString *authKey = status.authKey; // Auth key configured for passed client
80    NSString *origin = status.origin; // Origin against which request has been sent
81    NSURLRequest *clientRequest = status.clientRequest; // Request which has been used to send last request (may be nil)
82    BOOL willAutomaticallyRetry = status.willAutomaticallyRetry; // Whether client will try to perform automatic retry
83

84    // Following information available when operation == PNSubscribeOperation, because status is PNSubscribeStatus instance in this case
85    PNSubscribeStatus *subscribeStatus = (PNSubscribeStatus *)status;
86    NSNumber *currentTimetoken = subscribeStatus.currentTimetoken; // Timetoken which has been used for current subscribe request
87    NSNumber *lastTimeToken = subscribeStatus.lastTimeToken; // Timetoken which has been used for previous subscribe request
88    NSArray<NSString *> *subscribedChannels = subscribeStatus.subscribedChannels; // List of channels on which client currently subscribed
89    NSArray<NSString *> *subscribedChannelGroups = subscribeStatus.subscribedChannelGroups; // List of channel groups on which client currently subscribed
90    NSString *channel = subscribeStatus.data.channel; // Name of channel for which status has been received
91    NSString *subscription = subscribeStatus.data.subscription; // Wild-card channel or channel on which PubNub client actually subscribed
92    NSNumber *timetoken = subscribeStatus.data.timetoken; // Timetoken at which event arrived
93    NSDictionary *userMetadata = subscribeStatus.data.userMetadata; // Metadata / envelope which has been passed along with event
94

95    // Following information available when isError == YES, because status is PNErrorStatus instance in this case
96    PNErrorStatus *errorStatus = (PNErrorStatus *)status;
97    id associatedObject = errorStatus.associatedObject; // Data which may contain related information (not decrypted message for example)
98    NSArray<NSString *> *erroredChannels = errorStatus.errorData.channels; // List of channels for which error reported (mostly because of Access Manager)
99    NSArray<NSString *> *erroredChannelGroups = errorStatus.errorData.channelGroups; // List of channel groups for which error reported (mostly because of Access Manager)
100    NSString *errorInformation = errorStatus.errorData.information; // Stringified information about error
101    id errorData = errorStatus.errorData.data; // Additional error information from PubNub service
102}

show all 102 lines

Remove listeners

1[pubnub removeListener:self]

Objective-C statements

Objective-C statements require a trailing semicolon in implementation files.

Handling disconnects

The SDK automatically reconnects and reports status. You can stop automatic retries.

1- (void)client:(PubNub *)pubnub didReceiveStatus:(PNStatus *)status {
2  if (status.isError && status.willAutomaticallyRetry) {
3    // Stop automatic retry attempts.
4    [status cancelAutomaticRetry];
5  }
6}

Listener status events

Category	Description
PNAcknowledgmentCategory	An API call was successful. This status has additional details based on the type of the successful operation.
PNAccessDeniedCategory	Access Manager permission failure.
PNTimeoutCategory	Server didn't respond in time for reported operation request.
PNNetworkIssuesCategory	No internet connection.
PNRequestMessageCountExceededCategory	Reported when received message count exceeds requestMessageCountThreshold.
PNConnectedCategory	The SDK subscribed to new channels / channel groups.
PNReconnectedCategory	The SDK was able to reconnect to PubNub.
PNDisconnectedCategory	The SDK unsubscribed from channels / channel groups.
PNUnexpectedDisconnectCategory	Unexpected loss of live updates from PubNub.
PNRequestURITooLongCategory	Request URI too long (too many channels or channel groups).
PNMalformedFilterExpressionCategory	Malformed filtering expression.
PNMalformedResponseCategory	Unexpected service response.
PNDecryptionErrorCategory	Decryption failed using the configured cipherKey.
PNTLSConnectionFailedCategory	Secure (TLS) connection failed.
PNTLSUntrustedCertificateCategory	Untrusted certificate chain.

UserID

Set the user ID at runtime.

Method(s)

1@property (nonatomic, copy, setter = setUserID:) NSString *userID;

Sample code

Required User ID

Always set the User ID (userID) to uniquely identify the user or device that connects to PubNub. Persist the value and keep it stable for the lifetime of the user or device. If you don't set the userID, the client cannot connect.

1// User authorized and we need to update used UUID
2PNConfiguration *configuration = self.client.currentConfiguration;
3configuration.userID = @"myUniqueUserID";
4

5__weak __typeof(self) weakSelf = self;
6[self.client copyWithConfiguration:configuration completion:^(PubNub *client) {
7

8    weakSelf.client = client;
9}];

Other examples

Creating a function to subscribe a unique channel name

1/**
2    Subscription process results arrive to listener which should adopt to
3    PNObjectEventListener protocol and registered using:
4    */
5[self.client addListener:self];
6[self.client subscribeToChannels:@[[NSUUID UUID].UUIDString] withPresence:NO];
7

8// Handle new message from one of channels on which client has been subscribed.
9- (void)client:(PubNub *)client didReceiveMessage:(PNMessageResult *)message {
10

11    // Handle new message stored in message.data.message
12    if (![message.data.channel isEqualToString:message.data.subscription]) {
13

14        // Message has been received on channel group stored in message.data.subscription.
15    }
16    else {
17

18        // Message has been received on channel stored in message.data.channel.
19    }
20

21    NSLog(@"Received message: %@ on channel %@ at %@", message.data.message,
22            message.data.channel, message.data.timetoken);
23}
24

25// Handle subscription status change.
26- (void)client:(PubNub *)client didReceiveStatus:(PNStatus *)status {
27

28    if (status.operation == PNSubscribeOperation) {
29

30        // Check whether received information about successful subscription or restore.
31        if (status.category == PNConnectedCategory || status.category == PNReconnectedCategory) {
32

33            // Status object for those categories can be casted to `PNSubscribeStatus` for use below.
34            PNSubscribeStatus *subscribeStatus = (PNSubscribeStatus *)status;
35            if (subscribeStatus.category == PNConnectedCategory) {
36

37                // This is expected for a subscribe, this means there is no error or issue whatsoever.
38            }
39            else {
40

41                /**
42                    This usually occurs if subscribe temporarily fails but reconnects. This means there was
43                    an error but there is no longer any issue.
44                    */
45            }
46        }
47        else if (status.category == PNUnexpectedDisconnectCategory) {
48

49            /**
50                This is usually an issue with the internet connection, this is an error, handle
51                appropriately retry will be called automatically.
52                */
53        }
54        // Looks like some kind of issues happened while client tried to subscribe or disconnected from
55        // network.
56        else {
57

58            PNErrorStatus *errorStatus = (PNErrorStatus *)status;
59            if (errorStatus.category == PNAccessDeniedCategory) {
60

61                /**
62                    This means that Access Manager does allow this client to subscribe to this channel and channel group
63                    configuration. This is another explicit error.
64                    */
65            }
66            else {
67

68                /**
69                    More errors can be directly specified by creating explicit cases for other error categories
70                    of `PNStatusCategory` such as: `PNDecryptionErrorCategory`,
71                    `PNMalformedFilterExpressionCategory`, `PNMalformedResponseCategory`, `PNTimeoutCategory`
72                    or `PNNetworkIssuesCategory`
73                    */
74            }
75        }
76    }
77}

show all 77 lines

Creating a unique auth_key for Access Manager on initialization

1PNConfiguration *configuration = self.client.currentConfiguration;
2configuration.authKey = [NSUUID UUID].UUIDString.lowercaseString;
3

4__weak __typeof(self) weakSelf = self;
5[self.client copyWithConfiguration:configuration completion:^(PubNub *client) {
6

7    // Store reference on new client with updated configuration.
8    weakSelf.client = client;
9}];

Authentication key

Set and get the auth key.

Method(s)

Authentication key

1@property (nonatomic, nullable, copy) NSString *authKey;

UserID

1@property (nonatomic, copy, setter = setUserID:) NSString *userID;

Sample code

Set auth key

1PNConfiguration *configuration = self.client.currentConfiguration;
2configuration.authKey = @"my_new_authkey";
3

4__weak __typeof(self) weakSelf = self;
5[self.client copyWithConfiguration:configuration completion:^(PubNub *client) {
6

7    // Store reference on new client with updated configuration.
8    weakSelf.client = client;
9}];

Get auth key

1// Request current client configuration and pull out authorisation key from it.
2NSString *authorizationKey = self.client.currentConfiguration.authKey;

Returns

Get Auth key returns the current authentication key.

Filter expression

Requires Stream Controller add-on

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

Stream filtering lets a subscriber receive only messages that match the filter. The filter runs on the server, so non‑matching messages never reach the client.

Use the following property to set or get the filter. For details, see Publish Messages.

Method(s)

1@property (nonatomic, nullable, copy) NSString *filterExpression;

Sample code

Set filter expression

Required User ID

Always set the User ID (userID) to uniquely identify the user or device that connects to PubNub. Persist the value and keep it stable for the lifetime of the user or device. If you don't set the userID, the client cannot connect.

1PNConfiguration *configuration = [PNConfiguration configurationWithPublishKey:@"demo"
2                                                                 subscribeKey:@"demo"
3                                                                       userID:@"myUserID"];
4self.client = [PubNub clientWithConfiguration:configuration];
5self.client.filterExpression = @"(senderID=='PubNub')";

Get filter expression

1NSLog(@"Filtering expression: %@", self.client.filterExpression);

Returns

Returns the current filter expression.

Warning

If filter expression is malformed, PNObjectEventListener won't receive any messages and presence events from service (only error status).