--- source_url: https://www.pubnub.com/docs/sdks/cocoa-objective-c/api-reference/misc title: Utility Methods API for Cocoa Objective-C SDK updated_at: 2026-06-11T11:35:48.329Z --- > Documentation Index > For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt > For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt # Utility Methods API for Cocoa Objective-C SDK The methods on this page are utility methods that don't fit into other categories. ## Time This function will return a 17 digit precision Unix epoch. :::note Algorithm constructing the timetoken ```javascript timetoken = (Unix epoch time in seconds) * 10000000 ``` Example of creating a timetoken for a specific time and date: ```javascript 08/19/2013 @ 9:20pm in UTC = 1376961606 timetoken = 1376961606 * 10000000 timetoken = 13769616060000000 ``` ::: ### Method(s) To fetch `Time` you can use the following method(s) in Cocoa SDK: ```objectivec ­- (void)timeWithCompletion:(PNTimeCompletionBlock)block; ``` | Parameter | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | block | PNClientTimeTokenReceivingCompleteBlock | Yes | | `Time` request process results handling `block` which pass two arguments: result - in case of successful request processing data field will contain server-provided timetoken; status - in case if `error` occurred during request processing | ### Sample code #### Get PubNub timetoken ```objectivec [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]; */ } }]; ``` ### Response Response objects which is returned by client when Time API is used: ```objectivec @interface PNTimeData : PNServiceData // Current time on PubNub network servers. @property (nonatomic, readonly, strong) NSNumber *timetoken; @end @interface PNTimeResult : PNResult // Stores reference on time request processing information. @property (nonatomic, readonly, strong) PNTimeData *data; @end ``` ## Get size of message This function provides a mechanism to calculate resulting message before it will be sent to the PubNub network. ### Method(s) To run `Get size of message` you can use the following method(s) in the Cocoa SDK: #### Get size of message with block ```objectivec - (void)sizeOfMessage:(id)message toChannel:(NSString *)channel withCompletion:(PNMessageSizeCalculationCompletionBlock)block; ``` | Parameter | Description | | --- | --- | | `message` *Type: id | Message for which size should be calculated. | | `channel` *Type: NSString | Name of the `channel` to which `message` should be sent (it is part of request URI). | | `block` *Type: PNMessageSizeCalculationCompletionBlock | Reference on block which should be sent, when message size calculation will be completed. | #### Get size of message with compression and block ```objectivec - (void)sizeOfMessage:(id)message toChannel:(NSString *)channel compressed:(BOOL)compressMessage withCompletion:(PNMessageSizeCalculationCompletionBlock)block; ``` | Parameter | Description | | --- | --- | | `message` *Type: id | Message for which size should be calculated. | | `channel` *Type: NSString | Name of the `channel` to which `message` should be sent (it is part of request URI). | | `compressMessage` *Type: Bool | `YES` in case if `message` should be compressed before sending to `PubNub` network. | | `block` *Type: PNMessageSizeCalculationCompletionBlock | Reference on block which should be sent, when message size calculation will be completed. | #### Get size of message with storage and block ```objectivec - (void)sizeOfMessage:(id)message toChannel:(NSString *)channel storeInHistory:(BOOL)shouldStore withCompletion:(PNMessageSizeCalculationCompletionBlock)block; ``` | Parameter | Description | | --- | --- | | `message` *Type: id | Message for which size should be calculated. | | `channel` *Type: NSString | Name of the `channel` to which `message` should be sent (it is part of request URI). | | `shouldStore` *Type: Bool | `YES` in case if `message` should be stored in Message Persistence. | | `block` *Type: PNMessageSizeCalculationCompletionBlock | Reference on block which should be sent, when message size calculation will be completed. | #### Get size of message with compression, storage, and block ```objectivec - (void)sizeOfMessage:(id)message toChannel:(NSString *)channel compressed:(BOOL)compressMessage storeInHistory:(BOOL)shouldStore withCompletion:(PNMessageSizeCalculationCompletionBlock)block; ``` | Parameter | Description | | --- | --- | | `message` *Type: id | Message for which size should be calculated. | | `channel` *Type: NSString | Name of the `channel` to which `message` should be sent (it is part of request URI). | | `compressMessage` *Type: Bool | `YES` in case if `message` should be compressed before sending to PubNub network. | | `shouldStore` *Type: Bool | `NO` in case if `message` shouldn't be available after it has been sent via history Message Persistence API methods `group`. | | `block` *Type: PNMessageSizeCalculationCompletionBlock | Reference on block which should be sent, when message size calculation will be completed. | #### Get size of message with metadata and block ```objectivec - (void)sizeOfMessage:(id)message toChannel:(NSString *)channel withMetadata:(nullable NSDictionary *)metadata completion:(PNMessageSizeCalculationCompletionBlock)block; ``` | Parameter | Description | | --- | --- | | `message` *Type: id | The `message` for which the size needs be calculated. | | `channel` *Type: NSString | The `channel` on which the `message` has to be sent (it is part of request URI). | | `metadata`Type: NSDictionary | `NSDictionary` with values which should be used by `PubNub` service to filter messages. | | `block` *Type: PNMessageSizeCalculationCompletionBlock | Completion `block` which will be called when the `message` size calculation is complete. | #### Get size of message with compression, metadata, and block ```objectivec - (void)sizeOfMessage:(id)message toChannel:(NSString *)channel compressed:(BOOL)compressMessage withMetadata:(nullable NSDictionary *)metadata completion:(PNMessageSizeCalculationCompletionBlock)block; ``` | Parameter | Description | | --- | --- | | `message` *Type: id | The `message` for which the size needs be calculated. | | `channel` *Type: NSString | The `channel` on which the `message` has to be sent (it is part of request URI). | | `compressMessage` *Type: Bool | Should be `true` if the `message` is compressed before sending to `PubNub` network. | | `metadata`Type: NSDictionary | `NSDictionary` with values which should be used by `PubNub` service to filter messages. | | `block` *Type: PNMessageSizeCalculationCompletionBlock | Completion `block` which will be called when the `message` size calculation is complete. | #### Get size of message with storage, metadata, and block ```objectivec - (void)sizeOfMessage:(id)message toChannel:(NSString *)channel storeInHistory:(BOOL)shouldStore withMetadata:(nullable NSDictionary *)metadata completion:(PNMessageSizeCalculationCompletionBlock)block; ``` | Parameter | Description | | --- | --- | | `message` *Type: id | The `message` for which the size needs be calculated. | | `channel` *Type: NSString | The `channel` on which the `message` has to be sent (it is part of request URI). | | `shouldStore` *Type: Bool | Should be `true` if the `message` is marked to be stored in Message Persistence. | | `metadata`Type: NSDictionary | `NSDictionary` with values which should be used by `PubNub` service to filter messages. | | `block` *Type: PNMessageSizeCalculationCompletionBlock | Completion `block` which will be called when the `message` size calculation is complete. | #### Get size of message with storage, compression, metadata, and block ```objectivec - (void)sizeOfMessage:(id)message toChannel:(NSString *)channel compressed:(BOOL)compressMessage storeInHistory:(BOOL)shouldStore withMetadata:(nullable NSDictionary *)metadata completion:(PNMessageSizeCalculationCompletionBlock)block; ``` | Parameter | Description | | --- | --- | | `message` *Type: id | The `message` for which the size needs be calculated. | | `channel` *Type: NSString | The `channel` on which the `message` has to be sent (it is part of request URI). | | `shouldStore` *Type: Bool | Should be `true` if the `message` is marked to be stored in Message Persistence. | | `compressMessage` *Type: Bool | Should be `true` if the `message` is compressed before sending to PubNub network. | | `metadata`Type: NSDictionary | `NSDictionary` with values which should be used by `PubNub` service to filter messages. | | `block` *Type: PNMessageSizeCalculationCompletionBlock | Completion `block` which will be called when the `message` size calculation is complete. | ### Sample code #### Get message size ```objectivec [self.client sizeOfMessage: @{@"Hello": @"world"} toChannel: @"announcement" withCompletion:^(NSInteger size) { // Process calculated target message size. }]; ``` ### Returns The message size ### Other examples #### Get size of message with metadata ```objectivec [self.client sizeOfMessage: @{@"Hello": @"World"} toChannel: @"announcement" withMetadata: @{@"senderID": @"bob"} completion:^(NSInteger size) { // Process calculated target message size. }]; ``` ## Encrypt This function allows to `encrypt` the data. ### Method(s) To `encrypt` the data you can use the following method(s) in Cocoa SDK. #### Encrypt data with key ```objectivec + (nullable NSString *)encrypt:(NSData *)data withKey:(NSString *)key; ``` | Parameter | Description | | --- | --- | | `data` *Type: NSData | Reference on `NSData` object which should be encrypted. | | `key` *Type: NSString | Reference on `key` which should be used to `encrypt` data basing on it. | #### Encrypt data with key and error ```objectivec + (nullable NSString *)encrypt:(NSData *)data withKey:(NSString *)key andError:(NSError *__autoreleasing *)error; ``` | Parameter | Description | | --- | --- | | `data` *Type: NSData | Reference on `NSData` object which should be encrypted. | | `key` *Type: NSString | Reference on `key` which should be used to `encrypt` data basing on it. | | `error`Type: NSError | Reference on pointer into which encryption `error` will be stored in case of encryption failure. Error can be related to JSON string serialization as well as encryption itself. | ### Sample code #### Encrypt part of message ```objectivec PNCryptoModule *aesCBCCrypto = [PNCryptoModule AESCBCCryptoModuleWithCipherKey:@"enigma" randomInitializationVector:YES]; NSString *message = @"No one should see me as plain"; NSData *messageData = [message dataUsingEncoding:NSUTF8StringEncoding]; NSString *secretMessage = [aesCBCCrypto encrypt:messageData]; ``` ### Returns Encrypted `Base64-encoded` string received from Foundation object. `nil` will be returned in case of failure. ## Decrypt This function allows to `decrypt` the data. ### Method(s) To `decrypt` the data you can use the following method(s) in Cocoa SDK. #### Decrypt data with key ```objectivec + (nullable NSData *)decrypt:(NSString *)object withKey:(NSString *)key; ``` | Parameter | Description | | --- | --- | | `object` *Type: NSString | Reference on previously encrypted `Base64-encoded` string which should be decrypted. | | `key` *Type: NSString | Reference on `key` which should be used to `decrypt` data. | #### Decrypt data with key and error ```objectivec + (nullable NSData *)decrypt:(NSString *)object withKey:(NSString *)key andError:(NSError *__autoreleasing *)error; ``` | Parameter | Description | | --- | --- | | `object` *Type: NSString | Reference on previously encrypted `Base64-encoded` string which should be decrypted. | | `key` *Type: NSString | Reference on `key` which should be used to `decrypt` data. | | `error`Type: NSError | Reference on pointer into which decryption `error` will be stored in case of decryption failure. Error can be related to JSON string deserialization as well as decryption itself. | ### Sample code #### Decrypt part of message ```objectivec PNCryptoModule *aesCBCCrypto = [PNCryptoModule AESCBCCryptoModuleWithCipherKey:@"enigma" randomInitializationVector:YES]; NSString *encryptedMessage = messagePayload[@"secret"]; NSData *secureData = [[NSData alloc] initWithBase64EncodedString:encryptedMessage options:0]; NSData *messageData = [aesCBCCrypto decrypt:secureData]; NSString *decryptedMessage = [[NSString alloc] initWithData:messageData encoding:NSUTF8StringEncoding]; ``` ### Returns Initial `NSData` which has been encrypted earlier. `nil` will be returned in case of decryption error. ## Push notification configuration ### PNAPNSNotificationConfiguration `PNAPNSNotificationConfiguration` instance allow to configure how notification should be delivered using HTTP/2-based APNs. #### Method(s) ##### Configure notifications ```objectivec + (instancetype)defaultConfiguration ``` Create default configuration with single target configured against `PNAPNSDevelopment` environment `NSBundle.mainBundle.bundleIdentifier` as topic name. ##### Configure notifications with targets ```objectivec + (instancetype)configurationWithTargets:(NSArray *)targets ``` | Parameter | Description | | --- | --- | | `targets` *Type: `NSArray< [PNAPNSNotificationTarget](#pnapnsnotificationtarget) *> *` | List of topics which should receive this notification. Default target with `NSBundle.mainBundle.bundleIdentifier` topic and `PNAPNSDevelopment` environment will be used if list is empty. | ##### Configure notifications with expiration dates ```objectivec + (instancetype)configurationWithCollapseID:(nullable NSString *)collapseId expirationDate:(nullable NSDate *)date targets:(NSArray *)targets; ``` | Parameter | Description | | --- | --- | | `collapseId`Type: NSString | Notification group / collapse identifier. Value will be used in APNs POST request as `apns-collapse-id` header value. | | `date`Type: NSDate | Date till which APNS will try to deliver notification to target device. Value will be used in APNs POST request as `apns-expiration` header value. | | `targets` *Type: `NSArray< [PNAPNSNotificationTarget](#pnapnsnotificationtarget) *> *` | List of topics which should receive this notification. Default target with `NSBundle.mainBundle.bundleIdentifier` topic and `PNAPNSDevelopment` environment will be used if list is empty. | #### Sample code Create and configure configuration instance which will collapse invitation notifications and retry to deliver notification (APNS) for next 10 seconds if device off-line: ```objectivec PNAPNSNotificationConfiguration *configuration = nil; PNNotificationsPayload *builder = nil; PNAPNSNotificationTarget *target = [PNAPNSNotificationTarget targetForTopic:@"com.meetings.chat.app"]; NSDate *expirationDate = [NSDate dateWithTimeIntervalSinceNow:10]; configuration = [PNAPNSNotificationConfiguration configurationWithCollapseID:@"invitations" expirationDate:expirationDate targets:@[target]]; ``` #### Response Configured and ready to use `PNAPNSNotificationConfiguration` instance. ### PNAPNSNotificationPayload `PNAPNSNotificationPayload` instance provides access to options specific only to mobile push notifications sent with APNs. #### Properties | Parameter | Description | | --- | --- | | `configurations`Type: `NSArray< [PNAPNSNotificationConfiguration](#pnapnsnotificationconfiguration) *> *` | List of HTTP/2-based APNs delivery configurations. If list is empty when payload for `PNAPNS2Push` has been requested, it will create default configuration for `PNAPNSDevelopment` environment and `NSBundle.mainBundle.bundleIdentifier` as topic name. | | `notification`Type: NSMutableDictionary | Object with parameters which specify user-visible key-value pairs. | | `payload`Type: NSMutableDictionary | Platform specific notification payload. In addition to data required to make notification visual presentation it can be used to pass additional information which should be sent to remote device. | | `silent`Type: BOOL | Whether operation system should handle notification layout by default or not. `alert`, `sound` and `badge` will be removed from resulting payload if set to `YES`. | ### PNAPNSNotificationTarget `PNAPNSNotificationTarget` instance allow to configure APNS notification recipient. #### Method(s) ##### Configure notifications with targets ```objectivec + (instancetype)defaultTarget ``` Create default target configured against `PNAPNSDevelopment` environment `NSBundle.mainBundle.bundleIdentifier` as topic name. ##### Configure notifications with topics ```objectivec + (instancetype)targetForTopic:(NSString *)topic ``` | Parameter | Description | | --- | --- | | `topic` *Type: NSString | Notifications topic name (usually it is application's bundle identifier). Value will be used in APNs POST request as `apns-topic` header value. | ##### Configure notifications with environments ```objectivec + (instancetype)targetForTopic:(NSString *)topic inEnvironment:(PNAPNSEnvironment)environment withExcludedDevices:(nullable NSArray *)excludedDevices; ``` | Parameter | Description | | --- | --- | | `topic` *Type: NSString | Notifications topic name (usually it is application's bundle identifier). Value will be used in APNs POST request as `apns-topic` header value. | | `environment` *Type: PNAPNSEnvironment | One of `PNAPNSEnvironment` fields which specify environment within which registered devices to which notifications should be delivered. `PNAPNSEnvironment` fields: PNAPNSDevelopment, PNAPNSProduction | | `excludedDevices` *Type: `NSArray *` | List of devices (their push tokens) to which this notification shouldn't be delivered. | #### Sample code Create and configure APNS notification target, which excludes current device from recipients list: ```objectivec PNAPNSNotificationTarget *target = [PNAPNSNotificationTarget targetForTopic:@"com.meetings.chat.app" inEnvironment:PNAPNSProduction withExcludedDevices:@[self.currentDevicePushToken]]; ``` #### Response Configured and ready to use `PNAPNSNotificationTarget` instance. ### PNFCMNotificationPayload `PNFCMNotificationPayload` instance provides access to options specific only to mobile push notifications sent with FCM. #### Properties | Parameter | Description | | --- | --- | | `notification`Type: NSMutableDictionary | Object with parameters which specify user-visible key-value pairs. | | `data`Type: NSMutableDictionary | Custom key-value object with additional information which will be passed to device along with displayable notification information. All object and scalar type value should be converted to strings before passing to this object. Keys shouldn't match: `from`, `message_type` or start with `google` or `gcm`. Also as key can't be used any word defined in [this table](https://firebase.google.com/docs/cloud-messaging/http-server-ref#notification-payload-support) | | `silent`Type: BOOL | Whether operation system should handle notification layout by default or not. `notification` key with it's content will be moved from root level under `data` key. | | `icon`Type: NSString | Icon which should be shown on the left from notification title instead of application icon. | | `tag`Type: NSString | Unique notification identifier which can be used to publish update notifications (they will previous notification with same `tag`). | | `payload`Type: NSMutableDictionary | Platform specific notification payload. In addition to data required to make notification visual presentation it can be used to pass additional information which should be sent to remote device. | ### PNMPNSNotificationPayload `PNMPNSNotificationPayload` instance provides access to options specific only to mobile push notifications sent with MPNS. #### Properties | Parameter | Description | | --- | --- | | `backContent`Type: NSString | Message which should be shown in notification body (text for back tile). **40** characters long to fit into tile. | | `backTitle`Type: NSString | Additional information which may explain reason why this notification has been delivered. Maximum **15** characters long. | | `count`Type: NSNumber | Value between **1-99** which will be shown on the tile. | | `title`Type: NSString | Title of the tile. | | `type`Type: NSString | Type of notification which should be presented to the user. | | `payload`Type: NSMutableDictionary | Platform specific notification payload. In addition to data required to make notification visual presentation it can be used to pass additional information which should be sent to remote device. | ### PNNotificationsPayload `PNNotificationsPayload` instance provides convenient method and properties which allow to setup notification for multiple platforms without getting into details how they should be formatted. Builder instance contain additional set of properties which allow to fine tune payloads for particular platforms and even access to *RAW* payload dictionaries. #### Method(s) ```objectivec + (instancetype)payloadsWithNotificationTitle:(nullable NSString *)title body:(nullable NSString *)body; ``` | Parameter | Description | | --- | --- | | `title`Type: NSString | Short text which should be shown at the top of notification instead of application name. | | `body`Type: NSString | Message which should be shown in notification body (under title line). | | `subtitle`Type: NSString | Additional information which may explain reason why this notification has been delivered. | | `badge`Type: NSNumber | Number which should be shown in space designated by platform (for example atop of application icon). | | `sound`Type: NSString | Path to file with sound or name of system sound which should be played upon notification receive. | | `apns` *Type: [PNAPNSNotificationPayload](#pnapnsnotificationpayload) | Access to APNS specific notification builder. | | `fcm` *Type: [PNFCMNotificationPayload](#pnfcmnotificationpayload) | Access to FCM specific notification builder. | #### Sample code Create notification payload builder with pre-defined notification title and body: ```objectivec PNNotificationsPayload *builder = nil; builder = [PNNotificationsPayload payloadsWithNotificationTitle:@"Chat invitation" body:@"You have been invited to 'quiz' chat"]; ``` #### Response Configured and ready to use `PNNotificationsPayload` instance. #### Other examples #### Generate simple notification payload for FCM and APNS ```objectivec PNNotificationsPayload *builder = nil; builder = [PNNotificationsPayload payloadsWithNotificationTitle:@"Chat invitation" body:@"You have been invited to 'quiz' chat"]; builder.sound = @"default"; NSLog(@"Notifications payload: %@", [builder dictionaryRepresentationFor:PNAPNSPush|PNFCMPush]); ``` ##### Output ```objectivec { "pn_apns": { "aps": { "alert": { "body": "You have been invited to 'quiz' chat", "title": "Chat invitation" }, "sound": "default" } }, "pn_fcm": { "notification": { "body": "You have been invited to 'quiz' chat", "title": "Chat invitation" }, "android": { "notification": { "sound": "default" } } } } ``` #### Generate simple notification payload for FCM and HTTP/2-based APNs (default configuration) ```objectivec PNNotificationsPayload *builder = nil; builder = [PNNotificationsPayload payloadsWithNotificationTitle:@"Chat invitation" body:@"You have been invited to 'quiz' chat"]; builder.sound = @"default"; NSLog(@"Notifications payload: %@", [builder dictionaryRepresentationFor:PNAPNS2Push|PNFCMPush]); ``` ##### Output ```objectivec { "pn_apns": { "aps": { "alert": { "body": "You have been invited to 'quiz' chat", "title": "Chat invitation" }, "sound": "default" }, "pn_push": [ { "targets": [ { "environment": "development", "topic": "com.meetings.chat.app" } ], "version": "v2" } ] }, "pn_fcm": { "notification": { "body": "You have been invited to 'quiz' chat", "title": "Chat invitation" } "android": { "notification": { "sound": "default" } } } } ``` #### Generate simple notification payload for FCM and HTTP/2-based APNs (custom configuration) ```objectivec PNAPNSNotificationConfiguration *configuration = nil; PNNotificationsPayload *builder = nil; PNAPNSNotificationTarget *target = [PNAPNSNotificationTarget targetForTopic:@"com.meetings.chat.app"]; NSDate *expirationDate = [NSDate dateWithTimeIntervalSinceNow:10]; configuration = [PNAPNSNotificationConfiguration configurationWithCollapseID:@"invitations" expirationDate:expirationDate targets:@[target]]; builder = [PNNotificationsPayload payloadsWithNotificationTitle:@"Chat invitation" body:@"You have been invited to 'quiz' chat"]; builder.apns.configurations = @[configuration]; NSLog(@"Notifications payload: %@", [builder dictionaryRepresentationFor:PNAPNS2Push|PNFCMPush]); ``` ##### Output ```objectivec { "pn_apns": { "aps": { "alert": { "body": "Chat invitation", "title": "You have been invited to 'quiz' chat" } }, "pn_push": [ { "collapse_id": "invitations", "expiration": "2019-11-28T22:06:09Z", "targets": [ { "environment": "development", "topic": "com.meetings.chat.app" } ], "version": "v2" } ] }, "pn_fcm": { "notification": { "body": "You have been invited to 'quiz' chat", "title": "Chat invitation" } } } ``` Example above show how to create notification payload which APNS will try to redeliver few times (if devices not active) and give up after **10** seconds since moment when it has been scheduled. Additionally this invitation notification will be grouped along with other invitation notifications (using provided `collapse_id` as group identifier) and shown as one in notification center. ```objectivec - (NSDictionary *)dictionaryRepresentationFor:(PNPushType)pushTypes ``` Build notifications platform for requested platforms (`pushTypes`). | Parameter | Description | | --- | --- | | `pushTypes` *Type: PNPushType | Bitfield with fields from `PNPushType` which specify platforms for which payload should be added to final dictionary. `PNPushType` fields: PNAPNSPush, PNAPNS2Push, PNFCMPush, PNMPNSPush | #### Sample code Publish message with notification payload: ```objectivec PNNotificationsPayload *builder = nil; builder = [PNNotificationsPayload payloadsWithNotificationTitle:@"Chat invitation" body:@"You have been invited to 'quiz' chat"]; NSDictionary *payload = [builder dictionaryRepresentationFor:PNAPNS2Push|PNFCMPush]; NSDictionary *message = @{ @"message": @"Max invited you to 'quiz' chat room", @"roomID": @"ewuiogw9vewg0" }; [self.client publish:message toChannel:@"chat-bot" mobilePushPayload:payload withCompletion:^(PNPublishStatus *status) { // Handle publish results }]; ``` #### Response Dictionary with data, which can be sent with publish method call and trigger remote notifications for specified platforms.