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 manages the lifecycle of PubNub clients. 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 within the same game, allowing different contexts such as different users or keysets. If Initialize Automatically is enabled in Project Settings, a default client (ID 0) is created on startup. You can create additional clients with CreatePubnubClient().

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 automatically assigned to each UPubnubClient instance (0, 1, 2, etc.). Used 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

Project settings

You can configure default PubNub keys in Unreal Editor. These settings are used to create the default PubnubClient when Initialize Automatically is enabled. If you use CreatePubnubClient(), provide keys directly in the FPubnubConfig struct.

1. In the Unreal Editor window, click the Settings dropdown and select Project Settings.

2. In the Project Settings window, scroll down to the Plugins section and click Pubnub SDK. The Plugins - Pubnub SDK view opens.

3. In the Plugins - Pubnub SDK view, provide the desired values for the available configuration options.

* required

Property	Description
Publish Key Type: string	Publish Key from Admin Portal (only required if publishing).
Subscribe Key * Type: string	Subscribe Key from Admin Portal.
Secret Key Type: string	Secret Key from Admin Portal, only required for access control operations.
Initialize Automatically Type: Boolean	Whether to automatically create a default client on startup. If you use CreatePubnubClient() to create clients manually, disable this option.
Set Secret Key Automatically Type: Boolean	Whether to set the secret key automatically during client initialization. If the Secret Key is set and you enable this option, the client will have root permissions for Access Manager.

Required User ID

When using Initialize Automatically, the default client is created without a User ID. You must call SetUserID() on the UPubnubClient before calling any other PubNub method.

C++

Use CreatePubnubClient() to create a new UPubnubClient with custom configuration. This is the recommended approach for initializing PubNub in C++.

1UPubnubClient* CreatePubnubClient(
2  FPubnubConfig Config, 
3  FString DebugName = ""
4);

* required

Property	Description
Config * Type: FPubnubConfig	Configuration struct for the PubNub SDK. Contains the following properties.
→ PublishKey Type: FString	Publish Key from Admin Portal (only required if publishing). Default: "demo".
→ SubscribeKey * Type: FString	Subscribe Key from Admin Portal. Default: "demo".
→ SecretKey Type: FString	Secret Key from Admin Portal, only required for access control operations. When set, it gives user root permissions for Access Manager. To use it, set SetSecretKeyAutomatically to true or call SetSecretKey.
→ UserID * 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.
→ SetSecretKeyAutomatically Type: bool	If true, the SecretKey will be set during the initialization phase. Grants root permissions for Access Manager. Default: false.
DebugName Type: FString	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. Each client is assigned a unique Client ID starting from 0.

Sample code

Reference code

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

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

• In Blueprints, the SDK is managed by a subsystem. Start by calling the Pubnub Subsystem node, then use Create Pubnub Client to create a UPubnubClient instance.

• 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++, start by getting the UPubnubSubsystem (a Game Instance Subsystem), then create a UPubnubClient with your configuration.

  #include "Kismet/GameplayStatics.h"
  #include "PubnubSubsystem.h"
  #include "PubnubClient.h"
  
  
  UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
  UPubnubSubsystem* PubnubSubsystem = GameInstance->GetSubsystem<UPubnubSubsystem>();
  
  
  FPubnubConfig Config;
  Config.PublishKey = "pub-c-...";
  Config.SubscribeKey = "sub-c-...";
  Config.UserId = "my-user-id";
  
  
  UPubnubClient* PubnubClient = PubnubSubsystem->CreatePubnubClient(Config);

  PubnubClient allows you to call PubNub SDK functions, for example:

  PubnubClient->PublishMessageAsync("my-channel", "Hello!", OnPublishMessageResponseDelegate);

  The SDK supports multiple UPubnubClient instances within the same game for different contexts such as different users or keysets. For more information, refer to Configuration.

Usage in Blueprints and C++

Asynchronous and synchronous method execution

Most PubNub Unreal SDK methods that perform network operations are available in both 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(); the deprecated InitPubnub() / DeinitPubnub() are being removed.

Required User ID

Always set the User ID to uniquely identify the user or device that connects to PubNub. This User ID should be persisted, and should remain unchanged for the lifetime of the user or the device. If you don't set the User ID, you won't be able to connect to PubNub.

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.

C++

Actor.h

1

Actor.cpp

1

Project settings

Blueprint

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

