Unreal SDK 3.0.0 Migration Guide

This guide summarizes the differences between versions 2.x and 3.0.0 and shows how to migrate to Unreal SDK 3.0.0.

Unreal SDK 3.0.0 is built on the PubNub C SDK. It replaces the previous underlying library on Windows, Linux, macOS, iOS, and Android. The release also removes the deprecated UPubnubSubsystem API, moves payload encryption into FPubnubConfig, and changes several public result types. The plugin supports Unreal Engine 5.0 through 5.8.

Breaking changes

Unreal SDK 3.0.0 contains breaking changes. Code that compiles against 2.x does not compile against 3.0.0 until you apply the changes in this guide.

What has changed

See the major differences between versions:

Feature/Method	Unreal SDK 2.x	Unreal SDK 3.0.0
Client creation	PublishKey and SubscribeKey default to demo, empty UserID accepted	PublishKey, SubscribeKey, and UserID required, CreatePubnubClient returns nullptr if any is empty
Automatic client	UPubnubSubsystem creates a default client on startup	n/a
Subsystem API	Deprecated listeners, delegates, and operation methods on UPubnubSubsystem	CreatePubnubClient, GetPubnubClient, and DestroyPubnubClient only
Secret key	SetSecretKeyAutomatically and SetSecretKey()	SecretKey in FPubnubConfig, applied at creation. Any non-empty value gives the client admin rights.
User ID	void SetUserID(FString)	FPubnubOperationResult SetUserID(FString)
Origin	int SetOrigin(FString)	Origin in FPubnubConfig and FPubnubOperationResult SetOrigin(FString)
Crypto module	SetCryptoModule() and GetCryptoModule() on the client	FPubnubConfig::CryptoModule set before CreatePubnubClient
Crypto provider interface	IPubnubCryptoProviderInterface and UPubnubCryptoBridge	n/a
Custom cryptors	Any IPubnubCryptorInterface implementation	UPubnubAesCryptor and UPubnubLegacyCryptor only
Publish method	EPubnubPublishMethod with six values	EPubnubPublishMethod with PPM_SendViaGET and PPM_SendViaPOST
Publish replication	FPubnubPublishSettings::Replicate	n/a
Publish compression	PPM_SendViaPOSTwithGZIP and PPM_UsePATCHwithGZIP	FPubnubPublishSettings::Compress (EPubnubPublishCompress), applies only with POST
List users in a channel	FPubnubListUsersFromChannelResult::Data (FPubnubListUsersFromChannelWrapper)	TotalOccupancy, TotalChannels, and Channels map of FPubnubUsersFromChannel
Get state	FPubnubGetStateResult::StateResponse (FString)	FPubnubGetStateResult::States (TMap<FString, FString>)
Presence async callbacks	FOnPubnubListUsersFromChannelResponse and FOnPubnubGetStateResponse pass separate parameters	Both pass one result struct
Set state settings	FPubnubSetStateSettings has UserID and HeartBeat	Both fields removed
Heartbeat	Heartbeat() and HeartbeatAsync()	n/a
Subscribe result	Result reflects the connection outcome	Result reflects that the subscription is registered, connection outcome arrives on OnSubscriptionStatusChanged
Subscription cursor region	FPubnubSubscriptionCursor::Region used	Region ignored, FPubnubMessageData::region always 0
Logging	UPubnubLogManager bound to the previous library logger	Same FPubnubLoggerConfig and IPubnubLoggerInterface, internal bridge changed
Token utilities	UPubnubTokenUtilities without grant-token helpers	Existing functions unchanged, new helper functions added
Unreal Engine versions	5.0 to 5.7	5.0 to 5.8

Breaking changes

Client creation requires keys and a user ID

In 2.x, FPubnubConfig::PublishKey and FPubnubConfig::SubscribeKey defaulted to demo, and the client accepted an empty UserID. In 3.0.0, both keys default to an empty string, and UPubnubSubsystem::CreatePubnubClient validates the config. If PublishKey, SubscribeKey, or UserID is empty, the SDK logs an error. CreatePubnubClient then returns nullptr.

FPubnubConfig also has new fields:

Field	Type	Description
Origin	FString	PubNub origin host. Leave empty to use the default origin.
CryptoModule	TObjectPtr<UPubnubCryptoModule>	Payload crypto module. See Crypto module.
PNSdkOverride	FString	Internal use only. Overrides the base SDK identifier.

The SetSecretKeyAutomatically field is removed. See Secret key, user ID, and origin changes.

Always check the returned pointer before you use the client:

1

UPubnubSubsystem manages clients only

