Configuration API for Unreal SDK

Unreal complete API reference for building real-time applications on PubNub, including basic usage and sample code.

Configuration and initialization

Project settings

You can configure the PubNub SDK in Unreal Editor as follows:

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 initialize the SDK without having to call the Init Pubnub method. Disable this if you want to use the InitPubnubWithConfig() method.
Set Secret Key Automatically Type: Boolean	(Only in Project Settings) Whether to initialize the SDK with the provided secret key without having to call the Set Secret Key method. If the Secret Key is set and you enable Set Secret Key Automatically, the user will have root permissions for Access Manager.

C++

Must disable automatic initialization

You can only use the InitPubnubWithConfig() method if Initialize Automatically is disabled in the project settings.

PubnubSubsystem->InitPubnubWithConfig(FPubnubConfig);

Property	Description
FPubnubConfig Type: FPubnubConfig Default: n/a	Configuration struct for the PubNub SDK. Contains the following properties.
→ PublishKey Type: FString Default: "demo"	Publish Key from Admin Portal (only required if publishing).
→ SubscribeKey Type: FString Default: "demo"	Subscribe Key from Admin Portal.
→ SecretKey Type: FString Default: ""	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 function.
→ UserID Type: FString Default: ""	Identifies the user or device that connects to PubNub. Required for all operations. If left empty, use SetUserID before the first operation. Must be a UTF-8 encoded string up to 92 alphanumeric characters.
→ SetSecretKeyAutomatically Type: bool Default: false	If true, the SecretKey will be set during the initialization phase. Grants root permissions for Access Manager.

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 whole SDK is managed by a subsystem, so start by calling the Pubnub Subsystem node.

• 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++, you can use the PubNub SDK as any other Game Instance Subsystem.

  #include "Kismet/GameplayStatics.h"
  #include "PubnubSubsystem.h"
  
  UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
  UPubnubSubsystem* PubnubSubsystem = GameInstance->GetSubsystem<UPubnubSubsystem>();

  PubnubSubsystem now allows you to call all PubNub SDK functions, for example:

  PubnubSubsystem->SubscribeToChannel("MyChannel");

Usage in Blueprints and C++

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.

C++

Actor.h

Actor.cpp

Project settings

Blueprint

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.

Event listeners

In PubNub Unreal SDK, the listeners notify you of message events and errors. All events emitted on a particular channel are received through OnMessageReceived but differ in their JSON payload. Refer to Event types for more information.

Add listeners

C++

Actor.h

Actor.cpp

Blueprint

Other examples

Reference code

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

Add message listener with lambda

Actor.h

Actor.cpp

Add error listener

Actor.h

Actor.cpp

Add error listener with lambda

Actor.h

Actor.cpp

Add subscription status listener

You need to add a subscription status listener to get notified when the subscription status changes. For more information on subscriptions, refer to SDK Connection Lifecycle.

C++

Actor.h

Actor.cpp

Blueprint

Other examples

Reference code

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

Add subscription status listener with lambda

Actor.h

Actor.cpp

Add callback function

Responses to functions are handled using response delegates and callback functions.

All functions with a response type need a callback function to handle the response. Let's look into an example implementation of a callback function for the ListUsersFromChannel function.

C++

Actor.h

Actor.cpp

Blueprint

Other examples

Reference code

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

Add callback function with lambda

Actor.h

Actor.cpp

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.

Event Types

All message events are routed through OnMessageReceived but have a different JSON structure. The following list shows examples of the event payload emitted for different event types.

Objects

Set user metadata

{
  "source": "objects",
  "version": "2.0",
  "event": "set",
  "type": "uuid",
  "data": {
    "eTag": "dad3f3d77ec74a6458b34e0ee5172544",
    "id": "User1",
    "name": "new name",
    "updated": "2024-08-12T06:37:16.441347Z"
  }
}

Set channel metadata

{
  "source": "objects",
  "version": "2.0",
  "event": "set",
  "type": "channel",
  "data": {
    "eTag": "cdfd462ffc3a985470fd309810a05f0b",
    "id": "my_channel2",
    "name": "new channel name",
    "updated": "2024-08-12T06:39:50.16522Z"
  }
}

Set member

