Configuration API for Unreal SDK
Complete API reference for building real-time applications on PubNub with the Unreal Software Development Kit (SDK). This page covers configuration, initialization, client management, and event handling with concise, working examples.
The PubNub Unreal SDK uses a two-tier architecture:
UPubnubSubsystem- A Game Instance Subsystem that creates, returns, and destroys PubNub clients. It exposes onlyCreatePubnubClient(),GetPubnubClient(), andDestroyPubnubClient(). Access it from your Game Instance.UPubnubClient- An individual PubNub client with its own configuration, User ID, subscriptions, and event listeners.
Multiple clients
The SDK supports multiple clients in the same game, for different contexts such as users or keysets. The SDK doesn't create a client for you, so create each one with CreatePubnubClient(). The first client you create gets ID 0.
Client ID vs User ID
The Unreal Engine SDK uses two types of identifiers for different purposes:
| Identifier | Type | Purpose | Scope |
|---|---|---|---|
| Client ID | int | An internal SDK identifier. The SDK assigns it to each UPubnubClient instance in creation order (0, 1, 2, etc.). Use it only to retrieve or manage client instances within UPubnubSubsystem. | Local to your game instance. Not sent to PubNub. |
| User ID | FString | A PubNub identifier that represents the user or device connecting to PubNub. Required for all PubNub operations. Used for presence, App Context, access control, and message attribution. | Global across PubNub. Visible to other users and stored on PubNub servers. |
Required User ID
A single UPubnubClient (identified by its Client ID) always has exactly one User ID. If you need to represent multiple users, create multiple clients with CreatePubnubClient(), each with their own User ID.
Configuration and initialization
Reuse the client instance
Create one PubNub client and reuse it for the lifetime of the user or session. Don't call CreatePubnubClient() for every publish or operation. When a client is no longer needed, call DestroyClient() to release its connections and background resources.
For more information, refer to Reuse the client instance.
- C++
Use UPubnubSubsystem::CreatePubnubClient() to create a new UPubnubClient with your configuration. This is the only way to initialize PubNub. The SDK has no Project Settings page and creates no default client.
CreatePubnubClient() returns nullptr and logs an error if PublishKey, SubscribeKey, or UserID is empty.
1UPubnubClient* CreatePubnubClient(
2 FPubnubConfig Config,
3 FString DebugName = ""
4);
Configrequired#- Configuration struct for the PubNub SDK. Contains the following properties.
- property of Config:
PublishKeyrequired# - Publish Key from Admin Portal. Default:
"". Can't be empty. - property of Config:
SubscribeKeyrequired# - Subscribe Key from Admin Portal. Default:
"". Can't be empty. - property of Config:
SecretKey# - Secret Key from Admin Portal. For server or backend clients only. Never ship it in client builds. It gives the client root permissions for Access Manager. The SDK reads it only at creation, and you can't change it afterward. If
SecretKeyisn't empty, the client uses it from creation. There's no separate step to turn it on. Default:"". - property of Config:
UserIDrequired# - Identifies the user or device that connects to PubNub.
It's a UTF-8 encoded string of up to 92 alphanumeric characters.
Required for all operations. Default:"". Can't be empty. - property of Config:
LoggerConfig# - Logger setup used during client initialization. For details, refer to Logging.
- property of Config:
Origin# - PubNub origin host. The SDK reads it at creation. Leave it empty to use the default origin. Default:
"". - property of Config:
CryptoModule# - Payload crypto module. Call
InitCryptoModuleon it before you create the client. Leave it unset to publish and subscribe without payload encryption. Keep the module alive for the life of the client. Default:nullptr. For details, refer to Encryption. - property of Config:
PNSdkOverride# - Internal use only. Overrides the base SDK identifier. Default:
"". DebugName#- A name for the client used in debug logs. Useful for identifying clients when using multiple instances.
Returns
| Type | Description |
|---|---|
UPubnubClient* | A pointer to the newly created PubNub client, or nullptr if the configuration is invalid. Each client is assigned a unique Client ID starting from 0. |
Sample code
Asynchronous and synchronous method execution
Most PubNub Unreal SDK methods that perform network operations come in asynchronous and synchronous variants. Asynchronous methods use the Async suffix and take an optional delegate. Synchronous methods block until the operation completes and return a result struct (for example, FPubnubOperationResult). Configuration methods such as SetOrigin and GetOrigin are synchronous only. Client lifecycle uses CreatePubnubClient() and DestroyClient().
Required User ID
Always set the User ID to uniquely identify the user or device that connects to PubNub. Persist this User ID and keep it unchanged for the lifetime of the user or the device. CreatePubnubClient() fails if UserID is empty.
The following sample demonstrates creating a PubNub client with explicit configuration using CreatePubnubClient(). This approach gives you direct access to the UPubnubClient instance and is recommended when you need to manage multiple clients or want explicit control over the client lifecycle.
PubnubClient
The UPubnubClient class represents an individual PubNub client. Each client has its own configuration, User ID, subscriptions, and event listeners. Use this class to perform PubNub operations such as publishing messages, subscribing to channels, and managing App Context data.
The SDK supports creating multiple UPubnubClient instances. This is useful for:
- Supporting multiple users in split-screen or local multiplayer games
- Using different PubNub keysets for different purposes
- Managing separate subscription contexts
Encryption
UPubnubCryptoModule encrypts and decrypts messages. You choose which encryption algorithms it uses. Encryption is disabled by default.
The PubNub Unreal SDK includes two encryption implementations:
- 256-bit AES-CBC encryption (
UPubnubAesCryptor), recommended for new applications - Legacy encryption (
UPubnubLegacyCryptor), for compatibility with older PubNub implementations
For more general information on how encryption works, refer to the Message Encryption section.
To use encryption, initialize a UPubnubCryptoModule with InitCryptoModule() and assign it to FPubnubConfig::CryptoModule before you call CreatePubnubClient(). Once configured, the SDK encrypts every published message and decrypts every received message.
For more information on how to use the CryptoModule, refer to Encryption.
Create a client
Use CreatePubnubClient() to create a new PubNub client with a custom configuration.
Get a client
Use GetPubnubClient() to retrieve an existing client by its unique ID.
1UPubnubClient* GetPubnubClient(int ClientID);
ClientIDrequired#- The unique identifier of the client to retrieve. The first client you create with
CreatePubnubClient()has ID0.
Returns
| Type | Description |
|---|---|
UPubnubClient* | A pointer to the PubNub client with the specified ID, or nullptr if no client with that ID exists. |
Sample code
- C++
- Blueprint
1
Destroy a client
You can destroy a client in two ways:
- From
UPubnubSubsystem: useDestroyPubnubClient()when you have a reference to the subsystem and want to destroy a specific client by pointer. - From
UPubnubClient: useDestroyClient()when you want the client to destroy itself.
UPubnubSubsystem::DestroyPubnubClient()
1bool DestroyPubnubClient(UPubnubClient* ClientToDestroy);
ClientToDestroyrequired#- A pointer to the client to destroy.
Returns
| Type | Description |
|---|---|
bool | true if the client was successfully destroyed, false if the client was not found or was nullptr. |
UPubnubClient::DestroyClient()
1void DestroyClient();
This method takes no parameters and doesn't return a value. The client unregisters itself from the subsystem and cleans up its resources.
Sample code
- C++
- Blueprint
1
Get client ID
Returns the unique Client ID assigned to this client instance. This is an internal SDK identifier used to retrieve clients from UPubnubSubsystem. Do not confuse this with User ID, which identifies the user on PubNub servers.
1int GetClientID() const;
Returns
| Type | Description |
|---|---|
int | The unique Client ID. The first client you create has ID 0. Each later client gets the next ID (1, 2, 3, and so on). |
Set user ID
Sets the User ID for this client. The User ID is a PubNub identifier that represents the user or device on PubNub servers. It is used for presence, App Context, access control, and message attribution.
1FPubnubOperationResult SetUserID(FString UserID);
UserIDrequired#- A UTF-8 encoded string of up to 92 alphanumeric characters. This ID is visible to other users and stored on PubNub servers. It should persist for the lifetime of the user or device.
Returns
| Type | Description |
|---|---|
FPubnubOperationResult | Status of the operation. |
Sample code
1
Get user ID
Returns the current User ID for this client. This is the PubNub identifier visible to other users, not the internal Client ID.
1FString GetUserID();
Returns
| Type | Description |
|---|---|
FString | The current User ID. |
Sample code
1
Set origin
Sets the origin hostname for subsequent PubNub requests. Use it to point the client to a custom PubNub origin. To set the origin at creation instead, use FPubnubConfig::Origin.
1FPubnubOperationResult SetOrigin(FString Origin);
Originrequired#- The origin hostname to set. If empty, the client resets to the default origin.
Returns
| Type | Description |
|---|---|
FPubnubOperationResult | Success or failure of the update. Status is 200 and Error is false on success. |
Sample code
1
Get origin
Returns the currently set origin for the PubNub client.
1FString GetOrigin() const;
Returns
| Type | Description |
|---|---|
FString | The origin hostname currently in use, including the default when you set none. |
Sample code
1
Reconnect subscriptions
Reconnects all active subscriptions for this client. Use this after receiving PSS_DisconnectedUnexpectedly or PSS_ConnectionError from the OnSubscriptionStatusChanged listener, or after calling DisconnectSubscriptions().
1FPubnubOperationResult Result = PubnubClient->ReconnectSubscriptions(FString Timetoken);
2// Optional: omit to use default ""
Timetoken#- Optional timetoken to resume from. Default:
"".
Returns
| Type | Description |
|---|---|
FPubnubOperationResult | Status of the operation. |
Sample code
1
Disconnect subscriptions
Pauses all active subscriptions for this client.
1FPubnubOperationResult Result = PubnubClient->DisconnectSubscriptions();
Returns
| Type | Description |
|---|---|
FPubnubOperationResult | Status of the operation. |
Sample code
1
Client delegates
Each UPubnubClient has its own set of delegates for receiving events. These delegates only receive events for the specific client they belong to.
| Delegate | Type | Description |
|---|---|---|
OnClientDeinitialized | FOnPubnubClientDeinitialized | Called when the client is deinitialized. |
OnClientDeinitializeStart | FOnPubnubClientDeinitializeStart | Called when the client deinitialization starts. |
OnMessageReceived | FOnPubnubMessageReceived | Called when a message is received on any subscribed channel. |
OnMessageReceivedNative | FOnPubnubMessageReceivedNative | Native delegate equivalent that accepts lambdas. |
OnSubscriptionStatusChanged | FOnPubnubSubscriptionStatusChanged | Called when the subscription status changes (connected, disconnected, etc.). |
OnSubscriptionStatusChangedNative | FOnPubnubSubscriptionStatusChangedNative | Native delegate equivalent that accepts lambdas. |
Sample code
- C++
- Blueprint
Message listener
Binds a delegate to OnMessageReceived to handle incoming messages on any subscribed channel.
1
Message listener with a lambda
Binds a lambda to OnMessageReceivedNative.
1
Subscription status listener
Binds a delegate to OnSubscriptionStatusChanged to track connection state changes (connected, disconnected, etc.).
1
Event listeners
PubNub Unreal SDK provides several sources for real-time updates:
- Client-specific
UPubnubClientlisteners: Each client has its own delegates (OnMessageReceived,OnSubscriptionStatusChanged) that receive events only for that client's subscriptions. The subsystem has no listeners. - The
Subscriptionobject can receive updates only for the particular object for which it was created: channel, channel group, channel metadata, or user metadata. - The
SubscriptionSetobject can receive updates for all objects for which a list of subscription objects was created.
To work with these sources, the SDK provides local representations of server entities, so you can subscribe and add handlers per entity. For details, see Publish & Subscribe.
Async callback pattern
Most PubNub SDK methods offer an asynchronous variant with the Async suffix that accepts a response delegate. Bind a callback function to the delegate before you call the method. When the operation completes, the SDK calls it and passes a result struct. Inspect the struct for success or failure.
- C++
- Blueprint
1
1
Operation Result
All methods that connect to the PubNub network return a result struct. The result struct contains the status of the operation and the error message if the operation failed.
FPubnubOperationResult
| Field | Type | Description |
|---|---|---|
Status | int | Status of the operation. Returns 200 if the operation succeeded. |
Error | bool | Indicates whether the operation resulted in an error. |
ErrorMessage | FString | Contains useful information about the error if one occurred; otherwise empty. |