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 only CreatePubnubClient(), GetPubnubClient(), and DestroyPubnubClient(). 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:

IdentifierTypePurposeScope
Client IDintAn 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 IDFStringA 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.

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);
required
Config required#
Type: FPubnubConfig
Configuration struct for the PubNub SDK. Contains the following properties.
property of Config: PublishKey required#
Type: FString
Publish Key from Admin Portal. Default: "". Can't be empty.
property of Config: SubscribeKey required#
Type: FString
Subscribe Key from Admin Portal. Default: "". Can't be empty.
property of Config: SecretKey#
Type: FString
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 SecretKey isn't empty, the client uses it from creation. There's no separate step to turn it on. Default: "".
property of Config: UserID required#
Type: FString
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#
Type: FPubnubLoggerConfig
Logger setup used during client initialization. For details, refer to Logging.
property of Config: Origin#
Type: FString
PubNub origin host. The SDK reads it at creation. Leave it empty to use the default origin. Default: "".
property of Config: CryptoModule#
Type: UPubnubCryptoModule*
Payload crypto module. Call InitCryptoModule on 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#
Type: FString
Internal use only. Overrides the base SDK identifier. Default: "".
DebugName#
Type: FString
A name for the client used in debug logs. Useful for identifying clients when using multiple instances.

Returns​

TypeDescription
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​

icon

Usage in Blueprints and C++

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.

Actor.h​


1

Actor.cpp​


1

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);
required
ClientID required#
Type: int
The unique identifier of the client to retrieve. The first client you create with CreatePubnubClient() has ID 0.

Returns​

TypeDescription
UPubnubClient*A pointer to the PubNub client with the specified ID, or nullptr if no client with that ID exists.

Sample code​

1

Destroy a client​

You can destroy a client in two ways:

  • From UPubnubSubsystem: use DestroyPubnubClient() when you have a reference to the subsystem and want to destroy a specific client by pointer.
  • From UPubnubClient: use DestroyClient() when you want the client to destroy itself.

UPubnubSubsystem::DestroyPubnubClient()​

1bool DestroyPubnubClient(UPubnubClient* ClientToDestroy);
required
ClientToDestroy required#
Type: UPubnubClient*
A pointer to the client to destroy.
Returns​
TypeDescription
booltrue 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​

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​

TypeDescription
intThe 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);
required
UserID required#
Type: FString
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​

TypeDescription
FPubnubOperationResultStatus 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​

TypeDescription
FStringThe 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);
required
Origin required#
Type: FString
The origin hostname to set. If empty, the client resets to the default origin.

Returns​

TypeDescription
FPubnubOperationResultSuccess 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​

TypeDescription
FStringThe 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#
Type: FString
Optional timetoken to resume from. Default: "".

Returns​

TypeDescription
FPubnubOperationResultStatus of the operation.

Sample code​

1

Disconnect subscriptions​

Pauses all active subscriptions for this client.

1FPubnubOperationResult Result = PubnubClient->DisconnectSubscriptions();

Returns​

TypeDescription
FPubnubOperationResultStatus 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.

DelegateTypeDescription
OnClientDeinitializedFOnPubnubClientDeinitializedCalled when the client is deinitialized.
OnClientDeinitializeStartFOnPubnubClientDeinitializeStartCalled when the client deinitialization starts.
OnMessageReceivedFOnPubnubMessageReceivedCalled when a message is received on any subscribed channel.
OnMessageReceivedNativeFOnPubnubMessageReceivedNativeNative delegate equivalent that accepts lambdas.
OnSubscriptionStatusChangedFOnPubnubSubscriptionStatusChangedCalled when the subscription status changes (connected, disconnected, etc.).
OnSubscriptionStatusChangedNativeFOnPubnubSubscriptionStatusChangedNativeNative delegate equivalent that accepts lambdas.

Sample code​

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 UPubnubClient listeners: Each client has its own delegates (OnMessageReceived, OnSubscriptionStatusChanged) that receive events only for that client's subscriptions. The subsystem has no listeners.
  • The Subscription object can receive updates only for the particular object for which it was created: channel, channel group, channel metadata, or user metadata.
  • The SubscriptionSet object 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.

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​

FieldTypeDescription
StatusintStatus of the operation. Returns 200 if the operation succeeded.
ErrorboolIndicates whether the operation resulted in an error.
ErrorMessageFStringContains useful information about the error if one occurred; otherwise empty.

Was this page useful?

Last updated on