Presence API for Unreal SDK

Presence enables you to track the online and offline status of users and devices in real time and store custom state information. Presence provides authoritative information on:

• When a user has joined or left a channel
• Who, and how many, users are subscribed to a particular channel
• Which channel(s) an individual user is subscribed to
• Associated state information for these users

Learn more about our Presence feature here.

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

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.

You can obtain information about the current state of a channel including a list of unique user-ids currently subscribed to the channel and the total occupancy count.

Cache

This method has a 3 second response cache time.

Method(s)

PubnubSubsystem->ListUsersFromChannel(
    FString Channel, 
    FOnListUsersFromChannelResponse ListUsersFromChannelResponse, 
    FPubnubListUsersFromChannelSettings ListUsersFromChannelSettings = FPubnubListUsersFromChannelSettings()
);

* required

Parameter	Description
Channel * Type: FString	The channel to get the presence details of.
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.

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

Actor.cpp

Blueprint

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

Actor.cpp

Use lambda

You can use a lambda function to handle the response:

Actor.h

Actor.cpp

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.

You can obtain information about the current list of channels to which a User ID is subscribed to.

Timeout events

If the app is killed/crashes and restarted (or the page containing the PubNub instance is refreshed on the browser) within the heartbeat window no timeout event is generated.

Method(s)

PubnubSubsystem->ListUserSubscribedChannels(
    FString UserID, 
    FOnListUsersSubscribedChannelsResponse ListUserSubscribedChannelsResponse
);

* required

Parameter	Description
UserID * Type: FString	The User ID to get the subscribed channels of.
ListUserSubscribedChannelsResponse * Type: FOnListUsersSubscribedChannelsResponse	The callback function used to handle the result.

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

Actor.cpp

Blueprint

Returns

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

FOnListUsersSubscribedChannelsResponse

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

FOnListUsersSubscribedChannelsResponseNative

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

Actor.cpp

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

PubnubSubsystem->SetState(
    FString Channel, 
    FString StateJson, 
    FOnSetStateResponse OnSetStateResponse,
    FPubnubSetStateSettings SetStateSettings = FPubnubSetStateSettings()
);

* 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. You can also use a native callback of the type FOnSetStateResponseNative 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

PubnubSubsystem->GetState(
    FString Channel, 
    FString ChannelGroup, 
    FString UserID, 
    FOnGetStateResponse OnGetStateResponse
);

* 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 callback function used to handle the result.

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

Actor.cpp

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

Actor.cpp

Blueprint

Returns

The SetState method returns the FOnSetStateResponse struct.

FOnSetStateResponse

Field	Type	Description
Result	FPubnubOperationResult	The result of the operation.

FOnSetStateResponseNative

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

The GetState method returns the FOnGetStateResponse struct.

FOnGetStateResponse

Field	Type	Description
Result	FPubnubOperationResult	The result of the operation.
StateResponse	FString	The state of the user.

FOnGetStateResponseNative

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

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:

Actor.h

Actor.cpp

Set state for a channel group

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

Actor.h

Actor.cpp

Set state with lambda

You can use a lambda function to handle the response:

Actor.h

Actor.cpp

Get state from channel group

You can get the state from a channel group by specifying the channel group name:

Actor.h

Actor.cpp

Get state from channel group with lambda

You can use a lambda function to handle the response:

Actor.h

Actor.cpp

Complete example

Reference code

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

ASample_PresenceFull.h

ASample_PresenceFull.cpp