Configuration API for PubNub Cocoa Swift SDK

This SDK has been replaced by a new PubNub Swift SDK written purely in Swift. Check it out here Swift complete API reference for building real-time applications on PubNub, including basic usage and sample code.

Configuration​

PNConfiguration instance is storage for user-provided information which describe further PubNub client behavior. Configuration instance contain additional set of properties which allow to perform precise PubNub client configuration.

Method(s)​

To create configuration instance you can use the following function in the Swift SDK:

public convenience init(publishKey: String, subscribeKey: String)
ParameterTypeRequiredDescription
publishKeyStringYesYour PubNub Publish Key.
subscribeKeyStringYesYour PubNub Subscribe Key.
heartbeatNotificationOptionsPNHeartbeatNotificationOptionsNoThese are bitmask options, they can be combined. When client instances are notified about heartbeat operations, this happens through the PNObjectEventListener callback for statuses.
PNHeartbeatNotifySuccess: explicitly tells client to notify on successful heartbeat operations.
PNHeartbeatNotifyFailure: explicitly tells client to notify on failed heartbeat operations (default is only this option)
PNHeartbeatNotifyAll: This is a combination of PNHeartbeatNotifySuccess and PNHeartbeatNotifyFailure
PNHeartbeatNotifyNone: This means the client will not provide any callback notifications for heartbeat operations
stripMobilePayloadBoolNoStores whether client should strip out received messages (real-time and history) from data which has been appended by client (like mobile payload for mobile push notifications).
cipherKeyStringNoKey which is used to encrypt messages pushed to PubNub service and decrypt messages received from live feeds on which client subscribed at this moment.
subscribeMaximumIdleTimeTimeIntervalNoMaximum number of seconds which client should wait for events from live feed.
Default 310.
nonSubscribeRequestTimeoutTimeIntervalNoNumber of seconds which is used by client during non-subscription operations to check whether response potentially failed with timeout or not.
Default 10.
presenceHeartbeatValueIntNoNumber of seconds which is used by server to track whether client still subscribed on remote data objects live feed or not.
presenceHeartbeatIntervalIntNoNumber of seconds which is used by client to issue heartbeat requests to PubNub service.
keepTimeTokenOnListChangeBoolNoWhether client should keep previous timetoken when subscribe on new set of remote data objects live feeds.
Default true.
catchUpOnSubscriptionRestoreBoolNoWhether client should try to catch up for events which occurred on previously subscribed remote data objects feed while client was off-line.
Default true.
applicationExtensionSharedGroupIdentifierStringNoReference on group identifier which is used to share request cache between application extension and it's containing application.
This property should be set to valid registered group only if PubNub client is used inside of application's extension (iOS 8.0+, macOS 10.10+).
requestMessageCountThresholdUIntNoNumber of maximum expected messages from PubNub service in single response.
maximumMessagesCacheSizeUIntNoMessages de-duplication cache size.
Default 100.
completeRequestsBeforeSuspensionBoolNoWhether client should try complete all API call which is done before application will be completely suspended.
Default true.
suppressLeaveEventsBoolNoIf true, the client shouldn't send presence leave events during the unsubscribe process.
originStringNoIf a custom domain is required, SDK accepts it here.

Basic Usage​

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.

let config = PNConfiguration(publishKey: "demo", subscribeKey: "demo")
self.client = PubNub.clientWithConfiguration(config)
self.client.addListener(self)

Returns​

Configured and ready to use client configuration instance.

Other Examples​

Configure heartbeat notifications​

PNConfiguration​
let config = PNConfiguration(publishKey: "<pub key>", subscribeKey: "<sub key>")
/**
    This is where you need to adjust the PNConfiguration object for the types of heartbeat notifications you want.
    This is a bitmask of options located at https://github.com/pubnub/objective-c/blob/1f1c7a41a3bd8c32b644a6ad98fe179d45397c2b/PubNub/Misc/PNStructures.h#L24
    */
config.heartbeatNotificationOptions = [.notifyAll]