CryptoModule provides encrypt/decrypt functionality for messages. From the 1.0.0 release on, you can configure how the actual encryption/decryption algorithms work. By default, encryption is disabled.

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.

If you want to use the encryption functionality, you need to configure the CryptoModule first. When it's configured, all messages published are automatically encrypted, and all received messages are decrypted.

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

Parameter	Description
ClientID * Type: int	The unique identifier of the client to retrieve. The default client created by InitPubnub() or InitPubnubWithConfig() has ID 0.

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++

1// Get the default client (ID 0)
2UPubnubClient* DefaultClient = PubnubSubsystem->GetPubnubClient(0);
3

4// Get a custom client by ID
5UPubnubClient* Player2Client = PubnubSubsystem->GetPubnubClient(1);

Blueprint

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

Parameter	Description
ClientToDestroy * Type: UPubnubClient*	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++

1// Option 1: Destroy from the subsystem
2UPubnubClient* ClientToRemove = PubnubSubsystem->GetPubnubClient(1);
3bool bSuccess = PubnubSubsystem->DestroyPubnubClient(ClientToRemove);
4

5// Option 2: Destroy from the client itself
6PubnubClient->DestroyClient();

Blueprint

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 default client has ID 0. Additional clients receive incrementing IDs (1, 2, 3, etc.).

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.

1void SetUserID(FString UserID);

* required

Parameter	Description
UserID * 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.

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.

Set secret key

Sets the secret key for this client, granting root permissions for Access Manager. Uses the SecretKey value from provided config during creation of PubNubClient (or from plugin settings if the default client is used).

1void SetSecretKey();

Set origin

Sets the origin for the PubNub client. The origin is the hostname of the PubNub server to connect to. You can use this method to point the client to a custom PubNub origin.

1int SetOrigin(FString Origin);

* required

Parameter	Description
Origin * Type: FString	The origin string to set. If empty, null is passed to the underlying SDK, resetting the origin to the default.

Returns

Type	Description
int32	0 if the origin was set successfully. 1 if the origin was set and will be applied with the next connection. -1 if there was an error setting the origin.

Get origin

Returns the currently set origin for the PubNub client.

1FString GetOrigin() const;

Returns

Type	Description
FString	The origin string that was previously set, or an empty string if none was set.

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 ""

* required

Parameter	Description
Timetoken Type: FString	Optional timetoken to resume from. Default: "".

Returns

Type	Description
FPubnubOperationResult	Status of the operation.

Disconnect subscriptions

Pauses all active subscriptions for this client.

1FPubnubOperationResult Result = PubnubClient->DisconnectSubscriptions();

Returns

Type	Description
FPubnubOperationResult	Status of the operation.

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

1// Bind to client-specific message listener
2PubnubClient->OnMessageReceived.AddDynamic(this, &AMyActor::OnPubnubMessageReceived);
3

4// Or use a lambda
5PubnubClient->OnMessageReceivedNative.AddLambda([](const FPubnubMessageData& MessageData)
6{
7    UE_LOG(LogTemp, Log, TEXT("Message received: %s"), *MessageData.Message);
8});
9

10// Bind to client-specific subscription status listener
11PubnubClient->OnSubscriptionStatusChanged.AddDynamic(this, &AMyActor::OnSubscriptionStatusChanged);

Blueprint

Message listener

Binds a delegate to OnMessageReceived to handle incoming messages on any subscribed channel.

Subscription status listener

Binds a delegate to OnSubscriptionStatusChanged to track connection state changes (connected, disconnected, etc.).

Event listeners

PubNub Unreal SDK provides several sources for real-time updates:

• Global UPubnubSubsystem listeners: The subsystem's delegates (OnMessageReceived, OnSubscriptionStatusChanged) forward events from the default client only. These are convenient for simple, single-client applications.
• Client-specific UPubnubClient listeners: Each client has its own delegates that receive events only for that client's subscriptions. Use these when working with multiple clients.
• 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.

Client-specific vs. global listeners

When using multiple clients, bind to each client's delegates directly (for example, PubnubClient->OnMessageReceived) rather than the subsystem's global delegates. The subsystem's global delegates only forward events from the default client (ID 0).

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 (suffixed with Async) that accepts a response delegate. Bind a callback function to the delegate before calling the method — the SDK invokes it when the operation completes, passing a result struct you can inspect for success or failure.

C++

1

1

Blueprint

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.