Publish/Subscribe API for Unreal SDK

You can use PubNub's functionality via Blueprints or directly in C++ code.

• In Blueprints, the whole SDK is managed by a subsystem, so start by calling the Pubnub Subsystem node.

• In a C++ project, you have to add a dependency to PubnubLibrary:

  1. In your IDE, navigate to Source/_{YourProject}_/_{YourProject}_.Build.cs and add a dependency to PubnubLibrary.

     PrivateDependencyModuleNames.AddRange(new string[] { "PubnubLibrary" });

  2. Compile the code and run the project.

• In C++, you can use the PubNub SDK as any other Game Instance Subsystem.

  #include "Kismet/GameplayStatics.h"
  #include "PubnubSubsystem.h"
  
  UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
  UPubnubSubsystem* PubnubSubsystem = GameInstance->GetSubsystem<UPubnubSubsystem>();

  PubnubSubsystem now allows you to call all PubNub SDK functions, for example:

  PubnubSubsystem->SubscribeToChannel("MyChannel");

Usage in Blueprints and C++

PubNub delivers messages worldwide in less than 30 ms. 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.

Publish

publish() 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

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

Security

Secure messages with Transport Layer Security (TLS) or Secure Sockets Layer (SSL) during initialization. You can also encrypt messages.

Message data

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.

Size

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 or calculate payload size, see Message size limits.

Publish rate

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.

Custom message type

You can optionally provide the CustomMessageType parameter to add your business-specific label or category to the message, for example text, action, or poll.

Best practices

• 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).

Method(s)

PubnubSubsystem->PublishMessage(
    FString Channel,
    FString Message, 
    FOnPublishMessageResponse OnPublishMessageResponse,
    FPubnubPublishSettings PublishSettings = FPubnubPublishSettings()
);

* required

Parameter	Description
Message * Type: FString	The message to publish. Can be a literal string or JSON-formatted string containing serialized data.
Channel * Type: FString	The channel ID to send the message to.
PublishSettings Type: FPubnubPublishSettings	Struct defining publish configuration.
OnPublishMessageResponse Type: FOnPublishMessageResponse	The delegate for the operation's result. You can also use a native callback of the type FOnPublishMessageResponseNative to handle the result using a lambda.

FPubnubPublishSettings

* required

Parameter	Description
StoreInHistory Type: bool	Whether to store the message so it is available to be returned by the History API. true by default.
Ttl Type: int	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 Type: FString	A JSON object containing additional (meta) data about the message which you can use with the filtering ability.
PublishMethod Type: EPubnubPublishMethod	Which HTTP method to use for the publish transaction. Available values: PPM_SendViaGET PPM_SendViaPOST PPM_UsePATCH PPM_SendViaPOSTwithGZIP PPM_UsePATCHwithGZIP PPM_UseDELETE
Replicate Type: bool	If true, the message is replicated and is received by all subscribers. If false, the message is not replicated and is delivered only to Functions event handlers.
CustomMessageType Type: FString	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 string pn_ or pn-. Examples: text, action, poll.

Sample code

Reference code

Set up your Unreal project and follow the instructions in the lines marked with ACTION REQUIRED before running the code.

Publish a message to a channel

C++

Actor.h

Actor.cpp

Blueprint

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 FOnPublishMessageResponse struct.

FOnPublishMessageResponse

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. Not relevant in most cases.
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.

FOnPublishMessageResponseNative

Field	Type	Description
Result	const FPubnubOperationResult&	The result of the operation.
PublishedMessage	const FPubnubMessageData&	A struct containing the result of the operation.

Other examples

Reference code

Set up your Unreal project and follow the instructions in the lines marked with ACTION REQUIRED before running the code.

Publish a message with TTL

Actor.h

Actor.cpp

Publish a message with metadata

Actor.h

Actor.cpp

Signal

The signal() function is used to send a signal to all subscribers of a channel.

By default, signals are limited to a message payload size of 64 bytes. This limit applies only to the payload, and not to the URI or headers. If you require a larger payload size, contact support.

Method(s)