self.client = PubNub.clientWithConfiguration(config)
self.client.addListener(self)
Listener​
func client(_ client: PubNub, didReceive status: PNStatus) {

    if status.operation == .heartbeatOperation {

        /**
            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/sdks/objective-c/api-reference/configuration#configuration_basic_usage
            */

        if !status.isError { /* Heartbeat operation was successful. */ }
        else { /* There was an error with the heartbeat operation, handle here. */ }
    }
}

Configuration update​

PubNub client instance doesn't allow dynamic configuration update, but it has helper functions which allow to receive new instance with updated configuration. Updated configuration will be applied on PubNub client copy. Original instance after copy block will return shouldn't be used anymore.

Method(s)​

To update client configuration you can use following functions in the Swift SDK:

Update client configuration with closure​

open func copyWithConfiguration(
    _ configuration: PNConfiguration,
    completion block: @escaping (PubNub) -> Swift.Void
)
ParameterTypeRequiredDescription
configurationPNConfigurationYesClass Instance which stores the configuration settings which is used by the PubNub client.
closure(PubNub) -> VoidYesCompletion closure which is called at the end of update process, has one parameter - PubNub instance with updated configuration.

Update client configuration with callback queue and closure​

open func copyWithConfiguration(
    _ configuration: PNConfiguration,
    callbackQueue: DispatchQueue?,
    completion block: @escaping (PubNub) -> Swift.Void
)
ParameterTypeRequiredDescription
configurationPNConfigurationYesClass Instance which stores the configuration settings which is used by the PubNub client.
callbackQueuedispatch_queue_tNoThe GCD dispatch queue where callbacks and completion handlers will be called (asynchronously).
closure(PubNub) -> VoidYesCompletion closure which is called at the end of update process, has one parameter - PubNub instance with updated configuration.

Basic Usage​

Client configuration:

// User authorized and we need to update used UUID
let configuration = self.client.currentConfiguration()
configuration.uuid = "AuthorizedUserID"
self.client.copyWithConfiguration(configuration, completion: { (updatedClient) in

    // Store reference on new client with updated configuration.
    self.client = updatedClient
})

Returns​

Void

Initialization​

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

Install the 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 tasks to complete:

  1. Create new Xcode project.
    Xcode project

  2. Create a Podfile in your newly created Xcode project root folder

    touch Podfile

  3. 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.

  4. 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!

OS X 10.9 and above: Complete the application delegate configuration​

If the project's deployment target is set to OS X 10.9 and above, you will need to import the module named AppDelegate.swift:

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. Not setting the UUID can significantly impact your billing if your account uses the Monthly Active Users (MAUs) based pricing model, and can also lead to unexpected behavior if you have Presence enabled.

import Cocoa
import PubNub // <- Here is our PubNub module import.

Common to all OS X versions: Add the PNObjectEventListener protocol to the AppDelegate​

class AppDelegate: NSObject, NSApplicationDelegate, PNObjectEventListener {

    // Stores reference on PubNub client to make sure what it won't be released.
    var client: PubNub!

    func applicationDidFinishLaunching(_ aNotification: Notification) {
        ...
    }
}

Description​

This function is used for initializing the PubNub Client API context. This function must be called before attempting to utilize any API functionality in order to establish account level credentials such as publishKey and subscribeKey.

Method(s)​

To Initialize PubNub you can use the following method(s) in the Swift SDK:

Initialize PubNub​

open class func clientWithConfiguration(_ configuration: PNConfiguration) -> Self
ParameterTypeRequiredDescription
configurationPNConfigurationYesClass Instance which stores the configuration settings which is used by the PubNub client.

Initialize PubNub with callback queue​

open class func clientWithConfiguration(
    _ configuration: PNConfiguration,
    callbackQueue: DispatchQueue?
) -> Self
ParameterTypeRequiredDescription
configurationPNConfigurationYesClass Instance which stores the configuration settings which is used by the PubNub client.
callbackQueuedispatch_queue_tNoThe GCD dispatch queue where callbacks and completion handlers will be called (asynchronously).

Basic Usage​

