Presence API for Unreal SDK

Presence lets you track who is online or offline and store custom state information. Presence shows:

• When a user has joined or left a channel
• How many users are subscribed to a particular channel (occupancy)
• Which channels a user or device is subscribed to
• Presence state associated with these users

Learn more about our Presence feature in the Presence overview.

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:

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

Usage in Blueprints and C++

Asynchronous and synchronous method execution

Most PubNub Unreal SDK methods are available in both asynchronous and synchronous variants.

• Asynchronous methods (Async suffix) return void and take an optional delegate parameter that fires when the operation completes.

  1PubnubClient->ListUsersFromChannelAsync("my-channel", OnListUsersFromChannelResponseDelegate);

  You can also use native callbacks that accept lambdas instead of dynamic delegates. Native callback types have the Native suffix (for example, FOnPubnubListUsersFromChannelResponseNative).

• Synchronous methods (no suffix) block the main game thread until the operation completes and return a result struct directly.

  1FPubnubListUsersFromChannelResult Result = PubnubClient->ListUsersFromChannel("my-channel");

List users from channel

Requires Presence

This method requires that the Presence add-on is enabled for your key in the Admin Portal.

For information on how to receive presence events and what those events are, refer to Presence Events.

This method returns information about the current state of a channel, including a list of unique user IDs (universally unique identifiers, UUIDs) currently subscribed to the channel and the total occupancy count of the channel.

Cache

This method has a 3-second response cache time.

Breaking change

The ListUsersFromChannel method now returns a maximum of 1,000 occupants per channel. Previously, it returned all occupants regardless of count. If you have channels with more than 1,000 occupants, you must use pagination (Limit and Offset parameters in FPubnubListUsersFromChannelSettings) to retrieve the complete list.

You can call ListUsersFromChannel() on a Channel entity (which already knows its channel) or directly on the PubNub client by passing the channel name explicitly.

Channel entity

This method is available to use with the Channel entity. For more information, refer to Channel.

Available in entities

Channel

Method(s)

To list users from a channel, you must first create a Channel entity where you provide the name of the channel you want to get presence information from.

1UPubnubChannelEntity* ChannelEntity = PubnubSubsystem->CreateChannelEntity("my-channel");
2

3ChannelEntity->ListUsersFromChannel(
4    FOnListUsersFromChannelResponse ListUsersFromChannelResponse,
5    FPubnubListUsersFromChannelSettings ListUsersFromChannelSettings = FPubnubListUsersFromChannelSettings()
6);

* required

Parameter	Description
ListUsersFromChannelResponse * Type: FOnListUsersFromChannelResponse	The delegate for the operation's result. You can also use a native callback of the type FOnListUsersFromChannelResponseNative to handle the result using a lambda.
ListUsersFromChannelSettings Type: FPubnubListUsersFromChannelSettings	A struct defining the method's configuration.

FPubnubListUsersFromChannelSettings

* required

Parameter	Description
ChannelGroups Type: FString	Comma-delimited list of channel group names. Not used if empty. Wildcards are not supported.
DisableUserID Type: bool	Whether to disable including the user IDs of the connected clients in the response. Default is true.
State Type: bool	Whether to including the state of the connected clients in the response. Default is false.
Limit Type: int	Maximum number of occupants to return per channel. Valid range: 1-1000. Default is 1000.
Offset Type: int	Zero-based starting index for pagination. Returns occupants starting from this position. Use with Limit to paginate through large occupant lists. Default is 0.

Sample code

Reference code

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

C++

Actor.h

1

Actor.cpp

1

Returns

This function is void, but the delegate returns the FOnListUsersFromChannelResponse struct.

FOnListUsersFromChannelResponse

Field	Type	Description
Result	FPubnubOperationResult	The result of the operation.
Data	FPubnubListUsersFromChannelWrapper	A struct containing the result of the operation.

FPubnubListUsersFromChannelWrapper

Field	Type	Description
Occupancy	int	The number of users in a given channel.
UsersState	TMap<FString, FString>	A map of user IDs and their respective state.

FOnListUsersFromChannelResponseNative

Field	Type	Description
Result	const FPubnubOperationResult&	The result of the operation.
Data	const FPubnubListUsersFromChannelWrapper&	A struct containing the result of the operation.

Other examples

Reference code

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

Return occupancy only

You can return only the occupancy information for a single channel by specifying the channel and setting DisableUserID to false:

Actor.h

1

Actor.cpp

1

Use lambda

You can use a lambda function to handle the response:

Actor.h

1

Actor.cpp

1

PubNub client

Method(s)

1PubnubClient->ListUsersFromChannelAsync(
2    FString Channel,
3    FOnPubnubListUsersFromChannelResponse ListUsersFromChannelResponse,
4    FPubnubListUsersFromChannelSettings ListUsersFromChannelSettings = FPubnubListUsersFromChannelSettings()
5);