PubnubSubsystem->Signal(
    FString Channel, 
    FString Message,
    FOnSignalResponse OnSignalResponse,
    FPubnubSignalSettings SignalSettings = FPubnubSignalSettings()
);

* required

Parameter	Description
Channel * Type: FString	The channel ID to send the signal to.
Message * Type: FString	The message to publish. Can be a literal string or JSON-formatted string containing serialized data.
OnSignalResponse Type: FOnSignalResponse	The delegate for the operation's result. You can also use a native callback of the type FOnSignalResponseNative to handle the result using a lambda.
SignalSettings Type: FPubnubSignalSettings	Struct defining signal configuration.

FPubnubSignalSettings

* required

Parameter	Description
CustomMessageType Type: FString	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 string pn_ or pn-. Examples: text, action, poll.

Sample code

Reference code

Set up your Unreal project and follow the instructions in the lines marked with ACTION REQUIRED before running the code.

Signal a message to a channel

C++

Actor.h

Actor.cpp

Blueprint

Returns

This function is void, but the delegate returns the FOnSignalResponse struct.

FOnSignalResponse

Field	Type	Description
Result	FPubnubOperationResult	The result of the operation.
SignalMessage	FPubnubMessageData	A struct containing the result of the operation.

FOnSignalResponseNative

Field	Type	Description
Result	const FPubnubOperationResult&	The result of the operation.
SignalMessage	const FPubnubMessageData&	A struct containing the result of the operation.

Other examples

Reference code

Set up your Unreal project and follow the instructions in the lines marked with ACTION REQUIRED before running the code.

Signal with custom message type

Actor.h

Actor.cpp

Subscribe

Receive messages

Your app receives messages and events via event listeners. The OnMessageReceived event listener is a single point through which your app receives all the messages, signals, and events that are sent in any channel you are subscribed to.

For more information about adding a listener, refer to the Event Listeners section.

Description

This function causes the client to create an open TCP socket to the PubNub Real-Time Network and begin listening for messages on a specified channel ID. To subscribe to a channel ID, the client must send the appropriate SubscribeKey at initialization.

By default, a newly subscribed client will only receive messages published to the channel after the Subscribe() call completes.

Unsubscribing from all channels

Unsubscribing from all channels, and then subscribing to a new channel Y is not the same as subscribing to channel Y and then unsubscribing from the previously-subscribed channel(s). Unsubscribing from all channels resets the last-received timetoken and thus, there could be some gaps in the subscription that may lead to message loss.

Method(s)

// subscribe to a channel
PubnubSubsystem->SubscribeToChannel(FString Channel, FOnSubscribeOperationResponse OnSubscribeToChannelResponse, FPubnubSubscribeSettings SubscribeSettings = FPubnubSubscribeSettings());
// subscribe to a channel group
PubnubSubsystem->SubscribeToGroup(FString ChannelGroup, FOnSubscribeOperationResponse OnSubscribeToGroupResponse, FPubnubSubscribeSettings SubscribeSettings = FPubnubSubscribeSettings());

* required

Parameter	Description
Channel * Type: FString	The channel ID to subscribe to.
ChannelGroup * Type: FString	The channel group to subscribe to.
OnSubscribeToChannelResponse Type: FOnSubscribeOperationResponse	The delegate for the operation's result. You can also use a native callback of the type FOnSubscribeOperationResponseNative to handle the result using a lambda.
OnSubscribeToGroupResponse Type: FOnSubscribeOperationResponse	The delegate for the operation's result. You can also use a native callback of the type FOnSubscribeOperationResponseNative to handle the result using a lambda.
SubscriptionSettings Type: FPubnubSubscriptionSettings	Struct defining subscription configuration.

FOnSubscribeOperationResponse

Field	Type	Description
Result	FPubnubOperationResult	The result of the operation.

FOnSubscribeOperationResponseNative

Field	Type	Description
Result	const FPubnubOperationResult&	The result of the operation.

FPubnubSubscriptionSettings

* required

Parameter	Description
ReceivePresenceEvents Type: bool	Whether to subscribe to presence events.