Initialize the PubNub client API​

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.

let configuration = PNConfiguration(publishKey: "demo", subscribeKey: "demo")
configuration.TLSEnabled = true
self.client = PubNub.clientWithConfiguration(configuration)

Returns​

It returns the PubNub instance for invoking PubNub APIs like publish(), subscribeToChannels(), historyForChannel, hereNowForChannel.

Other Examples​

Initialize the client​

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.

let configuration = PNConfiguration(publishKey: "demo", subscribeKey: "demo")
self.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 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.

let configuration = PNConfiguration(publishKey: "", subscribeKey: "demo")
self.client = PubNub.clientWithConfiguration(configuration)

Use a custom UUID​

Set a custom UUID to identify your users.

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.

let configuration = PNConfiguration(publishKey: "myPublishKey", subscribeKey: "mySubscribeKey")
configuration.uuid = "myUniqueUUID"
self.client = PubNub.clientWithConfiguration(configuration)

Initializing with SSL Enabled​

This examples demonstrates how to enable PubNub Transport Layer Encryption with SSL. Just initialize the client with ssl set to true. The hard work is done, now the PubNub API takes care of the rest. Just subscribe and publish as usual and you are good to go.

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.

let configuration = PNConfiguration(publishKey: "demo", subscribeKey: "demo")
configuration.TLSEnabled = true
self.client = PubNub.clientWithConfiguration(configuration)

UUID​

This function is used to set a user ID on the fly.

Method(s)​

To set UUID you can use the following method(s) in Swift SDK:

open var uuid: String

Basic Usage​

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.

// User authorized and we need to update used UUID
let configuration = self.client.currentConfiguration()
configuration.uuid = NSUUID().uuidString
self.client.copyWithConfiguration(configuration, completion: { (updatedClient) in

    // Store reference on new client with updated configuration.
    self.client = updatedClient
})

Other Examples​

Creating a function to subscribe a unique channel name​

/**
    Subscription process results arrive to listener which should adopt to PNObjectEventListener protocol
    and registered using:
    */
self.client.addListener(self)
self.client.subscribeToChannels([NSUUID().uuidString], withPresence: false)

// Handle new message from one of channels on which client has been subscribed.
func client(_ client: PubNub, didReceiveMessage message: PNMessageResult) {

    // Handle new message stored in message.data.message
    if message.data.channel != message.data.subscription {

        // Message has been received on channel group stored in message.data.subscription.
    }
show all 76 lines

Initializing with a custom uuid​

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.

let configuration = self.client.currentConfiguration()
configuration.uuid = "myUniqueUUID"
self.client.copyWithConfiguration(configuration, completion: { (updatedClient) in

    // Store reference on new client with updated configuration.
    self.client = updatedClient
})

Creating a unique auth_key for Access Manager on initialization​

let configuration = self.client.currentConfiguration()
configuration.authKey = NSUUID().uuidString
self.client.copyWithConfiguration(configuration, completion: { (updatedClient) in

    // Store reference on new client with updated configuration.
    self.client = updatedClient
})

Authentication Key​

Setter and getter for users auth key.

Method(s)​

open var authKey: String?

Basic Usage​

Set Auth Key​

let configuration = self.client.currentConfiguration()
configuration.authKey = "my_new_authkey"
self.client.copyWithConfiguration(configuration, completion: { (updatedClient) in

    // Store reference on new client with updated configuration.
    self.client = updatedClient
})

Get Auth Key​

// Request current client configuration and pull out authorisation key from it.
let authKey = 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.

To set or get message filters, you can use the following methods.

Method(s)​

open var filterExpression: String?

Basic Usage​

Set Filter Expression​

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.

let configuration = PNConfiguration(publishKey: "demo", subscribeKey: "demo")
self.client = PubNub.clientWithConfiguration(configuration)
self.client.filterExpression = "(senderID=='PubNub')";

Get Filter Expression​

print("Filtering expression: \(self.client.filterExpression)")

Returns​

Get Filter Expression returns the Current filtering expression.

Malformed filter expression

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

Last updated on
On this page