* required

Parameter	Description
Channel * Type: FString	The channel to get the presence details of.
ListUsersFromChannelResponse * Type: FOnPubnubListUsersFromChannelResponse	The delegate for the operation's result. You can also use a native callback of the type FOnPubnubListUsersFromChannelResponseNative to handle the result using a lambda.
ListUsersFromChannelSettings Type: FPubnubListUsersFromChannelSettings	A struct defining the method's configuration.

Sample code

Reference code

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

C++

Actor.h

1

Actor.cpp

1

Blueprint

Returns

This method is void. The delegate returns the following struct:

FOnPubnubListUsersFromChannelResponse

Field	Type	Description
Result	FPubnubOperationResult	The result of the operation.
Data	FPubnubListUsersFromChannelWrapper	A struct containing occupancy and user state information for the channel.

FOnPubnubListUsersFromChannelResponseNative

Field	Type	Description
Result	const FPubnubOperationResult&	The result of the operation.
Data	const FPubnubListUsersFromChannelWrapper&	A struct containing occupancy and user state information for the channel.

Other examples

Reference code

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

Return occupancy only

You can return only the occupancy information for a single channel by specifying the channel and setting DisableUserID to false:

C++

Actor.h

1

Actor.cpp

1

Blueprint

Use lambda

You can use a lambda function to handle the response:

Actor.h

1

Actor.cpp

1

List user subscribed channels

Requires Presence

This method requires that the Presence add-on is enabled for your key in the Admin Portal.

For information on how to receive presence events and what those events are, refer to Presence Events.

This method returns the list of channels a user ID is subscribed to.

Timeout events

If the app restarts (or the page refreshes) within the heartbeat window, no timeout event is generated.

Method(s)

1PubnubClient->ListUserSubscribedChannelsAsync(
2    FString UserID,
3    FOnPubnubListUsersSubscribedChannelsResponse ListUserSubscribedChannelsResponse
4);

* required

Parameter	Description
UserID * Type: FString	The User ID to get the subscribed channels of.
ListUserSubscribedChannelsResponse * Type: FOnPubnubListUsersSubscribedChannelsResponse	The delegate for the operation's result. You can also use a native callback of the type FOnPubnubListUsersSubscribedChannelsResponseNative to handle the result using a lambda.

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 simply need to define the user ID and the callback function to be used to send the data to as in the example below.

C++

Actor.h

1

Actor.cpp

1

Blueprint

Returns

This method is void. The delegate returns the following struct:

FOnPubnubListUsersSubscribedChannelsResponse

Field	Type	Description
Result	FPubnubOperationResult	The result of the operation.
Channels	const TArray<FString>&	An array of channel names the user is subscribed to.

FOnPubnubListUsersSubscribedChannelsResponseNative

Field	Type	Description
Result	const FPubnubOperationResult&	The result of the operation.
Channels	const TArray<FString>&	An array of channel names the user is subscribed to.

Other examples

Reference code

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

Use lambda

You can use a lambda function to handle the response:

Actor.h

1

Actor.cpp

1

User state

Requires Presence

This method requires that the Presence add-on is enabled for your key in the Admin Portal.

For information on how to receive presence events and what those events are, refer to Presence Events.

The Presence API is used to set/get key/value pairs specific to a subscriber User ID.

Method(s)

Set state

1PubnubClient->SetStateAsync(
2    FString Channel,
3    FString StateJson,
4    FOnPubnubSetStateResponse OnSetStateResponse,
5    FPubnubSetStateSettings SetStateSettings = FPubnubSetStateSettings()
6);

* required

Parameter	Description
Channel * Type: FString	The channel to set the presence state on.
StateJson * Type: FString	JSON object with the state to set.
OnSetStateResponse Type: FOnPubnubSetStateResponse	The delegate for the operation's result. You can also use a native callback of the type FOnPubnubSetStateResponseNative to handle the result using a lambda.
SetStateSettings Type: FPubnubSetStateSettings	Struct defining the method's configuration.

FPubnubSetStateSettings

* required

Parameter	Description
ChannelGroups Type: FString	Comma-delimited list of channel group names. Not used if empty.
UserID Type: FString	The User ID of the user for which to set state for. If NULL, the current PubNub context User ID is used.
HeartBeat Type: bool	Whether to set the state and make a heartbeat call at the same time via the /heartbeat endpoint.

Get state

1PubnubClient->GetStateAsync(
2    FString Channel,
3    FString ChannelGroup,
4    FString UserID,
5    FOnPubnubGetStateResponse OnGetStateResponse
6);

* required

