iOSiOSCocoaObjective-CPubNub iOS SDK 4.5.12

CocoaPods is a dependency manager and this is by far the easiest and quickest way to get started with PubNub iOS SDK! (If you don't have pods installed yet you can check CocoaPods installation section for installation guide).

Be sure you are running CocoaPods 1.0.0 or above! You can install the latest cocopods gem:

gem install cocoapods

If you’ve already installed you can upgrade to the latest CocoaPods gem using:

gem update cocoapods
Add the PubNub iOS SDK folder to your project.
To build the framework as a standalone bundle and integrate into project, perform the following:
  1. Clone the PubNub master repository
    git clone git@github.com:pubnub/objective-c.git
    
  2. Navigate to root of the cloned repository
  3. Run the CocoaPods pod install command to pull out all required dependencies
    pod install
    
  4. Open the PubNub.xcworkspace from the PubNub repository in Xcode.
  5. Select the Framework or Universal Framework target for target platform and hit Cmd+B to build the selected type of framework.
    Select Framework target

  6. Navigate to the Framework directory and find the Products directory.
    Navigate to Framework bundle
  7. Drag&Drop PubNub.framework bundle from the Products directory to your application.
    Drag & drop Framework bundle
  8. Select the Copy items if needed checkbox and click Finish.
    Copy Framework bundle
  9. Open your project's General tab and scroll to Embedded Binaries.
    Open embedded binaries group Objective C
  10. Click on + and select PubNub.framework file.
    Add Framework bundle to embedded binaries group
 
If the PubNub target has been used, then the framework will be generated only for the selected platform (device or simulator.) If you try to use the framework to compile for another platform, it will crash during run-time! Using the PubNub-Universal build target (which can be used on both device and simulator) will help mitigate any sort of crash scenarios during development.

Now that these steps are complete, let's learn more about how to use the framework in your app.

At this point, you should have the framework added to your application project, we'll need to make your project aware of the PubNub framework.

You need to import the PubNub headers in classes where it will be used.

#import <PubNub/PubNub.h>

To build the framework as a standalone bundle and integrate into project, perform the following:

  1. Install latest Carthage (if required).
  2. Create a Cartfile (any location can be used) or use existing file.
    touch Cartfile
  3. Add next line into a Cartfile which will allow to build framework bundles

    		github "pubnub/objective-c" ~> 4.1	
  4. Update and rebuild the project's dependencies (update command ensure what latest PubNub client code will be used to build framework). build can be used if frameworks has been built before and it will be much faster because git clone will be skipped.

    		carthage update

    Command above will build framework for all configured platforms, but if only one required it can be called like this

    		carthage update --platform ios

    Instead of ios can be used: mac, tvos or watchos

  5. Navigate to the Carthage directory and find the Build directory.
  6. Navigate to directory which represent your target platform. For example: iOS

    Navigate to built framework bundle for Carthage
  7. Drag&Drop PubNub.framework bundle from the Products directory to your application.

    Drag & drop Framework bundle for Carthage
  8. Select the Copy items if needed checkbox and click Finish.

    Copy Framework bundle for Carthage
  9. Open your project's General tab and scroll to Embedded Binaries.

    Open embedded binaries group Objective C for Carthage
  10. Click on + and select PubNub.framework file.

    Add Framework bundle to embedded binaries group for Carthage

At this point, you should have the framework added to your application project, we'll need to make your project aware of the PubNub framework.

You need to import the PubNub headers in classes where it will be used.

#import <PubNub/PubNub.h>

Install CocoaPods gem by following the procedure defined under How to Get It.
To add the PubNub SDK to your project with CocoaPods, there are four basic tasks to complete which are covered below:
  1. Create new Xcode project.
  2. Create Podfile in new Xcode project root folder
    touch Podfile
  3. The PubNub client can be added as dynamic framework (only with a deployment target of iOS 8.0 and above) or as a static library (for deployment targets of iOS 7.0 and above).
    1. For a deployment target of iOS 8.0 and above use:
      source 'https://github.com/CocoaPods/Specs.git'
      
      # optionally complete and uncomment if compilation issues arise
      # project '<path to project relative to this Podfile>/<name of project without extension>'
      # workspace 'MyPubNubProject'
      
      use_frameworks!
       
      target 'application-target-name' do
          # Can only support iOS 8 or higher with frameworks, 
          # but can only target higher frameworks as well
          platform :ios, '8.0' # (or '9.0' or '10.0')
          pod "PubNub", "~> 4"
      end
    2. For a deployment target of iOS 7.0 and above use:
      source 'https://github.com/CocoaPods/Specs.git'
      
      # optionally complete and uncomment if compilation issues arise
      # project '<path to project relative to this Podfile>/<name of project without extension>'
      # workspace 'MyPubNubProject'
       
      target 'application-target-name' do
          # Should only use this with projects 
          # that must have a minimum deployment 
          # target of iOS 7 
          platform :ios, '7.0' # (if you don't need to use iOS 7, then see other Podfile)
          pod "PubNub", "~> 4"
      end
      If you have any other pods you'd like to include, or if you have other targets you'd to add (like a test target) add those entries to this Podfile as well. See the CocoaPods documentation for more information on Podfile configuration.
  4. Install your pods by running pod install via the command line from the directory that contains your Podfile.

 
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!

To be able to use PubNub SDK within your application code you need to import it. Import PubNub SDK headers in implementation files for classes where you need to use it using this import statement:
#import <PubNub/PubNub.h>
Add the PNObjectEventListener protocol to AppDelegate in implementation file to anonymous category:
#import <PubNub/PubNub.h>

@interface AppDelegate () <PNObjectEventListener>

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

@end
// Initialize and configure PubNub client instance
PNConfiguration *configuration = [PNConfiguration configurationWithPublishKey:@"demo" subscribeKey:@"demo"];
self.client = [PubNub clientWithConfiguration:configuration];
[self.client addListener:self];

// Subscribe to demo channel with presence observation
[self.client subscribeToChannels: @[@"my_channel"] withPresence:YES];
 
// Handle new message from one of channels on which client has been subscribed.
- (void)client:(PubNub *)client didReceiveMessage:(PNMessageResult *)message {

	// Handle new message stored in message.data.message
	if (![message.data.channel isEqualToString:message.data.subscription]) {
 
		// Message has been received on channel group stored in message.data.subscription.
	}
	else {
 
		// Message has been received on channel stored in message.data.channel.
	}

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

// New presence event handling.
- (void)client:(PubNub *)client didReceivePresenceEvent:(PNPresenceEventResult *)event {
	
	if (![event.data.channel isEqualToString:event.data.subscription]) {
		
		// Presence event has been received on channel group stored in event.data.subscription.
	}
	else {
		
		// Presence event has been received on channel stored in event.data.channel.
	}
	
	if (![event.data.presenceEvent isEqualToString:@"state-change"]) {
		
		NSLog(@"%@ \"%@'ed\"\nat: %@ on %@ (Occupancy: %@)", event.data.presence.uuid, 
			  event.data.presenceEvent, event.data.presence.timetoken, event.data.channel, 
			  event.data.presence.occupancy);
	}
	else {
		
		NSLog(@"%@ changed state at: %@ on %@ to: %@", event.data.presence.uuid, 
			  event.data.presence.timetoken, event.data.channel, event.data.presence.state);
	}
}

// Handle subscription status change.
- (void)client:(PubNub *)client didReceiveStatus:(PNStatus *)status {
	
	if (status.operation == PNSubscribeOperation) {
		
		// Check whether received information about successful subscription or restore.
		if (status.category == PNConnectedCategory || status.category == PNReconnectedCategory) {
			
			// Status object for those categories can be casted to `PNSubscribeStatus` for use below.
			PNSubscribeStatus *subscribeStatus = (PNSubscribeStatus *)status;
			if (subscribeStatus.category == PNConnectedCategory) {
				
				// This is expected for a subscribe, this means there is no error or issue whatsoever.
				
				// Select last object from list of channels and send message to it.
				NSString *targetChannel = [client channels].lastObject;
				[self.client publish: @"Hello from the PubNub Objective-C SDK" 
						   toChannel: targetChannel withCompletion:^(PNPublishStatus *publishStatus) {
						  
					// Check whether request successfully completed or not.
					if (!publishStatus.isError) {

						// Message successfully published to specified channel.
					}
					else {

						/**
						 Handle message publish 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: [publishStatus retry];
						*/
					}
				}];
			}
			else {
				
				/**
				 This usually occurs if subscribe temporarily fails but reconnects. This means there was 
				 an error but there is no longer any issue.
				 */
			}
		}
		else if (status.category == PNUnexpectedDisconnectCategory) {
			
			/**
			 This is usually an issue with the internet connection, this is an error, handle 
			 appropriately retry will be called automatically.
			 */
		}
		// Looks like some kind of issues happened while client tried to subscribe or disconnected from 
		// network.
		else {
			
			PNErrorStatus *errorStatus = (PNErrorStatus *)status;
			if (errorStatus.category == PNAccessDeniedCategory) {
				
				/**
				 This means that PAM does allow this client to subscribe to this channel and channel group 
				 configuration. This is another explicit error.
				 */
			}
			else {
				
				/**
				 More errors can be directly specified by creating explicit cases for other error categories 
				 of `PNStatusCategory` such as: `PNDecryptionErrorCategory`,  
				 `PNMalformedFilterExpressionCategory`, `PNMalformedResponseCategory`, `PNTimeoutCategory`
				 or `PNNetworkIssuesCategory`
				 */
			}
		}
	}
}
In addition to the Hello World sample code, we also provide some copy and paste snippets of common API functions:
Instantiate a new Pubnub instance. Only the subscribeKey is mandatory. Also include publishKey if you intend to publish from this instance, and the secretKey if you wish to perform PAM administrative operations from this Objective-C instance.
 
It is not a best practice to include the secret key in client-side code for security reasons.
PNConfiguration *configuration = [PNConfiguration configurationWithPublishKey:@"demo" 
																 subscribeKey:@"demo"];
self.client = [PubNub clientWithConfiguration:configuration];
 
PubNub instance should be placed as a property in a long-life object (otherwise PubNub instance will be automatically removed as autoreleased object).

@property (nonatomic, strong) PubNub *client;
Call timeWithCompletion to verify the client connectivity to the origin:
[self.client timeWithCompletion:^(PNTimeResult *result, PNErrorStatus *status) {

	if (!status) {

		// Handle downloaded server time token using: result.data.timetoken
	}
	else {

		/**
		 Handle time token download 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];
		 */
	}
}];
Subscribe (listen on) a channel (it's async!):
/**
 Subscription process results arrive to listener which should adopt to PNObjectEventListener protocol
 and registered using:
 */
[self.client addListener:self]; 
[self.client subscribeToChannels: @[@"my_channel1", @"my_channel2"] withPresence:NO];
 

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

	// Handle new message stored in message.data.message
	if (![message.data.channel isEqualToString:message.data.subscription]) {
 
		// Message has been received on channel group stored in message.data.subscription.
	}
	else {
 
		// Message has been received on channel stored in message.data.channel.
	}

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

// Handle subscription status change.
- (void)client:(PubNub *)client didReceiveStatus:(PNStatus *)status {
    
	if (status.operation == PNSubscribeOperation) {
        
		// Check whether received information about successful subscription or restore.
		if (status.category == PNConnectedCategory || status.category == PNReconnectedCategory) {

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

				// This is expected for a subscribe, this means there is no error or issue whatsoever.
			}
			else {
                
				/**
				 This usually occurs if subscribe temporarily fails but reconnects. This means there was 
				 an error but there is no longer any issue.
				 */
			}
		}
		else if (status.category == PNUnexpectedDisconnectCategory) {

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

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

				/**
				 This means that PAM does allow this client to subscribe to this channel and channel group 
				 configuration. This is another explicit error.
				 */
			}
			else {
					
				/**
				 More errors can be directly specified by creating explicit cases for other error categories 
				 of `PNStatusCategory` such as: `PNDecryptionErrorCategory`,  
				 `PNMalformedFilterExpressionCategory`, `PNMalformedResponseCategory`, `PNTimeoutCategory`
				 or `PNNetworkIssuesCategory`
				 */
			}
		}
	}
	else if (status.operation == PNUnsubscribeOperation) {

		if (status.category == PNDisconnectedCategory) {

			/**
			 This is the expected category for an unsubscribe. This means there was no error in unsubscribing
			 from everything.
			 */
		}
	}
	else if (status.operation == PNHeartbeatOperation) {

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

		if (!status.isError) { /* Heartbeat operation was successful. */ } 
		else { /* There was an error with the heartbeat operation, handle here. */ }
	}
}
Publish a message to a channel:
[self.client publish: @"Hello from PubNub iOS!" toChannel: @"my_channel" storeInHistory:YES
	  withCompletion:^(PNPublishStatus *status) {

	if (!status.isError) {

		// Message successfully published to specified channel.
	}
	else {

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

		 Request can be resent using: [status retry];
		 */
	}
}];
Get occupancy of who's here now on the channel by UUID:
Requires that the Presence add-on is enabled for your key. How do I enable add-on features for my keys? - see http://www.pubnub.com/knowledge-base/discussion/644/how-do-i-enable-add-on-features-for-my-keys
// 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];
		 */
	}
}];
Subscribe to realtime Presence events, such as join, leave, and timeout, by UUID. Setting the presence attribute to a callback will subscribe to presents events on my_channel:
Requires that the Presence add-on is enabled for your key. How do I enable add-on features for my keys? - see http://www.pubnub.com/knowledge-base/discussion/644/how-do-i-enable-add-on-features-for-my-keys
/**
 Subscription process results arrive to listener which should adopt to
 PNObjectEventListener protocol and registered using:
 */