Unreal SDK 3.0.0 removes the deprecated UPubnubSubsystem API that 2.x kept for backward compatibility. The UPubnubSettings class and its InitializeAutomatically property no longer exist, so the SDK does not create a default client at startup. The first client you create with CreatePubnubClient gets client ID 0. Until you create it, GetPubnubClient(0) returns nullptr.

The subsystem now exposes only these functions:

Function	Description
CreatePubnubClient(FPubnubConfig Config, FString DebugName = "")	Creates a client. Returns nullptr if the config is invalid.
GetPubnubClient(int ClientID)	Returns the client with that ID, or nullptr.
DestroyPubnubClient(UPubnubClient* ClientToDestroy)	Destroys the client and returns true if it existed.

The following members are removed from UPubnubSubsystem. Call the equivalent member on UPubnubClient instead:

• InitPubnub(), InitPubnubWithConfig(), and DeinitPubnub()
• The OnPubnubSubsystemDeinitialized, OnMessageReceived, OnMessageReceivedNative, OnPubnubError, OnPubnubErrorNative, OnSubscriptionStatusChanged, and OnSubscriptionStatusChangedNative delegates
• All operation methods, such as PublishMessage, Signal, SubscribeToChannel, SetState, GetState, GrantToken, RevokeToken, and the App Context, history, and message action methods
• The 2.x delegate types without the Pubnub prefix, such as FOnPublishMessageResponse. Use the FOnPubnub...Response types listed in the 2.0.0 migration guide.

Create a client from the subsystem and keep the returned pointer. You can also look it up by ID later:

1

Secret key, user ID, and origin changes

A secret key in FPubnubConfig now gives the client admin rights

In 2.x, SecretKey in FPubnubConfig had no effect on its own. The client used it only after you set SetSecretKeyAutomatically to true or called SetSecretKey().

In 3.0.0, the client uses any non-empty SecretKey as soon as you call CreatePubnubClient(). It signs every request with the key and gets full access to the keyset, whatever the Access Manager permissions.

If your 2.x code set SecretKey for every client but called SetSecretKey() only on your server, every one of those clients gets admin rights after the upgrade. Before you upgrade, check every place you build an FPubnubConfig. Leave SecretKey empty for every client that isn't a trusted server.

The SDK now applies SecretKey and Origin only when it creates the client:

• SecretKey is read from FPubnubConfig. The SetSecretKeyAutomatically field and the UPubnubClient::SetSecretKey() method are removed. You can't change the secret key after the client exists. Use a secret key only in server or backend clients.
• Origin is read from FPubnubConfig. You can still change it later with SetOrigin.
• SetUserID now returns FPubnubOperationResult instead of void. An empty user ID returns an error result.
• SetOrigin now returns FPubnubOperationResult instead of int. The old return codes 0, 1, and -1 no longer exist. A successful call has Status 200 and Error set to false. An empty origin resets the client to the default origin.
• GetOrigin returns the origin currently in use, including the default origin when you did not set one.

Update code that compares the old int result of SetOrigin to check FPubnubOperationResult::Error instead.

Crypto module is set in FPubnubConfig

In 2.x, you called UPubnubClient::SetCryptoModule after you created the client. In 3.0.0, you build a UPubnubCryptoModule, assign it to FPubnubConfig::CryptoModule, and then call CreatePubnubClient. The client uses the module for publish, subscribe, history, and files. Keep the module alive for the life of the client.

These APIs are removed:

• UPubnubClient::SetCryptoModule() and UPubnubClient::GetCryptoModule()
• IPubnubCryptoProviderInterface, with its ProviderEncrypt and ProviderDecrypt functions
• UPubnubCryptoBridge

UPubnubCryptoModule no longer implements a provider interface, and InitCryptoModule now returns bool:

• Each cryptor must have its cipher key set before you call InitCryptoModule.
• InitCryptoModule returns false if a live client still holds the module.
• The module accepts at most four additional cryptors.
• The module accepts only UPubnubAesCryptor and UPubnubLegacyCryptor. It rejects custom IPubnubCryptorInterface implementations, even though the interface itself is still source-compatible.
• IPubnubCryptorInterface keeps GetIdentifier, Encrypt, and Decrypt. The SDK calls them through the built-in cryptors only.

UPubnubAesCryptor and UPubnubLegacyCryptor also change. Call SetCipherKey before you use the cryptor. The SDK seals the cryptor when a crypto module takes it, so you can't change the key afterwards. For UPubnubLegacyCryptor, set UseRandomIV before you call InitCryptoModule.

The first snippet creates a module with the AES cryptor and assigns it to the config. The second adds the legacy cryptor, which decrypts data from other SDKs:

1

1

