Utility Methods API for Objective-C SDK

The methods on this page are utility methods that don't fit into other categories.

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 Objective-C SDK:

1- (void)sizeOfMessage:(id)message 
2            toChannel:(NSString *)channel 
3       withCompletion:(PNMessageSizeCalculationCompletionBlock)block;

* required

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	Referecnce on block which should be sent, when message size calculation will be completed.

1- (void)sizeOfMessage:(id)message 
2            toChannel:(NSString *)channel 
3           compressed:(BOOL)compressMessage 
4       withCompletion:(PNMessageSizeCalculationCompletionBlock)block;

* required

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	Referecnce on block which should be sent, when message size calculation will be completed.

1- (void)sizeOfMessage:(id)message 
2            toChannel:(NSString *)channel 
3       storeInHistory:(BOOL)shouldStore 
4       withCompletion:(PNMessageSizeCalculationCompletionBlock)block;

* required

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	Referecnce on block which should be sent, when message size calculation will be completed.

1- (void)sizeOfMessage:(id)message 
2            toChannel:(NSString *)channel 
3           compressed:(BOOL)compressMessage 
4       storeInHistory:(BOOL)shouldStore 
5       withCompletion:(PNMessageSizeCalculationCompletionBlock)block;

* required

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 Message Persistence API methods group.
block * Type: PNMessageSizeCalculationCompletionBlock	Referecnce on block which should be sent, when message size calculation will be completed.

1- (void)sizeOfMessage:(id)message 
2            toChannel:(NSString *)channel 
3         withMetadata:(nullable NSDictionary<NSString *, id> *)metadata 
4           completion:(PNMessageSizeCalculationCompletionBlock)block;

* required

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.

1- (void)sizeOfMessage:(id)message 
2            toChannel:(NSString *)channel 
3           compressed:(BOOL)compressMessage 
4         withMetadata:(nullable NSDictionary<NSString *, id> *)metadata 
5           completion:(PNMessageSizeCalculationCompletionBlock)block;

* required

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.

1- (void)sizeOfMessage:(id)message 
2            toChannel:(NSString *)channel 
3       storeInHistory:(BOOL)shouldStore 
4         withMetadata:(nullable NSDictionary<NSString *, id> *)metadata 
5           completion:(PNMessageSizeCalculationCompletionBlock)block;

* required

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

1- (void)sizeOfMessage:(id)message 
2            toChannel:(NSString *)channel 
3           compressed:(BOOL)compressMessage 
4       storeInHistory:(BOOL)shouldStore 
5         withMetadata:(nullable NSDictionary<NSString *, id> *)metadata 
6           completion:(PNMessageSizeCalculationCompletionBlock)block;

* required

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

1[self.client sizeOfMessage: @{@"Hello": @"world"} toChannel: @"announcement"
2             withCompletion:^(NSInteger size) {
3

4    // Process calculated target message size.
5 }];

Returns

The message size

Other examples

Get size of message with metadata

1[self.client sizeOfMessage: @{@"Hello": @"World"} toChannel: @"announcement"
2              withMetadata: @{@"senderID": @"bob"} completion:^(NSInteger size) {
3

4    // Process calculated target message size.
5}];

Push notification configuration

PNAPNSNotificationConfiguration

PNAPNSNotificationConfiguration instance allow to configure how notification should be delivered using HTTP/2-based APNs.

Method(s)

1+ (instancetype)defaultConfiguration

Create default configuration with single target configured against PNAPNSDevelopment environment NSBundle.mainBundle.bundleIdentifier as topic name.

1+ (instancetype)configurationWithTargets:(NSArray<PNAPNSNotificationTarget *> *)targets

* required

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.

1+ (instancetype)configurationWithCollapseID:(nullable NSString *)collapseId 
2                             expirationDate:(nullable NSDate *)date 
3                                    targets:(NSArray<PNAPNSNotificationTarget *> *)targets;

* required

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:

1PNAPNSNotificationConfiguration *configuration = nil;
2PNNotificationsPayload *builder = nil;
3

4PNAPNSNotificationTarget *target = [PNAPNSNotificationTarget targetForTopic:@"com.meetings.chat.app"];
5NSDate *expirationDate = [NSDate dateWithTimeIntervalSinceNow:10];
6configuration = [PNAPNSNotificationConfiguration configurationWithCollapseID:@"invitations"
7                                                              expirationDate:expirationDate
8                                                                     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)

1+ (instancetype)defaultTarget

Create default target configured against PNAPNSDevelopment environment NSBundle.mainBundle.bundleIdentifier as topic name.

1+ (instancetype)targetForTopic:(NSString *)topic

* required

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.

1+ (instancetype)targetForTopic:(NSString *)topic 
2                 inEnvironment:(PNAPNSEnvironment)environment 
3           withExcludedDevices:(nullable NSArray<NSData *> *)excludedDevices;

* required

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<NSDate *> *	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:

1PNAPNSNotificationTarget *target = [PNAPNSNotificationTarget targetForTopic:@"com.meetings.chat.app"
2                                                              inEnvironment:PNAPNSProduction
3                                                        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 fcm. Also as key can't be used any word defined in this table
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.

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)

