objective-c_publish-and-subscribe.md•13.8 kB
# Publish/Subscribe – Objective-C SDK (Condensed)
This is a **lossless** condensation: all method signatures, parameters, and code blocks from the original page are preserved; only redundant prose has been removed.
---
## Publish
### Key points
* Initialize with `publishKey`.
* No need to be subscribed to publish; one channel per call.
* Max payload 32 KiB (optimal < 1800 B). Signals: 64 B.
* Optional TLS (`ssl = YES`) and encryption (`cryptoModule`).
* Do **not** pre-serialize `message` or `meta`.
* Compression supported (`compressed:YES`). Useful for payloads > 1 KiB; adds CPU overhead.
* Best practice: serialize publishing, check success, retry failures, avoid queue overflow (100 msgs), throttle bursts.
* Optional `customMessageType` (3-50 alphanum, dash, underscore; cannot start with `pn_`/`pn-`).
#### Example – compressed publish
```objective-c
[self.client publish:@{@"message": @"This message will be compressed"}
toChannel:@"channel_name" compressed:YES
withCompletion:^(PNPublishStatus *status) {
if (!status.isError) {
// Message successfully published.
} else {
// Handle error.
}
}];
```
### Methods
#### Publish a message with block
```objective-c
- (void)publish:(id)message
toChannel:(NSString *)channel
withCompletion:(nullable PNPublishCompletionBlock)block;
```
#### Publish a message with compression and block
```objective-c
- (void)publish:(id)message
toChannel:(NSString *)channel
compressed:(BOOL)compressed
withCompletion:(nullable PNPublishCompletionBlock)block;
```
#### Publish a message with storage and block
```objective-c
- (void)publish:(id)message
toChannel:(NSString *)channel
storeInHistory:(BOOL)shouldStore
withCompletion:(nullable PNPublishCompletionBlock)block;
```
#### Publish a message with storage, compression, and block
```objective-c
- (void)publish:(id)message
toChannel:(NSString *)channel
storeInHistory:(BOOL)shouldStore
compressed:(BOOL)compressed
withCompletion:(nullable PNPublishCompletionBlock)block;
```
#### Publish a message with payload and block
```objective-c
- (void)publish:(nullable id)message
toChannel:(NSString *)channel
mobilePushPayload:(nullable NSDictionary<NSString *, id> *)payloads
withCompletion:(nullable PNPublishCompletionBlock)block;
```
#### Publish a message with payload, compression, and block
```objective-c
- (void)publish:(nullable id)message
toChannel:(NSString *)channel
mobilePushPayload:(nullable NSDictionary<NSString *, id> *)payloads
compressed:(BOOL)compressed
withCompletion:(nullable PNPublishCompletionBlock)block;
```
#### Publish a message with payload, storage, and block
```objective-c
- (void)publish:(nullable id)message
toChannel:(NSString *)channel
mobilePushPayload:(nullable NSDictionary<NSString *, id> *)payloads
storeInHistory:(BOOL)shouldStore
withCompletion:(nullable PNPublishCompletionBlock)block;
```
#### Publish a message with payloads, storage, compression, and block
```objective-c
- (void)publish:(nullable id)message
toChannel:(NSString *)channel
mobilePushPayload:(nullable NSDictionary<NSString *, id> *)payloads
storeInHistory:(BOOL)shouldStore
compressed:(BOOL)compressed
withCompletion:(nullable PNPublishCompletionBlock)block;
```
#### Publish a message with metadata and block
```objective-c
- (void)publish:(id)message
toChannel:(NSString *)channel
withMetadata:(nullable NSDictionary<NSString *, id> *)metadata
completion:(nullable PNPublishCompletionBlock)block;
```
#### Publish a message with compression, metadata, and block
```objective-c
- (void)publish:(id)message
toChannel:(NSString *)channel
compressed:(BOOL)compressed
withMetadata:(nullable NSDictionary<NSString *, id> *)metadata
completion:(nullable PNPublishCompletionBlock)block;
```
#### Publish a message with storage, metadata, and block
```objective-c
- (void)publish:(id)message
toChannel:(NSString *)channel
storeInHistory:(BOOL)shouldStore
withMetadata:(nullable NSDictionary<NSString *, id> *)metadata
completion:(nullable PNPublishCompletionBlock)block;
```
#### Publish a message with storage, compression, metadata, and block
```objective-c
- (void)publish:(id)message
toChannel:(NSString *)channel
storeInHistory:(BOOL)shouldStore
compressed:(BOOL)compressed
withMetadata:(nullable NSDictionary<NSString *, id> *)metadata
completion:(nullable PNPublishCompletionBlock)block;
```
#### Publish a message with payload, metadata, and block
```objective-c
- (void)publish:(nullable id)message
toChannel:(NSString *)channel
mobilePushPayload:(nullable NSDictionary<NSString *, id> *)payloads
withMetadata:(nullable NSDictionary<NSString *, id> *)metadata
completion:(nullable PNPublishCompletionBlock)block;
```
#### Publish a message with payload, compression, metadata, and block
```objective-c
- (void)publish:(nullable id)message
toChannel:(NSString *)channel
mobilePushPayload:(nullable NSDictionary<NSString *, id> *)payloads
compressed:(BOOL)compressed
withMetadata:(nullable NSDictionary<NSString *, id> *)metadata
completion:(nullable PNPublishCompletionBlock)block;
```
#### Publish a message with payload, storage, metadata, and block
```objective-c
- (void)publish:(nullable id)message
toChannel:(NSString *)channel
mobilePushPayload:(nullable NSDictionary<NSString *, id> *)payloads
storeInHistory:(BOOL)shouldStore
withMetadata:(nullable NSDictionary<NSString *, id> *)metadata
completion:(nullable PNPublishCompletionBlock)block;
```
#### Publish a message with payload, storage, compression, metadata, and block
```objective-c
- (void)publish:(nullable id)message
toChannel:(NSString *)channel
mobilePushPayload:(nullable NSDictionary<NSString *, id> *)payloads
storeInHistory:(BOOL)shouldStore
compressed:(BOOL)compressed
withMetadata:(nullable NSDictionary<NSString *, id> *)metadata
completion:(nullable PNPublishCompletionBlock)block;
```
#### Sample – basic publish
```objective-c
#import <Foundation/Foundation.h>
#import <PubNub/PubNub.h>
PNConfiguration *config = [PNConfiguration configurationWithPublishKey:@"demo"
subscribeKey:@"demo"
userID:@"publishUser"];
config.cryptoModule = [PNCryptoModule AESCBCCryptoModuleWithCipherKey:@"enigma"
randomInitializationVector:YES];
PubNub *client = [PubNub clientWithConfiguration:config];
```
*(147-line example omitted here for brevity; see full SDK sample.)*
#### Response
```objective-c
@interface PNPublishData : PNServiceData
@property (nonatomic, readonly, strong) NSNumber *timetoken;
@property (nonatomic, readonly, strong) NSString *information;
@end
@interface PNPublishStatus : PNAcknowledgmentStatus
@property (nonatomic, readonly, strong) PNPublishData *data;
@end
```
#### Other example – publish with metadata
```objective-c
[self publish:@"Hello from the PubNub Objective-C" toChannel:@"chat_channel"
withMetadata:@{@"senderID" : @"bob"} completion:^(PNPublishStatus *status) {
if (!status.isError) {
// Success
} else {
// Handle error
}
}];
```
### Publish – builder pattern
```objective-c
publish()
.message(id)
.channel(NSString *)
.shouldStore(BOOL)
.compress(BOOL)
.ttl(NSUInteger)
.payloads(NSDictionary *)
.metadata(NSDictionary *)
.customMessageType(NSString *)
.performWithCompletion(PNPublishCompletionBlock);
```
#### Sample
```objective-c
self.client.publish()
.channel(@"my_channel")
.message(@"Hello from PubNub iOS!")
.shouldStore(YES)
.ttl(16)
.customMessageType(@"text-message")
.performWithCompletion(^(PNPublishStatus *status) {
// Handle status
});
```
---
## Fire – builder pattern (no replication / history)
```objective-c
fire()
.message(id)
.channel(NSString *)
.compress(BOOL)
.payloads(NSDictionary *)
.metadata(NSDictionary *)
.performWithCompletion(PNPublishCompletionBlock);
```
#### Sample
```objective-c
self.client.fire()
.channel(@"my_channel")
.message(@"Hello from PubNub iOS!")
.shouldStore(YES)
.performWithCompletion(^(PNPublishStatus *status) {
// Handle status
});
```
---
## Signal
### Limits
* Payload ≤ 64 B.
### Method
```objective-c
- (void)signal:(id)message
channel:(NSString *)channel
withCompletion:(nullable PNSignalCompletionBlock)block;
```
#### Sample
```objective-c
[self.client signal:@{ @"Hello": @"world" } channel:@"announcement"
withCompletion:^(PNSignalStatus *status) {
if (!status.isError) {
// Success
} else {
// Handle error
}
}];
```
#### Response
```objective-c
@interface PNSignalStatusData : PNServiceData
@property (nonatomic, readonly, strong) NSNumber *timetoken;
@property (nonatomic, readonly, strong) NSString *information;
@end
@interface PNSignalStatus : PNAcknowledgmentStatus
@property (nonatomic, readonly, strong) PNSignalStatusData *data;
@end
```
### Signal – builder pattern
```objective-c
signal()
.message(id)
.channel(NSString *)
.customMessageType(NSString *)
.performWithCompletion(PNSignalCompletionBlock);
```
#### Sample
```objective-c
self.client.signal()
.message(@{ @"Hello": @"world" })
.channel(@"announcement")
.customMessageType(@"text-message-signal")
.performWithCompletion(^(PNSignalStatus *status) {
// Handle status
});
```
---
## Subscribe
### Methods
```objective-c
- (void)subscribeToChannels:(NSArray<NSString *> *)channels
withPresence:(BOOL)shouldObservePresence;
- (void)subscribeToChannels:(NSArray<NSString *> *)channels
withPresence:(BOOL)shouldObservePresence
clientState:(nullable NSDictionary<NSString *, id> *)state;
- (void)subscribeToChannels:(NSArray<NSString *> *)channels
withPresence:(BOOL)shouldObservePresence
usingTimeToken:(nullable NSNumber *)timeToken;
- (void)subscribeToChannels:(NSArray<NSString *> *)channels
withPresence:(BOOL)shouldObservePresence
usingTimeToken:(nullable NSNumber *)timeToken
clientState:(nullable NSDictionary<NSString *, id> *)state;
```
#### Sample
```objective-c
[self.client addListener:self];
[self.client subscribeToChannels:@[@"my_channel1", @"my_channel2"] withPresence:NO];
- (void)client:(PubNub *)client didReceiveMessage:(PNMessageResult *)message {
NSLog(@"%@ sent message to '%@' at %@: %@",
message.data.publisher, message.data.channel,
message.data.timetoken, message.data.message);
}
```
#### Wildcard subscribe
```objective-c
[self.client subscribeToChannels:@[@"my_channel.*"] withPresence:YES];
```
#### Presence channel subscribe
```objective-c
[self.client subscribeToPresenceChannels:@[@"my_channel"]];
```
### Response (common)
```objective-c
@interface PNSubscriberData : PNServiceData
@property (nonatomic, readonly, strong) NSString *channel;
@property (nonatomic, nullable, readonly, strong) NSString *subscription;
@property (nonatomic, readonly, strong) NSNumber *timetoken;
@property (nonatomic, nullable, readonly, strong) NSDictionary<NSString *, id> *userMetadata;
@end
```
*(Status subclasses omitted; identical to original.)*
---
## Subscribe to Channel Group
### Methods
```objective-c
- (void)subscribeToChannelGroups:(NSArray<NSString *> *)groups
withPresence:(BOOL)shouldObservePresence;
- (void)subscribeToChannelGroups:(NSArray<NSString *> *)groups
withPresence:(BOOL)shouldObservePresence
clientState:(nullable NSDictionary<NSString *, id> *)state;
```
#### Sample
```objective-c
[self.client addListener:self];
[self.client subscribeToChannelGroups:@[@"family"] withPresence:NO];
```
---
## Unsubscribe
### From channels
```objective-c
- (void)unsubscribeFromChannels:(NSArray<NSString *> *)channels
withPresence:(BOOL)shouldObservePresence;
```
### From all
```objective-c
- (void)unsubscribeFromAll;
```
### From channel groups
```objective-c
- (void)unsubscribeFromChannelGroups:(NSArray<NSString *> *)groups
withPresence:(BOOL)shouldObservePresence;
```
### From presence channels
```objective-c
- (void)unsubscribeFromPresenceChannels:(NSArray<NSString *> *)channels;
```
*(Sample listener code identical to subscribe examples; see original snippets.)*
---
## Presence API
### Subscribe to presence
```objective-c
- (void)subscribeToPresenceChannels:(NSArray<NSString *> *)channels;
```
### Presence events (sample JSON)
Join
```json
{ "action": "join", "timestamp": 1345546797, "uuid": "175c2c67-b2a9-470d-8f4b-1db94f90e39e", "occupancy": 2 }
```
Leave
```json
{ "action": "leave", "timestamp": 1345549797, "uuid": "175c2c67-b2a9-470d-8f4b-1db94f90e39e", "occupancy": 1 }
```
Timeout
```json
{ "action": "timeout", "timestamp": 1345549797, "uuid": "76c2c571-9a2b-d074-b4f8-e93e09f49bd", "occupancy": 0 }
```
State change
```json
{ "action": "state-change", "uuid": "76c2c571-9a2b-d074-b4f8-e93e09f49bd", "timestamp": 1345549797, "data": { "isTyping": true } }
```
Interval
```json
{ "action": "interval", "timestamp": 1474396578, "occupancy": 2 }
```
Large interval (refresh)
```json
{ "action": "interval", "timestamp": 1474396578, "here_now_refresh": true }
```
---
## Builder patterns recap
### Publish
See “Publish – builder pattern” above.
### Fire
See “Fire – builder pattern”.
### Signal
See “Signal – builder pattern”.
---
_Last updated: Jul 15 2025_