For a complete example that publishes and receives encrypted messages, see the full crypto sample:

1

Publish method and compression changes

EPubnubPublishMethod now has two values:

Value	Description
PPM_SendViaGET	The message is part of the URL path. There is no body, so compression does not apply. This is the default.
PPM_SendViaPOST	The message is part of the request body. Required for compression.

The values PPM_UsePATCH, PPM_SendViaPOSTwithGZIP, PPM_UsePATCHwithGZIP, and PPM_UseDELETE are removed. The FPubnubPublishSettings::Replicate field is removed, so you can no longer publish a message that only Functions receive.

Gzip compression moves into a new FPubnubPublishSettings::Compress field of the new EPubnubPublishCompress enum:

Value	Description
PPC_No	Sends the request body uncompressed. This is the default.
PPC_Yes	Gzips the request body and sends Content-Encoding: gzip. The SDK ignores it unless PublishMethod is PPM_SendViaPOST.

PPC_Yes does not switch a GET publish to POST. To replace PPM_SendViaPOSTwithGZIP, set PublishMethod to PPM_SendViaPOST and Compress to PPC_Yes. To replace PPM_UsePATCHwithGZIP, use the same combination, because PATCH is no longer available.

The 3.0.0 samples do not include a snippet for Compress. The following snippet shows how to pass FPubnubPublishSettings to a publish call. Set the PublishMethod and Compress fields on the same struct:

1

Presence results are grouped by channel

Presence reads now return data keyed by channel name, and Heartbeat is removed.

ListUsersFromChannel

In 2.x, FPubnubListUsersFromChannelResult::Data held an FPubnubListUsersFromChannelWrapper with Occupancy and a UsersState map of user ID to state. In 3.0.0, the wrapper is gone and the result struct has three fields:

Field	Type	Description
TotalOccupancy	int	Occupancy across all returned channels.
TotalChannels	int	Number of channels the server reports.
Channels	TMap<FString, FPubnubUsersFromChannel>	Users present on each returned channel, keyed by channel name.

Each FPubnubUsersFromChannel has Channel, Occupancy, and Users, which is a TArray<FPubnubUserFromChannel>. Each FPubnubUserFromChannel has UserID and State. State is raw state JSON, empty if you did not request state or the user has none. Occupancy can be larger than Users.Num() when Limit and Offset paginate the list.

The async delegates FOnPubnubListUsersFromChannelResponse and FOnPubnubListUsersFromChannelResponseNative now take one FPubnubListUsersFromChannelResult parameter instead of FPubnubOperationResult and FPubnubListUsersFromChannelWrapper. Read the operation status from Result.Result.

1

GetState

In 2.x, FPubnubGetStateResult::StateResponse was one JSON FString. In 3.0.0, States replaces it. States is a TMap<FString, FString> of channel name to raw state JSON. The string is empty when the user has no state on that channel. The async delegates FOnPubnubGetStateResponse and FOnPubnubGetStateResponseNative now take one FPubnubGetStateResult parameter instead of FPubnubOperationResult and FString.

1

SetState and Heartbeat

• FPubnubSetStateSettings::UserID and FPubnubSetStateSettings::HeartBeat are removed. SetState always sets state for the client's current user ID, and the settings keep ChannelGroup.
• UPubnubClient::Heartbeat() and UPubnubClient::HeartbeatAsync() are removed. The SDK has no replacement.

Subscribe returns when the subscription is registered

SubscribeToChannel and SubscribeToGroup, including the Async variants, now report that the SDK registered the subscription locally. They no longer wait for the connection to complete. The returned FPubnubOperationResult (or the callback result) does not tell you whether the connection succeeded. Listen to OnSubscriptionStatusChanged on the client for connection success and failure. If your code treated a successful subscribe result as a confirmed connection, move that logic into the status listener.

1

The subscription cursor also changes:

• FPubnubSubscriptionCursor::Region is ignored. Resuming uses Timetoken only, and the SDK logs a warning if you set a non-zero Region.
• FPubnubMessageData::region is always 0.

Other changes

These changes affect fewer projects:

