Presence API for PubNub 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.

Usage in Blueprints and C++

List Users from Channel

Requires Presence add-on

This method requires that the Presence add-on is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.

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)

Blueprint

Response variants

You can also call the ListUsersFromChannel_JSON() variant of this method to get an FOnPubnubResponse which contains pure JSON.

C++

Response variants

You can also call the ListUsersFromChannel_JSON() variant of this method to get an FOnPubnubResponse which contains pure JSON.

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

Parameter	Type	Required	Description
ChannelName	FString	Yes	The channel to get the presence details of.
ListUsersFromChannelResponse	FOnListUsersFromChannelResponse	Yes	The callback function used to handle the result.
ListUsersFromChannelSettings	FPubnubListUsersFromChannelSettings	Optional	A struct defining the method's configuration.

FPubnubListUsersFromChannelSettings

Parameter	Type	Required	Description
ChannelGroups	FString	Optional	Comma-delimited list of channel group names. Not used if NULL.
DisableUUID	bool	Optional	Whether to disable including the user IDs of the connected clients in the response. Default is true.
State	bool	Optional	Whether to including the state of the connected clients in the response. Default is false.

Basic Usage

Get a list of User IDs subscribed to channel

#include "Kismet/GameplayStatics.h"
#include "PubnubSubsystem.h"

UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
UPubnubSubsystem* PubnubSubsystem = GameInstance->GetSubsystem<UPubnubSubsystem>();

FString ChannelName = "randomChannel";
FString Message = "{ \"text\" : \"This is my message\" }";

// Create a pubnub response delegate
// you MUST implement your own callback function to handle the response
FOnListUsersFromChannelResponse ListUsersFromChannelResponse;
ListUsersFromChannelResponse.BindDynamic(this, &AMyActor::ListUsersFromChannelResponse);

// Create the list users settings

show all 22 lines

Returns

This method returns the FOnListUsersFromChannelResponse struct.

FOnListUsersFromChannelResponse

Field	Type	Description
Status	int	HTTP code of the result of the operation.
Message	FString	More information about the status 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.
UuidsState	TMap<FString, FString>	A map of user IDs and their respective state.

JSON response

{
  "status": 200, 
  "message": "OK", 
  "occupancy": 2, 
  "uuids": [
    {"uuid": "uuid-1"}, 
    {"uuid": "uuid-2"}
  ], 
  "service": "Presence"
}

Other Examples

Return Occupancy Only

Requires Presence add-on

This method requires that the Presence add-on is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.

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

#include "Kismet/GameplayStatics.h"
#include "PubnubSubsystem.h"

UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
UPubnubSubsystem* PubnubSubsystem = GameInstance->GetSubsystem<UPubnubSubsystem>();

FString ChannelName = "randomChannel";

// Create a pubnub response delegate
// you MUST implement your own callback function to handle the response
FPubnubListUsersFromChannelSettings ListUsersFromChannelResponse;
ListUsersFromChannelResponse.BindDynamic(this, &AMyActor::ListUsersFromChannelResponse);

// Create the list users settings
FPubnubListUsersFromChannelSettings ListUsersFromChannelSettings;

show all 21 lines

List User Subscribed Channels

Requires Presence add-on

This method requires that the Presence add-on is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.

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)

Blueprint

Response variants

You can also call the ListUserSubscribedChannels_JSON() variant of this method to get an FOnPubnubResponse which contains pure JSON.

C++

Response variants

You can also call the ListUserSubscribedChannels_JSON() variant of this method to get an FOnPubnubResponse which contains pure JSON.

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

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

Basic Usage

You simply need to define the uuid and the callback function to be used to send the data to as in the example below.

Get a list of channels a UUID is subscribed to

#include "Kismet/GameplayStatics.h"
#include "PubnubSubsystem.h"

UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
UPubnubSubsystem* PubnubSubsystem = GameInstance->GetSubsystem<UPubnubSubsystem>();

FString UserId = "myUserId";

// Create a pubnub response delegate
// you MUST implement your own callback function to handle the response
FOnListUsersSubscribedChannelsResponse ListUsersFromChannelResponse;
ListUserSubscribedChannelsResponse.BindDynamic(this, &AMyActor::OnListUsersFromChannelResponse);

