---
source_url: https://www.pubnub.com/docs/sdks/unreal/api-reference/configuration
title: Configuration API for Unreal SDK
updated_at: 2026-05-25T11:29:34.458Z
sdk_name: PubNub Unreal SDK
sdk_version: 2.0.5
---

> Documentation Index
> For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt
> For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt


# Configuration API for Unreal SDK

PubNub Unreal SDK, use the latest version: 2.0.5

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.

:::note 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. |

:::note 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.

![Open project settings animation](https://www.pubnub.com/assets/images/config-d0215092c3071a9ebc0fea10b17bbd60.gif)

| Property | Description |
| --- | --- |
| Publish KeyType: string | Publish Key from [Admin Portal](https://admin.pubnub.com/) (only required if publishing). |
| Subscribe Key *Type: string | Subscribe Key from [Admin Portal](https://admin.pubnub.com/). |
| Secret KeyType: string | Secret Key from [Admin Portal](https://admin.pubnub.com/), only required for access control operations. |
| Initialize AutomaticallyType: Boolean | Whether to automatically create a default client on startup. If you use `CreatePubnubClient()` to create clients manually, disable this option. |
| Set Secret Key AutomaticallyType: 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. |

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

```cpp
UPubnubClient* CreatePubnubClient(
  FPubnubConfig Config, 
  FString DebugName = ""
);
```

| Property | Description |
| --- | --- |
| `Config` *Type: `FPubnubConfig` | Configuration struct for the PubNub SDK. Contains the following properties. |
| `> PublishKey`Type: `FString` | Publish Key from [Admin Portal](https://admin.pubnub.com/) (only required if publishing). Default: `"demo"`. |
| `> SubscribeKey` *Type: `FString` | Subscribe Key from [Admin Portal](https://admin.pubnub.com/). Default: `"demo"`. |
| `> SecretKey`Type: `FString` | Secret Key from [Admin Portal](https://admin.pubnub.com/), only required for access control operations. When set, it gives user root permissions for [Access Manager](https://www.pubnub.com/docs/sdks/unreal/api-reference/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](https://www.pubnub.com/docs/sdks/unreal/api-reference/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

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

##### Usage in Blueprints and C++

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: In your IDE, navigate to Source/_{YourProject}_/_{YourProject}_.Build.cs and add a dependency to PubnubLibrary. PrivateDependencyModuleNames.AddRange(new string[] { "PubnubLibrary" });, 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.

:::note 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.
:::

:::note 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

```cpp
// blueprint._9byc9q1
UFUNCTION(BlueprintCallable, Category = "Pubnub|Samples|Configuration")
void CreatePubnubClient();
	
// blueprint.poqf2o09
UFUNCTION(BlueprintCallable, Category = "Pubnub|Samples|Configuration")
UPubnubClient* GetPubnubClient();
	
// blueprint.256-9zfg
UFUNCTION(BlueprintCallable, Category = "Pubnub|Samples|Configuration")
void DestroyPubnubClient();
```

#### Actor.cpp

```cpp
#include "Kismet/GameplayStatics.h"
#include "Engine/GameInstance.h"
#include "PubnubSubsystem.h"

// ACTION REQUIRED: Replace ASample_Configuration with name of your Actor class
void ASample_Configuration::CreatePubnubClient()
{
	//Get PubnubSubsystem from GameInstance
	UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
	UPubnubSubsystem* PubnubSubsystem = GameInstance->GetSubsystem<UPubnubSubsystem>();

	// Create Pubnub Client using Pubnub Subsystem
	FPubnubConfig PubnubConfig;
	PubnubConfig.PublishKey = TEXT("demo");   //replace with your Publish Key from Admin Portal
	PubnubConfig.SubscribeKey = TEXT("demo"); //replace with your Subscribe Key from Admin Portal
	PubnubConfig.UserID = TEXT("Player_001");
	UPubnubClient* PubnubClient = PubnubSubsystem->CreatePubnubClient(PubnubConfig);
	
	UE_LOG(LogTemp, Log, TEXT("Pubnub Client created with config"));
}

#include "Kismet/GameplayStatics.h"
#include "Engine/GameInstance.h"
#include "PubnubSubsystem.h"

// ACTION REQUIRED: Replace ASample_Configuration with name of your Actor class
UPubnubClient* ASample_Configuration::GetPubnubClient()
{
	UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
	UPubnubSubsystem* PubnubSubsystem = GameInstance->GetSubsystem<UPubnubSubsystem>();
	
	//Get default PubnubClient - created automatically if PluginSettings are set to do so
	UPubnubClient* PubnubClient = PubnubSubsystem->GetPubnubClient(0);
	
	PubnubClient->SetUserID(TEXT("player_001"));
	return PubnubClient;
}

#include "Kismet/GameplayStatics.h"
#include "Engine/GameInstance.h"
#include "PubnubSubsystem.h"

// ACTION REQUIRED: Replace ASample_Configuration with name of your Actor class
void ASample_Configuration::DestroyPubnubClient()
{
	// snippet.hide
	UPubnubClient* PubnubClient = GetPubnubClient();
	// snippet.show
	
	UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
	UPubnubSubsystem* PubnubSubsystem = GameInstance->GetSubsystem<UPubnubSubsystem>();
	
	PubnubSubsystem->DestroyPubnubClient(PubnubClient);
}
```

###### Project settings

![Project Settings configuration screenshot](https://www.pubnub.com/assets/images/config-project-settings-fd9c1cf1bce1c267005426c7e83f1175.png)

###### 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](https://www.pubnub.com/docs/general/setup/data-security#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](https://www.pubnub.com/docs/sdks/unreal/api-reference/encryption).

### Create a client

Use [CreatePubnubClient()](#configuration-and-initialization) to create a new PubNub client with a custom configuration.

### Get a client

Use `GetPubnubClient()` to retrieve an existing client by its unique ID.

```cpp
UPubnubClient* GetPubnubClient(int ClientID);
```

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

```cpp
// Get the default client (ID 0)
UPubnubClient* DefaultClient = PubnubSubsystem->GetPubnubClient(0);

// Get a custom client by ID
UPubnubClient* 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()

```cpp
bool DestroyPubnubClient(UPubnubClient* ClientToDestroy);
```

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

```cpp
void 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++

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

// Option 2: Destroy from the client itself
PubnubClient->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.

```cpp
int 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.

```cpp
void SetUserID(FString UserID);
```

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

```cpp
FString 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).

```cpp
void 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.

```cpp
int SetOrigin(FString Origin);
```

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

```cpp
FString 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()`.

```cpp
FPubnubOperationResult Result = PubnubClient->ReconnectSubscriptions(FString Timetoken);
// Optional: omit to use default ""
```

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

#### Returns

| Type | Description |
| --- | --- |
| [FPubnubOperationResult](#operation-result) | Status of the operation. |

### Disconnect subscriptions

Pauses all active subscriptions for this client.

```cpp
FPubnubOperationResult Result = PubnubClient->DisconnectSubscriptions();
```

#### Returns

| Type | Description |
| --- | --- |
| [FPubnubOperationResult](#operation-result) | 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++

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

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

// Bind to client-specific subscription status listener
PubnubClient->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](https://www.pubnub.com/docs/sdks/unreal/api-reference/publish-and-subscribe#create-a-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](https://www.pubnub.com/docs/sdks/unreal/api-reference/publish-and-subscribe#create-a-subscription-set) object can receive updates for all objects for which a list of subscription objects was created.

:::tip 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](https://www.pubnub.com/docs/sdks/unreal/api-reference/publish-and-subscribe#event-listeners).

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

```cpp
#include "PubnubClient.h"

// blueprint.w8o07e-l
UFUNCTION(BlueprintCallable, Category = "Pubnub|Samples|Configuration")
void ListUsersFromChannelSample();

UFUNCTION()
void OnListUsersFromChannelResponse(FPubnubOperationResult Result, FPubnubListUsersFromChannelWrapper Data);
```

```cpp
// ACTION REQUIRED: Replace ASample_Configuration with name of your Actor class
void ASample_Configuration::ListUsersFromChannelSample()
{
	// snippet.hide
	UPubnubClient* PubnubClient = GetPubnubClient();
	// snippet.show
	
	//Assumes PubnubClient is created and UserID is set

	// Bind response delegate
	// ACTION REQUIRED: Replace ASample_Configuration with name of your Actor class
	FOnPubnubListUsersFromChannelResponse OnListUsersFromChannelResponse;
	OnListUsersFromChannelResponse.BindDynamic(this, &ASample_Configuration::OnListUsersFromChannelResponse);

	//List users from a channel
	FString Channel = TEXT("guild-channel");
	PubnubClient->ListUsersFromChannelAsync(Channel, OnListUsersFromChannelResponse);
}

// ACTION REQUIRED: Replace ASample_Configuration with name of your Actor class
void ASample_Configuration::OnListUsersFromChannelResponse(FPubnubOperationResult Result, FPubnubListUsersFromChannelWrapper Data)
{
	if(Result.Error)
	{
		UE_LOG(LogTemp, Error, TEXT("Failed to list users from channel. Status: %d, Reason: %s"), Result.Status, *Result.ErrorMessage);
	}
	else
	{
		UE_LOG(LogTemp, Log, TEXT("Users successfully listed from channel. Occupancy: %d"), Data.Occupancy);
	}
}
```

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

## Terms in this document

* **PubNub** - PubNub is a real-time messaging platform that provides APIs and SDKs for building scalable applications. It handles the complex infrastructure of real-time communication, including: Message delivery and persistence, Presence detection, Access control, Push notifications, File sharing, Serverless processing with Functions and Events & Actions, Analytics and monitoring with BizOps Workspace, AI-powered insights with Illuminate.
* **User** - An individual or entity that interacts with a system, application, or service. In PubNub, a user typically refers to someone who sends or receives messages through the platform, identified by a unique user ID or username.
* **User ID** - UTF-8 encoded, unique string of up to 92 characters used to identify a single client (end user, device, or server) that connects to PubNub.