Sample code

Reference code

Set up your Unreal project and follow the instructions in the lines marked with ACTION REQUIRED before running the code.

C++

Actor.h

Actor.cpp

Event listeners

The response of the call is handled by adding a listener. Refer to the Event Listeners section for more details. Listeners should be added before calling the method.

Blueprint

Returns

This method doesn't have a return value. To receive messages, you must add a listener.

Other examples

Reference code

Set up your Unreal project and follow the instructions in the lines marked with ACTION REQUIRED before running the code.

Subscribe with presence

Requires Presence

This method requires that the Presence add-on is enabled for your key in the Admin Portal.

For information on how to receive presence events and what those events are, refer to Presence Events.

For any given channel there is an associated Presence channel. You can subscribe directly to the channel by appending -pnpres to the channel name or you can use the subscribe method with the ReceivePresenceEvents parameter set to true. For more information on presence events, refer to the Presence section.

Actor.h

Actor.cpp

Response

All presence events are received via a listener. For more information on the structure of the received events, refer to Event types.

Subscribe to channel group

Actor.h

Actor.cpp

Subscribe with lambda

Actor.h

Actor.cpp

Subscribe with result callback

Actor.h

Actor.cpp

Unsubscribe

When subscribed to a single channel, this function causes the client to issue a leave from the channel ID and close any open socket to the PubNub Network. For multiplexed channels, the specified channel(s) will be removed and the socket remains open until there are no more channels remaining in the list.

Unsubscribing from all channels

Unsubscribing from all channels, and then subscribing to a new channel Y is not the same as subscribing to channel Y and then unsubscribing from the previously-subscribed channel(s). Unsubscribing from all channels resets the last-received timetoken and thus, there could be some gaps in the subscription that may lead to message loss.

Method(s)

// unsubscribe from a channel
PubnubSubsystem->UnsubscribeFromChannel(FString Channel, FOnSubscribeOperationResponse OnUnsubscribeFromChannelResponse);
// unsubscribe from a channel group
PubnubSubsystem->UnsubscribeFromGroup(FString ChannelGroup, FOnSubscribeOperationResponse OnUnsubscribeFromGroupResponse);

* required

Parameter	Description
Channel * Type: FString	The channel ID to unsubscribe from.
ChannelGroup * Type: FString	The channel group to unsubscribe from.
OnUnsubscribeFromChannelResponse Type: FOnSubscribeOperationResponse	The delegate for the operation's result. You can also use a native callback of the type FOnSubscribeOperationResponseNative to handle the result using a lambda.
OnUnsubscribeFromGroupResponse Type: FOnSubscribeOperationResponse	The delegate for the operation's result. You can also use a native callback of the type FOnSubscribeOperationResponseNative to handle the result using a lambda.

Sample code

Reference code

Set up your Unreal project and follow the instructions in the lines marked with ACTION REQUIRED before running the code.

C++

Actor.h

Actor.cpp

Blueprint

Returns

This method doesn't have a return value.

Other examples

Reference code

Set up your Unreal project and follow the instructions in the lines marked with ACTION REQUIRED before running the code.

Unsubscribe from a channel group

Actor.h

Actor.cpp

Unsubscribe all

Unsubscribe from all channels and all channel groups.

Method(s)

PubnubSubsystem->UnsubscribeFromAll(FOnSubscribeOperationResponse OnUnsubscribeFromAllResponse);

* required

Parameter	Description
OnUnsubscribeFromAllResponse Type: FOnSubscribeOperationResponse	The delegate for the operation's result. You can also use a native callback of the type FOnSubscribeOperationResponseNative to handle the result using a lambda.

Sample code

Reference code

Set up your Unreal project and follow the instructions in the lines marked with ACTION REQUIRED before running the code.

C++

Actor.h

Actor.cpp

Blueprint

Returns

This method doesn't have a return value.

Complete example

Reference code

Set up your Unreal project and follow the instructions in the lines marked with ACTION REQUIRED before running the code.

ASample_PubSubFull.h

ASample_PubSubFull.cpp