{
  "source": "objects",
  "version": "2.0",
  "event": "set",
  "type": "membership",
  "data": {
    "channel": {
      "id": "my_ue_channel"
    },
    "eTag": "Afah2qS199e74QE",
    "updated": "2024-08-12T13:15:47.057904689Z",
    "uuid": {
      "id": "User11"
    }
  }

show all 16 lines

Set membership

{
  "source": "objects",
  "version": "2.0",
  "event": "set",
  "type": "membership",
  "data": {
    "channel": {
      "id": "channel_from_ue"
    },
    "eTag": "Afah2qS199e74QE",
    "updated": "2024-08-12T13:17:22.756243015Z",
    "uuid": {
      "id": "User12"
    }
  }

show all 16 lines

Presence

Presence join

{
    "Event": "join",
    "Uuid": "175c2c67-b2a9-470d-8f4b-1db94f90e39e",
    "Timestamp": 1345546797,
    "Occupancy": 2,
    "State": null,
    "Channel":" my_channel",
    "Subscription": "",
    "Timetoken": 15034141109823424,
    "UserMetadata": null,
    "Join": null,
    "Timeout": null,
    "Leave": null,
    "HereNowRefresh": false
}

Presence leave

{
    "Event": "leave",
    "Uuid": "175c2c67-b2a9-470d-8f4b-1db94f90e39e",
    "Timestamp": 1345546797,
    "Occupancy": 1,
    "State": null,
    "Channel": "my_channel",
    "Subscription": "",
    "Timetoken": 15034141109823424,
    "UserMetadata": null,
    "Join": null,
    "Timeout": null,
    "Leave": null,
    "HereNowRefresh": false
}

Presence timeout

{
    "Event": "timeout",
    "Uuid": "175c2c67-b2a9-470d-8f4b-1db94f90e39e",
    "Timestamp": 1345546797,
    "Occupancy": 0,
    "State": null,
    "Channel": "my_channel",
    "Subscription": "",
    "Timetoken": 15034141109823424,
    "UserMetadata": null,
    "Join": null,
    "Timeout": null,
    "Leave": null,
    "HereNowRefresh": false
}

State change event

{
    "Event": "state-change",
    "Uuid": "175c2c67-b2a9-470d-8f4b-1db94f90e39e",
    "Timestamp": 1345546797,
    "Occupancy": 1,
    "State": {
        "isTyping": true
    },
    "Channel": "my_channel",
    "Subscription": "",
    "Timetoken": 15034141109823424,
    "UserMetadata": null,
    "Join": null,
    "Timeout": null,
    "Leave": null,

show all 17 lines

Presence interval

{
    "Event": "interval",
    "Uuid": "175c2c67-b2a9-470d-8f4b-1db94f90e39e",
    "Timestamp": 1345546797,
    "Occupancy": 2,
    "State": null,
    "Channel": "my_channel",
    "Subscription": "",
    "Timetoken": 15034141109823424,
    "UserMetadata": null,
    "Join": null,
    "Timeout": null,
    "Leave": null,
    "HereNowRefresh": false
}

When a channel is in interval mode with presence_deltas pnconfig flag enabled, the interval message may also include the following fields which contain an array of changed User IDs since the last interval message.

• joined
• left
• timedout

For example, this interval message indicates there were 2 new User IDs that joined and 1 timed out User ID since the last interval:

{
    "Event": "interval",
    "Uuid": "175c2c67-b2a9-470d-8f4b-1db94f90e39e",
    "Timestamp": <unix timestamp>,
    "Occupancy": <# users in channel>,
    "State": null,
    "Channel": "my_channel",
    "Subscription": "",
    "Timetoken": 15034141109823424,
    "UserMetadata": null,
    "Join": ["uuid2", "uuid3"],
    "Timeout": ["uuid1"],
    "Leave": null,
    "HereNowRefresh": false
}

If the full interval message is greater than 30KB (since the max publish payload is ∼32KB), none of the extra fields will be present. Instead there will be a here_now_refresh boolean field set to true. This indicates to the user that they should do a hereNow request to get the complete list of users present in the channel.

{
    "Event": "interval",
    "Uuid": "175c2c67-b2a9-470d-8f4b-1db94f90e39e",
    "Timestamp": <unix timestamp>,
    "Occupancy": <# users in channel>,
    "State": null,
    "Channel": "my_channel",
    "Subscription": "",
    "Timetoken": 15034141109823424,
    "UserMetadata": null,
    "Join": null,
    "Timeout": null,
    "Leave": null,
    "HereNowRefresh": true
}