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, and event handling with concise, working examples.

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

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

• The PubNub client can receive updates from all subscriptions: all channels, channel groups, channel metadata, and user metadata.
• 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.

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

Various listeners receive PubNub events. The following list shows examples of the event payload emitted for different event types.

Catch all events

The OnAnyEventReceived listener catches all event types Refer to Event listeners for more information.

App context

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
}