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.

icon

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)​

Response variants

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

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 Channel = "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​


FieldTypeDescription
StatusintHTTP code of the result of the operation.
MessageFStringMore information about the status of the operation.
DataFPubnubListUsersFromChannelWrapperA struct containing the result of the operation.

FPubnubListUsersFromChannelWrapper​


FieldTypeDescription
OccupancyintThe number of users in a given channel.
UuidsStateTMap<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 DisableUserID to false:

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

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

FString Channel = "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)​

Response variants

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

Basic Usage​

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.

Get a list of channels a User 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​


FieldTypeDescription
StatusintHTTP code of the result of the operation.
MessageFStringMore information about the status of the operation.
ChannelsTArray<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​

Get State​

Basic Usage​

Set State​

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

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

FString Channel = "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 Channel = "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)​

Basic Usage​

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

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

FString Channel = "exampleChannel";
FString ChannelGroup = "exampleGroup";

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

Returns​

This method doesn't have a return value

Last updated on
On this page