[self.client addListener:self];
[self.client subscribeToPresenceChannels:@[@"my_channel"]];


// New presence event handling.
- (void)client:(PubNub *)client didReceivePresenceEvent:(PNPresenceEventResult *)event {
	
	if (![event.data.channel isEqualToString:event.data.subscription]) {
		
		// Presence event has been received on channel group stored in event.data.subscription.
	}
	else {
		
		// Presence event has been received on channel stored in event.data.channel.
	}
	
	if (![event.data.presenceEvent isEqualToString:@"state-change"]) {
		
		NSLog(@"%@ \"%@'ed\"\nat: %@ on %@ (Occupancy: %@)", event.data.presence.uuid, 
			  event.data.presenceEvent, event.data.presence.timetoken, event.data.channel, 
			  event.data.presence.occupancy);
	}
	else {
		
		NSLog(@"%@ changed state at: %@ on %@ to: %@", event.data.presence.uuid, 
			  event.data.presence.timetoken, event.data.channel, event.data.presence.state);
	}
}
Retrieve published messages from archival storage:
Requires that the Storage and Playback add-on is enabled for your key. How do I enable add-on features for my keys? - see http://www.pubnub.com/knowledge-base/discussion/644/how-do-i-enable-add-on-features-for-my-keys
[self.client historyForChannel: @"my_channel" start:nil end:nil limit:100
				withCompletion:^(PNHistoryResult *result, PNErrorStatus *status) {

	if (!status) {

		/**
		 Handle downloaded history using: 
			result.data.start - oldest message time stamp in response
			result.data.end - newest message time stamp in response
			result.data.messages - list of messages
		 */
	}
	else {

		/**
		 Handle message history download 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];
		 */
	}
}];
Stop subscribing (listening) to a channel.
/**
 Unsubscription process results arrive to listener which should adopt to
 PNObjectEventListener protocol and registered using:
 */
[self.client addListener:self];
[self.client unsubscribeFromChannels: @[@"my_channel1", @"my_channel2"] withPresence:NO];

// Handle subscription status change.
- (void)client:(PubNub *)client didReceiveStatus:(PNStatus *)status {
 
	if (status.operation == PNUnsubscribeOperation && status.category == PNDisconnectedCategory) {

		/**
		 This is the expected category for an unsubscribe. This means there was no error in 
		 unsubscribing from everything.
		 */
	}
}
Check out PubNub's other Objective-C-based SDKs, such as iOS, Cocoa.