Unreal API & SDK Docs 0.3.0

In this guide, we'll create a simple "Hello, World" application that demonstrates the core concepts of PubNub

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:

in Unreal Engine:

  • Setting up a connection to PubNub
  • Sending a "Hello, World" message
  • Receiving messages in real-time

Overview​

This guide will help you get up and running with PubNub in your Unreal Engine application using C++ programming. You'll learn how to initialize the SDK, set up event listeners, and send/receive a simple "Hello, World" message - all with minimal code.

Prerequisites​

Before we dive in, make sure you have:

  • A basic understanding of Unreal Engine and C++
  • Unreal Engine installed (version 5.2 or higher recommended)
  • A PubNub account (we'll help you set this up!)
icon

Installation on Unreal Engine <5.2.0

Setup​

Get your PubNub keys​

First things first – you'll need your PubNub keys to get started. Here's how to get them:

  • Sign in or create an account on the Admin Portal and create an app.
  • When you create a new app, the first set of keys is generated automatically.
  • Find your publish

    Publish Key

    A unique identifier that allows your application to send messages to PubNub channels. It's part of your app's credentials and should be kept secure.
     and subscribe

    Subscribe Key

    A unique identifier that allows your application to receive messages from PubNub channels. It's part of your app's credentials and should be kept secure.
     keys in the app's dashboard.

We recommend that you create separate keysets for production and test environments.

Install the SDK​

SDK version

Always use the latest SDK version to have access to the newest features and avoid security vulnerabilities, bugs, and performance issues.

PubNub Unreal Engine SDK is available on FAB as a free downloadable plugin that you can add to your project.

  1. Install the PubNub SDK plugin from FAB. For information on installing plugins, refer to the Unreal Engine documentation.

  2. Enable the PubNubSDK in your project. For information on enabling plugins, refer to the Unreal Engine documentation.

  3. In your project's Build.cs file, add the dependency (this is required only for using PubNub SDK with C++):

    PrivateDependencyModuleNames.AddRange(new string[] { "PubnubLibrary" });

  4. In files that you want to use PubNub SDK functionality include the necessary header:

    #include "PubnubSubsystem.h"

Configure PubNub in Unreal Editor​

After installing the PubNub SDK plugin, you should configure it in the Unreal Editor's Project Settings:

  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.

  3. In the Plugins - Pubnub SDK view, provide the following configuration options:

    OptionValueNotes
    Publish Key
    		demo
    		Replace with your key from the Admin Portal for production
    Subscribe Key
    		demo
    		Replace with your key from the Admin Portal for production
    Secret Key
    		(leave empty)
    		Only required for access control operations
    Initialize Automatically
    		(checked)
    		Recommended for easier setup
    Set Secret Key Automatically
    		(unchecked)
    		Only check if using access control

After configuring these settings, the PubNub SDK will be ready to use in your project.

SDK initialization

If you choose not to enable Initialize Automatically, you'll need to manually initialize the PubNub SDK in your code before using any PubNub functionality.

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.

Configure the Unreal Engine project​

For our simple "Hello, World" example, we'll focus on creating just two essential classes:

  1. GameInstance to initialize PubNub and handle messages.
  2. PlayerController to trigger sending our "Hello, World" message with a key press.

Create a new project​

Launch the Unreal Editor and create a new C++ project (or open your existing project).

Create essential C++ classes​

Create the following C++ classes through the editor:

  1. Click the Tools dropdown menu and select New C++ Class... or simply Select Tools -> New C++ Class....
  2. Create these classes:
  • PubNubGameInstance - Inherit from UGameInstance
  • PubNubPlayerController - Inherit from APlayerController

Configure project settings​

Configure the project settings:

  1. Navigate to Edit > Project Settings.
  2. Under Maps & Modes:
  • Set Default GameInstance to your PubNubGameInstance class.
  • Set Default Player Controller to your PubNubPlayerController class.

Steps​

Initialize PubNub​

For more information, refer to the Configuration section of the SDK documentation.

Set up event listeners​

Listeners help your app react to events and messages. You can implement custom app logic to respond to each type of message or event.

We've already set up our message and error listeners in the GameInstance's Init method. The listeners will:

  • Log any received messages to the Output Log.
  • Log any errors that occur.

For more information, refer to the Event Listeners section of the SDK documentation.

Create a subscription​

To receive messages sent to a particular channel, you need to subscribe to it.

We've already subscribed to the "hello_world_channel" in our GameInstance's Init method.

For more information, refer to the Subscribe section of the SDK documentation.

Publish messages​

When you publish a message to a channel, PubNub delivers that message to everyone who is subscribed to that channel.

A message can be any type of JSON-serializable data (such as objects, arrays, integers, strings) that is smaller than 32 KiB.

For more information, refer to the Publish section of the SDK documentation.

Run the app​

To test your Hello World PubNub integration:

  1. In the Unreal Editor, click the Play button in the toolbar.
  2. Look at the Output Log (Window > Developer Tools > Output Log).
  3. You should see initialization messages confirming that PubNub is connected and subscribed.
  4. Press the P key to publish a "Hello, World!" message.
  5. In the Output Log, you should see both the publish confirmation and the received message.

Cross-platform testing​

To verify that your PubNub implementation works across platforms:

  1. Open the PubNub Debug Console in your web browser.
  2. Enter the demo publish and subscribe keys.
  3. Subscribe to "hello_world_channel".
  4. Press the P key in your Unreal application to send a message.
  5. The message should appear in both your Unreal app's logs and the PubNub Debug Console.
  6. You can also publish a message from the Debug Console and see it appear in your Unreal app's logs.

Complete example​

Here's the complete implementation for our Hello World example:

  • PubNubGameInstance.h
// PubNubGameInstance.h
#pragma once

#include "CoreMinimal.h"
#include "Engine/GameInstance.h"
#include "PubnubSubsystem.h"
#include "PubNubGameInstance.generated.h"

UCLASS()
//Replace YOUR_PROJECT_API with [Project_Name]_API
class YOUR_PROJECT_API UPubNubGameInstance : public UGameInstance
{
	GENERATED_BODY()
    
public:
show all 32 lines
  • PubNubGameInstance.cpp
// PubNubGameInstance.cpp
#include "PubNubGameInstance.h"

void UPubNubGameInstance::Init()
{
	Super::Init();
    
	// Set the channel we'll use for our Hello World example
	ChannelName = "hello_world_channel";
    
	// Get the PubNub subsystem
	PubnubSubsystem = GetSubsystem<UPubnubSubsystem>();
    
	// Set User ID - required for connection
	PubnubSubsystem->SetUserID("unreal_user_123");
show all 51 lines
  • PubNubPlayerController.h
// PubNubPlayerController.h
#pragma once

#include "CoreMinimal.h"
#include "GameFramework/PlayerController.h"
#include "PubNubGameInstance.h"
#include "PubNubPlayerController.generated.h"

UCLASS()
//Replace YOUR_PROJECT_API with [Project_Name]_API
class YOUR_PROJECT_API APubNubPlayerController : public APlayerController
{
	GENERATED_BODY()
    
protected:
show all 23 lines
  • PubNubPlayerController.cpp
// PubNubPlayerController.cpp
#include "PubNubPlayerController.h"
#include "Kismet/GameplayStatics.h"

void APubNubPlayerController::SetupInputComponent()
{
	Super::SetupInputComponent();
    
	// Bind the P key to publish a Hello World message
	InputComponent->BindKey(EKeys::P, IE_Pressed, this, &APubNubPlayerController::HandleKeyP);
    
	// Get our game instance
	PubNubInstance = Cast<UPubNubGameInstance>(UGameplayStatics::GetGameInstance(GetWorld()));
}

show all 22 lines

Next steps​

Great job! 🎉 You've successfully created your first PubNub application in Unreal Engine. Here are some exciting things you can explore next:

Last updated on
Related Resources
On this page