Parameter	Description
Channel * Type: FString	The channel to get the presence state of.
ChannelGroup * Type: FString	The channel group to get the presence state of.
UserID * Type: FString	The User ID to get the presence state of.
OnGetStateResponse * Type: FOnPubnubGetStateResponse	The delegate for the operation's result. You can also use a native callback of the type FOnPubnubGetStateResponseNative to handle the result using a lambda.

Sample code

Reference code

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

C++

Actor.h

1

Actor.cpp

1

Blueprint

Get State

Reference code

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

C++

Actor.h

1

Actor.cpp

1

Blueprint

Returns

The SetStateAsync method is void. The delegate returns the following struct:

FOnPubnubSetStateResponse

Field	Type	Description
Result	FPubnubOperationResult	The result of the operation.

FOnPubnubSetStateResponseNative

Field	Type	Description
Result	const FPubnubOperationResult&	The result of the operation.

The GetStateAsync method is void. The delegate returns the following struct:

FOnPubnubGetStateResponse

Field	Type	Description
Result	FPubnubOperationResult	The result of the operation.
StateResponse	FString	The state of the user as a JSON string.

FOnPubnubGetStateResponseNative

Field	Type	Description
Result	const FPubnubOperationResult&	The result of the operation.
StateResponse	FString	The state of the user as a JSON string.

Other examples

Reference code

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

Set state with result struct

You can use the result struct to handle the response:

C++

Actor.h

1

Actor.cpp

1

Blueprint

Set state for a channel group

You can set the state for a channel group by specifying the channel group name:

C++

Actor.h

1

Actor.cpp

1

Blueprint

Set state with lambda

You can use a lambda function to handle the response:

Actor.h

1

Actor.cpp

1

Get state from channel group with lambda

You can use a lambda function to handle the response:

Actor.h

1

Actor.cpp

1

Complete example

Reference code

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

C++

ASample_PresenceFull.h

1

ASample_PresenceFull.cpp

1

Blueprint

Deprecated methods

List users from channel (deprecated)

Deprecated

This method is deprecated and will be removed in a future version. Use PubnubClient->ListUsersFromChannel() or PubnubClient->ListUsersFromChannelAsync() instead.

1PubnubSubsystem->ListUsersFromChannel(
2    FString Channel,
3    FOnListUsersFromChannelResponse ListUsersFromChannelResponse,
4    FPubnubListUsersFromChannelSettings ListUsersFromChannelSettings = FPubnubListUsersFromChannelSettings()
5);

* required

Parameter	Description
Channel * Type: FString	The channel to get the presence details of.
ListUsersFromChannelResponse * Type: FOnListUsersFromChannelResponse	The delegate for the operation's result.
ListUsersFromChannelSettings Type: FPubnubListUsersFromChannelSettings	A struct defining the method's configuration.

List user subscribed channels (deprecated)

Deprecated

This method is deprecated and will be removed in a future version. Use PubnubClient->ListUserSubscribedChannels() or PubnubClient->ListUserSubscribedChannelsAsync() instead.

1PubnubSubsystem->ListUserSubscribedChannels(
2    FString UserID,
3    FOnListUsersSubscribedChannelsResponse ListUserSubscribedChannelsResponse
4);

* required

Parameter	Description
UserID * Type: FString	The User ID to get the subscribed channels of.
ListUserSubscribedChannelsResponse * Type: FOnListUsersSubscribedChannelsResponse	The delegate for the operation's result.

Set state (deprecated)

Deprecated

This method is deprecated and will be removed in a future version. Use PubnubClient->SetState() or PubnubClient->SetStateAsync() instead.

1PubnubSubsystem->SetState(
2    FString Channel,
3    FString StateJson,
4    FOnSetStateResponse OnSetStateResponse,
5    FPubnubSetStateSettings SetStateSettings = FPubnubSetStateSettings()
6);

* required

Parameter	Description
Channel * Type: FString	The channel to set the presence state on.
StateJson * Type: FString	JSON object with the state to set.
OnSetStateResponse Type: FOnSetStateResponse	The delegate for the operation's result.
SetStateSettings Type: FPubnubSetStateSettings	Struct defining the method's configuration.

Get state (deprecated)

Deprecated

This method is deprecated and will be removed in a future version. Use PubnubClient->GetState() or PubnubClient->GetStateAsync() instead.

1PubnubSubsystem->GetState(
2    FString Channel,
3    FString ChannelGroup,
4    FString UserID,
5    FOnGetStateResponse OnGetStateResponse
6);

* required

Parameter	Description
Channel * Type: FString	The channel to get the presence state of.
ChannelGroup * Type: FString	The channel group to get the presence state of.
UserID * Type: FString	The User ID to get the presence state of.
OnGetStateResponse * Type: FOnGetStateResponse	The delegate for the operation's result.