// List users from the channel using the specified settings
PubnubSubsystem->ListUserSubscribedChannels(UserId, ListUserSubscribedChannelsResponse);

Returns

This method returns the FOnListUsersSubscribedChannelsResponse struct.

FOnListUsersSubscribedChannelsResponse

Field	Type	Description
Status	int	HTTP code of the result of the operation.
Message	FString	More information about the status of the operation.
Channels	TArray<FString>&	An array of channel names the user is subscribed to.

JSON response

{
  "status": 200, 
  "message": "OK", 
  "payload": {
    "channels": ["my_channel"]
  }, 
  "service": "Presence"
}

User State

Requires Presence add-on

This method requires that the Presence add-on is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.

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

Method(s)

Set State

Blueprint

C++

PubnubSubsystem->SetState(
    FString ChannelName, 
    FString StateJson, 
    FPubnubSetStateSettings SetStateSettings = FPubnubSetStateSettings()
);

Parameter	Type	Required	Description
ChannelName	FString	Yes	The channel to set the presence state on.
StateJson	FString	Yes	JSON object with the state to set.
SetStateSettings	FPubnubSetStateSettings	Optional	Struct defining the method's configuration.

FPubnubSetStateSettings

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

Get State

Blueprint

C++

PubnubSubsystem->GetState(
    FString ChannelName, 
    FString ChannelGroup, 
    FString UserID, 
    FOnPubnubResponse OnGetStateResponse
);

Parameter	Type	Required	Description
ChannelName	FString	Yes	The channel to get the presence state of.
ChannelGroup	FString	Yes	The channel group to get the presence state of.
UserID	FString	Yes	The User ID to get the presence state of.
OnGetStateResponse	FOnPubnubResponse	Yes	The callback function used to handle the result.

Basic Usage

Set State

#include "Kismet/GameplayStatics.h"
#include "PubnubSubsystem.h"

UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
UPubnubSubsystem* PubnubSubsystem = GameInstance->GetSubsystem<UPubnubSubsystem>();

FString ChannelName = "exampleChannel";
FString StateJson = "{\"mood\": \"happy\"}"; 

// Create the set state settings
FPubnubSetStateSettings SetStateSettings;
SetStateSettings.ChannelGroups = "group1,group2"; // Example channel groups
SetStateSettings.UserID = "user123"; // Example user ID
SetStateSettings.HeartBeat = true; // Set state and make a heartbeat call

show all 17 lines

Get State

#include "Kismet/GameplayStatics.h"
#include "PubnubSubsystem.h"

UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
UPubnubSubsystem* PubnubSubsystem = GameInstance->GetSubsystem<UPubnubSubsystem>();

FString ChannelName = "exampleChannel";
FString ChannelGroup = "";
FString UserID = "user123";

// Create the response delegate
// you MUST implement your own callback function to handle the response
FOnPubnubResponse OnGetStateResponse;
OnGetStateResponse.BindDynamic(this, &AMyActor::OnGetStateResponse);

show all 17 lines

Returns

The SetState method doesn't have a return value. The GetState method returns the following:

{
  "status": 200, 
  "message": "OK", 
  "payload": {
    "happy": "true"
  }, 
  "service": "Presence"
}

Heartbeat

Requires Presence add-on

This method requires that the Presence add-on is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.

This method notifies channels and channel groups about a client's presence. You can send heartbeats to channels you are not subscribed to.

Method(s)

Blueprint

C++

PubnubSubsystem->Heartbeat(
    FString ChannelName, 
    FString ChannelGroup
);

Parameter	Type	Required	Description
ChannelName	FString	Yes	The channel to send the heartbeat to.
ChannelGroup	FString	Yes	The channel group to send the heartbeat to.

Basic Usage

#include "Kismet/GameplayStatics.h"
#include "PubnubSubsystem.h"

UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
UPubnubSubsystem* PubnubSubsystem = GameInstance->GetSubsystem<UPubnubSubsystem>();

FString ChannelName = "exampleChannel";
FString ChannelGroup = "exampleGroup";

// Send the heartbeat to the specified channel and channel group
PubnubSubsystem->Heartbeat(ChannelName, ChannelGroup);

Returns

This method doesn't have a return value