PubNub Cocoa Objective-C SDK 5.7.0

Get Code: CocoaPods

CocoaPods is a dependency manager and this is by far the easiest and quickest way to get started with PubNub Cocoa 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 cocoapods gem:

gem install cocoapods

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

gem update cocoapods

Get Code: Git

Add the PubNub Cocoa SDK folder to your project.

Get Code: Framework

The PubNub framework project allows you to build standalone framework bundles which can be copied right into your application.

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

Clone the PubNub master repository

git clone [email protected]:pubnub/objective-c.git

Navigate to root of the cloned repository
Run the CocoaPods pod install command to pull out all required dependencies
```
`pod install`
```
Open the PubNub.xcworkspace from the PubNub repository in Xcode.
Select the Framework or Universal Framework target for target platform and hit Cmd+B to build the selected type of framework.
Navigate to the Framework directory and find the Products directory.
Drag&Drop PubNub.framework bundle from the Products directory to your application.
Select the Copy items if needed checkbox and click Finish.
Open your project's General tab and scroll to Embedded Binaries.
Click on + and select PubNub.framework file.

PubNub-Universal

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.

Using the framework with 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>

Get Code: Carthage

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

Install latest Carthage (if required).
Create a Cartfile (any location can be used) or use existing file.
```
touch Cartfile
```
Add next line into a Cartfile which will allow to build framework bundles
```
github "pubnub/objective-c" ~> 4.1
```
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
Navigate to the Carthage directory and find the Build directory.
Navigate to directory which represent your target platform. For example: iOS
Drag&Drop PubNub.framework bundle from the Products directory to your application.
Select the Copy items if needed checkbox and click Finish.
Open your project's General tab and scroll to Embedded Binaries.
Click on + and select PubNub.framework file.

Using the framework with 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>

Get Code: Source

Hello World

Include PubNub SDK in your project you need to use CocoaPods

Install CocoaPods gem by following the procedure defined above. To add the PubNub SDK to your project with CocoaPods, there are four basic tasks to complete which are covered below:

Create new Xcode project.
Create Podfile in new Xcode project root folder
```
touch Podfile
```
The PubNub client can be added as module (only with a deployment target of OS X 10.9 and above):
```
source 'https://github.com/CocoaPods/Specs.git'
platform :osx, "10.9"
use_frameworks!

target 'application-target-name' do
    pod "PubNub", "~> 4.1"
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.
Install your pods by running pod install via the command line from the directory that contains your Podfile.

Work within the workspace

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>

Complete application delegate configuration

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

Required UUID

Always set the UUID to uniquely identify the user or device that connects to PubNub. This UUID should be persisted, and should remain unchanged for the lifetime of the user or the device. If you don't set the UUID, you won't be able to connect to PubNub.

#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

Required UUID

// Initialize and configure PubNub client instance
PNConfiguration *configuration = [PNConfiguration configurationWithPublishKey:@"demo" subscribeKey:@"demo"];
configuration.uuid = @"myUniqueUUID";

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]) {
show all 128 lines

Copy and paste examples

In addition to the Hello World sample code, we also provide some copy and paste snippets of common API functions:

Init

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 Access Manager administrative operations from this Cocoa instance.

Secure your secretKey

It is not a best practice to include the secret key in client-side code for security reasons.

When you init with secretKey, you get root permissions for the Access Manager. With this feature you don't have to grant access to your servers to access channel data. The servers get all access on all channels.

Required UUID

PNConfiguration *configuration = [PNConfiguration configurationWithPublishKey:@"demo"
                                                                 subscribeKey:@"demo"];
configuration.uuid = @"myUniqueUUID";
self.client = [PubNub clientWithConfiguration:configuration];

PubNub instance as property

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;

Listeners

Add Listeners

Listener's class should conform to PNEventsListener protocol to have access to available callbacks.

// Adding listener.
[pubnub addListener:self];

// Callbacks listed below.

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

- (void)client:(PubNub *)pubnub didReceiveSignal:(PNSignalResult *)signal {
    NSString *channel = message.data.channel; // Channel on which the signal has been published
show all 102 lines

Remove Listeners

[pubnub removeListener:self]

Listener status events

Category	Description
`PNAcknowledgmentCategory`	Reported operation request acknowledgment status.
`PNAccessDeniedCategory`	Access Manager permission failure.
`PNTimeoutCategory`	Server didn't respond in time for reported operation request.
`PNNetworkIssuesCategory`	No connection to Internet.
`PNRequestMessageCountExceededCategory`	The SDK announces this error if `requestMessageCountThreshold` is set, and the number of messages received from PubNub (in-memory cache messages) exceeds the threshold.
`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`	The SDK unexpectedly lost ability to receive live updated from PubNub.
`PNRequestURITooLongCategory`	Reported operation request URI too long (too many channels / channel groups).
`PNMalformedFilterExpressionCategory`	The SDK has been configured with malformed filtering expression.
`PNMalformedResponseCategory`	The SDK received unexpected PubNub service response.
`PNDecryptionErrorCategory`	The SDK unable to decrypt received message using configured `cipherKey`.
`PNTLSConnectionFailedCategory`	The SDK unable to establish secured connection.
`PNTLSUntrustedCertificateCategory`	The SDK unable to check certificates trust chain.

Time

Call timeWithCompletion to verify the client connectivity to the origin:

[self.client timeWithCompletion:^(PNTimeResult *result, PNErrorStatus *status) {

    if (!status) {

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

        /**
         Handle timetoken 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];
show all 18 lines

Subscribe (listen on) a channel (it's async!):

/**
 Subscription results arrive to a listener which should implement the
 PNObjectEventListener protocol and be registered as follows:
 */
[self.client addListener:self];
[self.client subscribeToChannels: @[@"my_channel1", @"my_channel2"] withPresence:NO];

// Handle a new message from a subscribed channel
- (void)client:(PubNub *)client didReceiveMessage:(PNMessageResult *)message {
    // Reference to the channel group containing the chat the message was sent to
    NSString *subscription = message.data.subscription;
    NSLog(@"%@ sent message to '%@' at %@: %@", message.data.publisher, message.data.channel,
            message.data.timetoken, message.data.message);
}

show all 97 lines

Event listeners

The response of the call is handled by adding a Listener. Please see the Listeners section for more details. Listeners should be added before calling the method.

Publish

Publish a message to a channel:

[self.client publish: @{@"Dictionary": @[@"with",@"array",@"as", @"value"]}
           toChannel: @"pubnub" 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.

show all 19 lines

Here Now

Get occupancy of who's here now on the channel by UUID:

Requires Presence add-on

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

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

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

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

Presence

Subscribe to real-time 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 Presence add-on

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

/**
 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 {
show all 31 lines

Event listeners

The response of the call is handled by adding a Listener. Please see the Listeners section for more details. Listeners should be added before calling the method.

History

Retrieve published messages from archival storage:

Requires Message Persistence

This method requires that Message Persistence is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your 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 {

        /**
show all 24 lines

Unsubscribe

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

Event listeners

The response of the call is handled by adding a Listener. Please see the Listeners section for more details. Listeners should be added before calling the method.

Get Code: CocoaPods​

Get Code: Git​

Get Code: Framework​

PubNub-Universal

Using the framework with your app​

Get Code: Carthage​

Using the framework with your app​

Get Code: Source​

Hello World​

Include PubNub SDK in your project you need to use CocoaPods​

Work within the workspace

Complete application delegate configuration​

Required UUID

Required UUID

Copy and paste examples​

Init​

Secure your secretKey

Required UUID

PubNub instance as property

Listeners​

Add Listeners​

Remove Listeners​

Listener status events​

Time​

Subscribe​

Event listeners

Publish​

Here Now​

Requires Presence add-on

Presence​

Requires Presence add-on

Event listeners

History​

Requires Message Persistence

Unsubscribe​

Event listeners

Get Code: CocoaPods

Get Code: Git

Get Code: Framework

Using the framework with your app

Get Code: Carthage

Using the framework with your app

Get Code: Source

Hello World

Include PubNub SDK in your project you need to use CocoaPods

Complete application delegate configuration

Copy and paste examples

Init

Listeners

Add Listeners

Remove Listeners

Listener status events

Time

Subscribe

Publish

Here Now

Presence

History

Unsubscribe