• Logging. FPubnubLoggerConfig, IPubnubLoggerInterface, and DefaultLoggerMinCCoreLevel keep their names and behavior, now applied to logs from the PubNub library itself. If you call UPubnubLogManager directly, GetCCoreLoggerInterface() is removed. The class now has GetCCoreLoggerProvider() and ReleaseCCoreLoggerBridge(), and HandleCCoreLog takes a different entry type. These are internal functions, so most projects are not affected.
• Token utilities. The existing UPubnubTokenUtilities functions keep their signatures. 3.0.0 adds the public static functions BuildReworkedParsedToken, BuildGrantTokenResourceStorage, and ApplyGrantTokenResourceStorage. The SDK uses them in its own grant and parse code. You don't need to call them.
• Utility functions. The public UPubnubUtilities header no longer declares PubnubConfigFromPluginSettings, PubnubGetLastServerHttpResponse, AddQuotesToString, RemoveOuterQuotesFromString, PubnubCharMemBlockToString, ArrayOfStringsToCommaSeparatedString, SafeCopyFStringToCharBuffer, and UEMessageFromPubnubMessage. Remove any calls to them.
• Internal client API. SetRuntimeSdkVersionSuffix is removed from UPubnubClient.
• Subscription sets. UPubnubSubscriptionSet has a new private initializer that accepts channel metadata and user metadata IDs. Your code does not call it.
• Unreal Engine versions. The plugin supports Unreal Engine 5.0 through 5.8.

Migration steps

To migrate from Unreal SDK 2.x to 3.0.0:

1. Update your PubNub plugin to version 3.0.0.

2. Create the client explicitly with valid config values:

   Action	Description
   Set PublishKey, SubscribeKey, and UserID on FPubnubConfig	The SDK no longer defaults the keys to demo, and CreatePubnubClient returns nullptr if any value is empty.
   Call UPubnubSubsystem::CreatePubnubClient() at startup and check the returned pointer	The SDK does not create a client for you, and GetPubnubClient(0) returns nullptr until you create one.
   Remove uses of UPubnubSettings, InitPubnub(), InitPubnubWithConfig(), and DeinitPubnub()	These APIs no longer exist.

3. Move off the removed UPubnubSubsystem API:

   Action	Description
   Call operations and bind delegates on UPubnubClient	UPubnubSubsystem keeps only CreatePubnubClient, GetPubnubClient, and DestroyPubnubClient.
   Replace delegate types such as FOnPublishMessageResponse with FOnPubnubPublishMessageResponse	Delegates without the Pubnub prefix are removed.

4. Update secret key, user ID, and origin handling:

   Action	Description
   Find every FPubnubConfig with SecretKey set	In 3.0.0, a non-empty SecretKey always gives the client admin rights. Keep it only on clients where 2.x called SetSecretKey() or set SetSecretKeyAutomatically.
   Remove SetSecretKeyAutomatically and SetSecretKey() calls	Do this only after the check above.
   Set Origin in FPubnubConfig	It applies only at creation. Use SetOrigin() to change it later.
   Check FPubnubOperationResult from SetUserID() and SetOrigin()	SetUserID() returned void and SetOrigin() returned int in 2.x.

5. Move crypto into the config:

   Action	Description
   Create the cryptors, set their cipher keys, and call InitCryptoModule()	Check that it returns true.
   Assign the module to FPubnubConfig::CryptoModule before CreatePubnubClient()	Remove SetCryptoModule() and GetCryptoModule() calls.
   Replace custom cryptors with UPubnubAesCryptor or UPubnubLegacyCryptor	The crypto module rejects other implementations.
   Remove code that uses IPubnubCryptoProviderInterface or UPubnubCryptoBridge	Both are removed.

6. Update publish settings:

   Action	Description
   Remove FPubnubPublishSettings::Replicate	The field no longer exists.
   Replace removed EPubnubPublishMethod values	Use PPM_SendViaGET or PPM_SendViaPOST.
   Set PublishMethod to PPM_SendViaPOST and Compress to PPC_Yes to gzip the body	Compress has no effect on GET publishes.

7. Update presence code:

   Action	Description
   Read ListUsersFromChannel results from TotalOccupancy, TotalChannels, and Channels	The Data field and FPubnubListUsersFromChannelWrapper are removed.
   Read GetState results from States by channel name	The StateResponse field is removed.
   Update ListUsersFromChannelAsync and GetStateAsync callbacks	Both now receive one result struct.
   Remove Heartbeat(), HeartbeatAsync(), and the UserID and HeartBeat fields of FPubnubSetStateSettings	They no longer exist.

8. Update subscribe handling:

   Action	Description
   Treat a successful SubscribeToChannel() or SubscribeToGroup() result as "subscription registered"	The result no longer confirms a connection.
   Bind OnSubscriptionStatusChanged to learn about connection success and failure	Connection outcomes arrive there.
   Stop relying on FPubnubSubscriptionCursor::Region and FPubnubMessageData::region	The SDK ignores the cursor region and always sets the message region to 0.

9. Test your application. Pay special attention to client creation, encrypted publish and subscribe, presence reads, and subscription status handling.

Additional resources

For API details, see the Unreal SDK documentation. For questions or issues, contact PubNub support.