Publish/Subscribe API for Unreal SDK
PubNub's publish-processing latency, the time to accept and acknowledge a publish request, is about 0.5 ms within the same region. Send a message to one recipient or broadcast to thousands of subscribers.
For higher-level conceptual details on publishing and subscribing, refer to Connection Management and to Publish Messages.
Asynchronous and synchronous method execution
Most PubNub Unreal SDK methods are available in both asynchronous and synchronous variants.
-
Asynchronous methods (
Asyncsuffix) returnvoidand take an optional delegate parameter that fires when the operation completes.1PubnubClient->PublishMessageAsync("my-channel", "Hello!", OnPublishMessageResponseDelegate);You can also use native callbacks that accept lambdas instead of dynamic delegates. Native callback types have the
Nativesuffix (for example,FOnPubnubPublishMessageResponseNative). -
Synchronous methods (no suffix) block the main game thread until the operation completes and return a result struct directly.
1FPubnubPublishMessageResult Result = PubnubClient->PublishMessage("my-channel", "Hello!");
Publish
PublishMessage() sends a message to all channel subscribers. PubNub replicates the message across its points of presence and delivers it to all subscribed clients on that channel.
- Prerequisites and limitations
- Security
- Message data
- Size
- Publish rate
- Custom message type
- Best practices
- You must initialize PubNub with the
publishKey. - You don't have to be subscribed to a channel to publish to it.
- You cannot publish to multiple channels simultaneously.
Secure messages with Transport Layer Security (TLS) or Secure Sockets Layer (SSL) during initialization. You can also encrypt messages by assigning a crypto module to FPubnubConfig::CryptoModule before you create the client. For details, refer to Encryption.
The message can contain any JavaScript Object Notation (JSON)-serializable data (objects, arrays, integers, strings). Avoid special classes or functions. Strings can include any UTF‑8 characters.
Don't JSON serialize
You should not JSON serialize the message and meta parameters when sending signals, messages, or files as the serialization is automatic. Pass the full object as the message/meta payload and let PubNub handle everything.
The maximum message size is 32 KiB. This includes the escaped character count and the channel name. Aim for under 1,800 bytes for optimal performance.
If your message exceeds the limit, you'll receive a Message Too Large error. To learn more, see Message size limits. To calculate payload size, use the message size calculator.
Need larger messages?
PubNub supports payloads larger than the standard limit, but raising it requires verifying compatibility with your use case.
Talk to our team to discuss increasing the message size limit for your use case.
You can publish as fast as bandwidth allows. There is a soft throughput limit because messages may drop if subscribers can't keep up.
For example, publishing 200 messages at once may cause the first 100 to drop if a subscriber hasn't received any yet. The in-memory queue stores only 100 messages.
You can optionally provide the CustomMessageType parameter to add your business-specific label or category to the message, for example text, action, or poll.
- Publish to a channel serially (not concurrently).
- Verify a success return code (for example,
[1,"Sent","136074940..."]). - Publish the next message only after a success return code.
- On failure (
[0,"blah","<timetoken>"]), retry. - Keep the in-memory queue under 100 messages to avoid drops.
- Throttle bursts to meet latency needs (for example, no more than 5 messages per second).
You can call PublishMessage() on a Channel entity (which already knows its channel) or directly on the PubNub client by passing the channel name explicitly.
Channel entity
Method(s)
To publish to a channel, you must first create a Channel entity where you provide the name of the channel you want to publish to.
1UPubnubChannelEntity* ChannelEntity = PubnubClient->CreateChannelEntity("my-channel");
2
3ChannelEntity->PublishMessage(
4 FString Message,
5 FOnPubnubPublishMessageResponse OnPublishMessageResponse,
6 FPubnubPublishSettings PublishSettings = FPubnubPublishSettings()
7);
Messagerequired#- The message to publish. Can be a literal string or JSON-formatted string containing serialized data.
OnPublishMessageResponse#- The delegate for the operation's result.
You can also use a native callback of the typeFOnPubnubPublishMessageResponseNativeto handle the result using a lambda. PublishSettings#- Struct defining publish configuration.
FPubnubPublishSettings
StoreInHistory#- Whether to store the message so it is available to be returned by the History API.
trueby default. Ttl#- Time-to-live (TTL) for the message in hours. If not specified, the message will use the default retention period configured for the key.
MetaData#- A JSON object containing additional (meta) data about the message which you can use with the filtering ability.
PublishMethod#- Which HTTP method to use for the publish transaction. Default is
PPM_SendViaGET. Available values:
PPM_SendViaGET: puts the message in the URL path. You can't compress it.PPM_SendViaPOST: puts the message in the request body. Required for compression.
Compress#- Whether to gzip the request body. Default is
PPC_No. Available values:
PPC_No: sends the body uncompressed.PPC_Yes: sends the body gzip-compressed. Applies only whenPublishMethodisPPM_SendViaPOST. It doesn't switch a GET publish to POST.
CustomMessageType#- A case-sensitive, alphanumeric string from 3 to 50 characters describing the business-specific label or category of the message. Dashes
-and underscores_are allowed. The value cannot start with special characters or the stringpn_orpn-.
Examples:text,action,poll.
Sample code
Publish a message to a channel
Subscribe to the channel
Before running the above publish example (either using the Debug Console or in a separate script running in a new terminal window), subscribe to the same channel that you publish the message to.
Returns
This function is void, but the delegate returns the FOnPubnubPublishMessageResponse struct.
FOnPubnubPublishMessageResponse
| Field | Type | Description |
|---|---|---|
Result | FPubnubOperationResult | The result of the operation. |
PublishedMessage | FPubnubMessageData | A struct containing the result of the operation. |
FPubnubMessageData
| Field | Type | Description |
|---|---|---|
Message | FString | The message itself. |
Channel | FString | Channel that the message was published to. |
UserID | FString | The message information about the publisher. |
Timetoken | FString | The time token of the message, indicating when it was published. |
Metadata | FString | The message metadata, as published. |
MessageType | EPubnubMessageType | Indicates the message type: a signal, published, or another type. |
CustomMessageType | FString | User-provided message type. |
MatchOrGroup | FString | Subscription match or the channel group. |
region | int | Region of the message. Always 0. |
flags | int | Message flags. |
EPubnubMessageType
| Field | Description |
|---|---|
PMT_Signal | Indicates that the message was received as a signal. |
PMT_Published | Indicates that the message was published. |
PMT_Action | Indicates an action on a published message. |
PMT_Objects | Message about Objects. |
PMT_Files | Message about Files. |
FOnPubnubPublishMessageResponseNative
| Field | Type | Description |
|---|---|---|
Result | const FPubnubOperationResult& | The result of the operation. |
PublishedMessage | const FPubnubMessageData& | A struct containing the result of the operation. |
Other examples
Publish a message with settings
Actor.h
1
Actor.cpp
1
Publish a message with result
Actor.h
1
Actor.cpp
1
PubNub client
Method(s)
1PubnubClient->PublishMessageAsync(
2 FString Channel,
3 FString Message,
4 FOnPubnubPublishMessageResponse OnPublishMessageResponse,
5 FPubnubPublishSettings PublishSettings = FPubnubPublishSettings()
6);
Channelrequired#- The channel ID to send the message to.
Messagerequired#- The message to publish. Can be a literal string or JSON-formatted string containing serialized data.
OnPublishMessageResponse#- The delegate for the operation's result.
You can also use a native callback of the typeFOnPubnubPublishMessageResponseNativeto handle the result using a lambda. PublishSettings#- Struct defining publish configuration.
Sample code
Publish a message to a channel
Returns
This method is void. The delegate returns the following struct:
FOnPubnubPublishMessageResponse
| Field | Type | Description |
|---|---|---|
Result | FPubnubOperationResult | The result of the operation. |
PublishedMessage | FPubnubMessageData | A struct containing the published message data including timetoken and channel information. |
FOnPubnubPublishMessageResponseNative
| Field | Type | Description |
|---|---|---|
Result | const FPubnubOperationResult& | The result of the operation. |
PublishedMessage | const FPubnubMessageData& | A struct containing the published message data including timetoken and channel information. |