1+ (instancetype)payloadsWithNotificationTitle:(nullable NSString *)title 
2                                         body:(nullable NSString *)body;

* required

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	Access to APNS specific notification builder.
fcm * Type: PNFCMNotificationPayload	Access to FCM specific notification builder.

Sample code

Create notification payload builder with pre-defined notification title and body:

1PNNotificationsPayload *builder = nil;
2builder = [PNNotificationsPayload payloadsWithNotificationTitle:@"Chat invitation"
3                                                           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

1PNNotificationsPayload *builder = nil;
2builder = [PNNotificationsPayload payloadsWithNotificationTitle:@"Chat invitation"
3                                                            body:@"You have been invited to 'quiz' chat"];
4builder.sound = @"default";
5

6NSLog(@"Notifications payload: %@", [builder dictionaryRepresentationFor:PNAPNSPush|PNFCMPush]);

Output

1{
2    "pn_apns": {
3        "aps": {
4            "alert": {
5                "body": "You have been invited to 'quiz' chat",
6                "title": "Chat invitation"
7            },
8            "sound": "default"
9        }
10    },
11    "pn_fcm": {
12        "notification": {
13            "body": "You have been invited to 'quiz' chat",
14            "title": "Chat invitation"
15        },
16        "android": {
17            "notification": {
18                "sound": "default"
19            }
20        }
21    }
22}

show all 22 lines

Generate simple notification payload for FCM and HTTP/2-based APNs (default configuration)

1PNNotificationsPayload *builder = nil;
2builder = [PNNotificationsPayload payloadsWithNotificationTitle:@"Chat invitation"
3                                                            body:@"You have been invited to 'quiz' chat"];
4builder.sound = @"default";
5

6NSLog(@"Notifications payload: %@", [builder dictionaryRepresentationFor:PNAPNS2Push|PNFCMPush]);

Output

1{
2    "pn_apns": {
3        "aps": {
4            "alert": {
5                "body": "You have been invited to 'quiz' chat",
6                "title": "Chat invitation"
7            },
8            "sound": "default"
9        },
10        "pn_push": [
11            {
12                "targets": [
13                    {
14                        "environment": "development",
15                        "topic": "com.meetings.chat.app"
16                    }
17                ],
18                "version": "v2"
19            }
20        ]
21    },
22    "pn_fcm": {
23        "notification": {
24            "body": "You have been invited to 'quiz' chat",
25            "title": "Chat invitation"
26        },
27        "android": {
28            "notification": {
29                "sound": "default"
30            }
31        }
32    }
33}

show all 33 lines

Generate simple notification payload for FCM and HTTP/2-based APNs (custom configuration)

1PNAPNSNotificationConfiguration *configuration = nil;
2PNNotificationsPayload *builder = nil;
3

4PNAPNSNotificationTarget *target = [PNAPNSNotificationTarget targetForTopic:@"com.meetings.chat.app"];
5NSDate *expirationDate = [NSDate dateWithTimeIntervalSinceNow:10];
6configuration = [PNAPNSNotificationConfiguration configurationWithCollapseID:@"invitations"
7                                                                expirationDate:expirationDate
8                                                                        targets:@[target]];
9

10builder = [PNNotificationsPayload payloadsWithNotificationTitle:@"Chat invitation"
11                                                            body:@"You have been invited to 'quiz' chat"];
12builder.apns.configurations = @[configuration];
13

14NSLog(@"Notifications payload: %@", [builder dictionaryRepresentationFor:PNAPNS2Push|PNFCMPush]);

Output

1{
2    "pn_apns": {
3        "aps": {
4            "alert": {
5                "body": "Chat invitation",
6                "title": "You have been invited to 'quiz' chat"
7            }
8        },
9        "pn_push": [
10            {
11                "collapse_id": "invitations",
12                "expiration": "2019-11-28T22:06:09Z",
13                "targets": [
14                    {
15                        "environment": "development",
16                        "topic": "com.meetings.chat.app"
17                    }
18                ],
19                "version": "v2"
20            }
21        ]
22    },
23    "pn_fcm": {
24        "notification": {
25            "body": "You have been invited to 'quiz' chat",
26            "title": "Chat invitation"
27        }
28    }
29}

show all 29 lines

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.

1- (NSDictionary *)dictionaryRepresentationFor:(PNPushType)pushTypes

Build notifications platform for requested platforms (pushTypes).

* required

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

Sample code

Publish message with notification payload:

1PNNotificationsPayload *builder = nil;
2builder = [PNNotificationsPayload payloadsWithNotificationTitle:@"Chat invitation"
3                                                           body:@"You have been invited to 'quiz' chat"];
4NSDictionary *payload = [builder dictionaryRepresentationFor:PNAPNS2Push|PNFCMPush];
5NSDictionary *message = @{
6    @"message": @"Max invited you to 'quiz' chat room",
7    @"roomID": @"ewuiogw9vewg0"
8};
9

10[self.client publish:message toChannel:@"chat-bot" mobilePushPayload:payload
11      withCompletion:^(PNPublishStatus *status) {
12   // Handle publish results
13}];

Response

Dictionary with data, which can be sent with publish method call and trigger remote notifications for specified platforms.