App Context API for Unreal SDK

App Context provides easy-to-use, serverless storage for user and channel data you need to build innovative, reliable, scalable applications. Use App Context to easily store metadata about your application users and channels, and their membership associations, without the need to stand up your own databases.

PubNub also triggers events when object data is changed: set, updated, or removed from the database. At the same time, making a request to set the same data that already exist, doesn't trigger any event. Clients can receive these events in real time and update their front-end application accordingly.

icon

Usage in Blueprints and C++

User​

Get Metadata for All Users​

Returns a paginated list of User Metadata objects, optionally including the custom data object for each.

Method(s)​

Response variants

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

Basic Usage​

Reference code

This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.

MyGameMode.h​

// NOTE: This example requires correct PubnubSDK configuration in plugins settings and adding "PubnubLibrary" to PublicDependencyModuleNames in your build.cs
// More info in the documentation: https://www.pubnub.com/docs/sdks/unreal/api-reference/configuration

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/GameModeBase.h"
#include "MyGameMode.generated.h"

/**
 * 
 */
UCLASS()
class MYPROJECT_API AMyGameMode : public AGameModeBase
{
show all 23 lines

MyGameMode.cpp​

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

void AMyGameMode::GetAllUserMetadataExample()
{
	// Get PubnubSubsystem from the game instance
	UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
	UPubnubSubsystem* PubnubSubsystem = GameInstance->GetSubsystem<UPubnubSubsystem>();

	// Ensure user ID is set
	PubnubSubsystem->SetUserID("my_user_id");

	// Define response delegate
	FOnGetAllUserMetadataResponse OnGetAllUserMetadataResponse;
show all 35 lines

Returns​

This method returns the FOnGetAllUserMetadataResponse struct.

FOnGetAllUserMetadataResponse​

FieldTypeDescription
Status
int
HTTP code of the result of the operation.
UsersData
TArray<FPubnubUserData>&
Aa array of FPubnubUserData structs which are the users with their associated User metadata.
PageNext
FString
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
PagePrev
FString
Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the pageNext parameter is supplied.
FPubnubUserData​

FieldTypeDescription
UserID
FString
Unique user identifier. If not supplied, then the current user's User is used.
UserName
FString
Display name for the user.
ExternalID
FString
User's identifier in an external system.
ProfileUrl
FString
The URL of the user's profile picture.
Email
FString
The user's email address.
Custom
FString
JSON providing custom data about the user. Values must be scalar only; arrays or objects are not supported.
Status
FString
User status. Max. 50 characters.
Type
FString
User type. Max. 50 characters.
Updated
FString
The date when the user's metadata was last updated.
ETag
FString
Information on the object's content fingerprint.
JSON Response​
{
    "Uuids": [
        {
            "Uuid": "uuid-1",
            "Name": "John Doe",
            "Email": "john.doe@pubnub.com",
            "ExternalId": "",
            "ProfileUrl": "",
            "Custom": "",
            "Updated": "2020-06-17T16:28:14.060718Z"
        },
        {
            "Uuid": "uuid-2",
            "Name": "Bob Cat",
            "Email": "bobc@example.com",
show all 29 lines

Get User Metadata​

Returns metadata for the specified User, optionally including the custom data object for each.

Method(s)​

Response variants

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

Basic Usage​

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

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

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

FString Include = ""; // No additional attributes
FString User = "uuid-1"; 

PubnubSubsystem->GetUserMetadata(Include, Limit, Start, End, Count, OnGetUserMetadataResponse);

Returns​

This method returns the FOnGetUserMetadataResponse struct.

FOnGetUserMetadataResponse​

FieldTypeDescription
Status
int
HTTP code of the result of the operation.
UserData
FPubnubUserData
Aa instance of FPubnubUserData struct which is the user with their associated User metadata.

JSON Response​

{
    "Uuid": "uuid-1",
    "Name": "John Doe",
    "Email": "john.doe@pubnub.com",
    "ExternalId": "",
    "ProfileUrl": "",
    "Custom": "",
    "Updated": "2020-06-17T16:28:14.060718Z"
}

Set User Metadata​

Unsupported partial updates of custom metadata

The value of the custom metadata parameter sent in this method always overwrites the value stored on PubNub servers. If you want to add new custom data to an existing one, you must:

  1. Get the existing metadata and store it locally.
  2. Append the new custom metadata to the existing one.
  3. Set the entire updated custom object.

Set metadata for a User in the database, optionally including the custom data object for each.

Method(s)​

API limits

To learn about the maximum length of parameters used to set user metadata, refer to REST API docs.

Basic Usage​

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

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

FString User = "user123"; // Example User Metadata ID
FString Include = ""; // No additional attributes
FString UserMetadataObj = "{\"name\":\"John Doe\",\"email\":\"johndoe@example.com\"}"; // Example JSON object

// Call the SetUserMetadata method
PubnubSubsystem->SetUserMetadata(User, Include, UserMetadataObj);

Returns​

{
    "Uuid": "uuid-1",
    "Name": "John Doe",
    "Email": "john.doe@pubnub.com",
    "ExternalId": "",
    "ProfileUrl": "",
    "Custom": "",
    "Updated": "2020-06-17T16:28:14.060718Z"
}

Remove User Metadata​

Removes the metadata from a specified User ID.

Method(s)​

Basic Usage​

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

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

FString User = "user123"; // Example User Metadata ID

// Call the RemoveUserMetadata method
PubnubSubsystem->RemoveUserMetadata(User);

Returns​

This method doesn't have any return value.

Channel​

Get Metadata for All Channels​

Returns a paginated list of Channel Metadata objects, optionally including the custom data object for each.

Method(s)​

Response variants

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

Basic Usage​

#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
FOnGetAllChannelMetadataResponse OnGetAllUserMetadataResponse;
OnGetAllUserMetadataResponse.BindDynamic(this, &AMyActor::OnGetAllUserMetadataResponse);

int Limit = 10; // Limit to 10 objects
EPubnubTribool Count = PT_False; // Don't include total count
show all 17 lines

Returns​

This method returns the FOnGetAllChannelMetadataResponse struct.

FOnGetAllChannelMetadataResponse​

FieldTypeDescription
Status
int
HTTP code of the result of the operation.
ChannelsData
TArray<FPubnubChannelData>&
Aa array of FPubnubChannelData structs which are the users with their associated Channel metadata.
PageNext
FString
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
PagePrev
FString
Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the pageNext parameter is supplied.
FPubnubChannelData​

FieldTypeDescription
ChannelID
FString
ID of the channel.
ChannelName
FString
Name of the channel.
Description
FString
Additional description of the channel.
Custom
FString
JSON providing custom data about the user. Values must be scalar only; arrays or objects are not supported.
Status
FString
Channel status. Max 50 characters.
Type
FString
Channel type. Max 50 characters.
Updated
FString
The date when the channel's metadata was last updated.
ETag
FString
Version identifier of the user's metadata.
JSON Response​
{
    "Channels": [
        {
            "Channel": "my-channel",
            "Name": "My channel",
            "Description": "A channel that is mine",
            "Custom": "",
            "Updated": "2020-06-17T16:52:19.562469Z"
        },
        {
            "Channel": "main",
            "Name": "Main channel",
            "Description": "The main channel",
            "Custom": {
                "public": true,
show all 26 lines

Get Channel Metadata​

Returns metadata for the specified Channel, optionally including the custom data object for each.

Method(s)​

Response variants

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

Basic Usage​

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

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

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

FString Include = ""; // No additional attributes
FString Channel = "my-channel"; 

PubnubSubsystem->GetChannelMetadata(Include, Channel, OnGetChannelMetadataResponse);

Returns​

This method returns the FOnGetChannelMetadataResponse struct.

FOnGetChannelMetadataResponse​

FieldTypeDescription
Status
int
HTTP code of the result of the operation.
ChannelData
FPubnubChannelData
Aa instance of FPubnubChannelData struct which is the channel with its associated metadata.
JSON Response​
{
    "Channel": "my-channel",
    "Name": "My channel",
    "Description": "A channel that is mine",
    "Custom": "",
    "Updated": "2020-06-17T16:52:19.562469Z"
}

Set Channel Metadata​

Unsupported partial updates of custom metadata

The value of the custom metadata parameter sent in this method always overwrites the value stored on PubNub servers. If you want to add new custom data to an existing one, you must:

  1. Get the existing metadata and store it locally.
  2. Append the new custom metadata to the existing one.
  3. Set the entire updated custom object.

Set metadata for a channel in the database, optionally including the custom data object for each.

Method(s)​

Basic Usage​

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

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

FString Channel = "myChannel"; // Example Channel Metadata ID
FString Include = ""; // No additional attributes
FString ChannelMetadataObj = "{\"name\":\"PubNub channel\",\"description\":\"The channel for announcements\"}"; // Example JSON object

// Call the SetChannelMetadata method
PubnubSubsystem->SetChannelMetadata(Channel, Include, ChannelMetadataObj);
API limits

To learn about the maximum length of parameters used to set channel metadata, refer to REST API docs.

Returns​

{
    "Channel": "my-channel",
    "Name": "PubNub channel",
    "Description": "The channel for announcements",
    "Updated": "2020-06-17T16:52:19.562469Z"
}

Other Examples​

Iteratively update existing metadata​
#include "PubnubSubsystem.h"
#include "GameFramework/Actor.h"
#include "Kismet/GameplayStatics.h"


UCLASS()
//Replace MYPROJECT with name of your project
class MYPROJECT_API AMyActor : public AActor
{
    GENERATED_BODY()

protected:
    virtual void BeginPlay() override;

private:
show all 70 lines

Remove Channel Metadata​

Removes the metadata from a specified channel.

Method(s)​

Basic Usage​

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

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

FString Channel = "myChannel"; // Example Channel Metadata ID

// Call the RemoveChannelMetadata method
PubnubSubsystem->RemoveChannelMetadata(Channel);

Returns​

This method doesn't have any return value.

Channel Memberships​

Get Channel Memberships​

The method returns a list of channel memberships for a user. This method doesn't return a user's subscriptions.

Method(s)​

Response variants

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

Basic Usage​

#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
FOnGetMembershipsResponse OnGetMembershipResponse;
OnGetMembershipResponse.BindDynamic(this, &AMyActor::OnGetMembershipResponse);

User UserId = "user-1"
int Limit = 10; // Limit to 10 objects
show all 18 lines

Returns​

This method returns the FOnGetMembershipsResponse struct.

FOnGetMembershipsResponse​
FieldTypeDescription
Status
int
HTTP code of the result of the operation.
MembershipsData
TArray<FPubnubGetChannelMembershipWrapper>&
Aa array of FPubnubGetChannelMembershipsWrapper structs which are the memberships of the channel.
PageNext
FString
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
PagePrev
FString
Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the pageNext parameter is supplied.
FPubnubGetChannelMembershipsWrapper​

FieldTypeDescription
Channel
FPubnubChannelData
Contains channel metadata, including unique channel identifier and other relevant information.
Custom
FString
JSON providing custom data about the membership. Values must be scalar only; arrays or objects are not supported.
Status
FString
Status of the membership. Max 50 characters.
Type
FString
Type of the membership. Max 50 characters.
Updated
FString
The date when the channel's membership was last updated.
ETag
FString
Version identifier of the membership metadata.
JSON Response​
{
    "Memberships": [
        {
            "ChannelMetadata": {
                "Channel": "my-channel",
                "Name": "My channel",
                "Description": "A channel that is mine",
                "Custom": "",
                "Updated": "2020-06-17T16:55:44.632042Z"
            },
            "Custom": {
                "starred": false
            },
            "Updated": "2020-06-17T17:05:25.987964Z"
        },
show all 38 lines

Set Channel Memberships​

Set channel memberships for a User.

Method(s)​

API limits

To learn about the maximum length of parameters used to set user metadata, refer to REST API docs.

Basic Usage​

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

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

FString User = "user123"; // Example User ID
FString Include = ""; // No additional attributes
FString SetObj = "{\"channels\": [{\"channel123\": {\"name\":\"Channel One\"}}]}"; // Example JSON object

// Call the SetMemberships method
PubnubSubsystem->SetMemberships(User, Include, SetObj);
API limits

To learn about the maximum length of parameters used to set channel membership metadata, refer to REST API docs.

Returns​

{
    "Memberships": [
        {
            "ChannelMetadata": {
                "Channel": "my-channel",
                "Name": "My channel",
                "Description": "A channel that is mine",
                "Custom": "",
                "Updated": "2020-06-17T16:55:44.632042Z"
            },
            "Custom": {
                "starred": false
            },
            "Updated": "2020-06-17T17:05:25.987964Z"
        },
show all 38 lines

Remove Channel Memberships​

Remove channel memberships for a user.

Method(s)​

Basic Usage​

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

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

FString User = "user123"; // Example User ID
FString Include = ""; // No additional attributes
FString RemoveObj = "{\"channels\": [{\"channel123\": {\"name\":\"Channel One\"}}]}"; // Example JSON object

// Call the RemoveMemberships method
PubnubSubsystem->RemoveMemberships(User, Include, RemoveObj);

Returns​

{
    "Memberships": [
        {
            "ChannelMetadata": {
                "Channel": "my-channel",
                "Name": "My channel",
                "Description": "A channel that is mine",
                "Custom": "",
                "Updated": "2020-06-17T16:55:44.632042Z"
            },
            "Custom": {
                "starred": false
            },
            "Updated": "2020-06-17T17:05:25.987964Z"
        },
show all 38 lines

Channel Members​

Get Channel Members​

The method returns a list of members in a channel. The list will include user metadata for members that have additional metadata stored in the database.

Method(s)​

Response variants

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

Basic Usage​

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

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

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

FString Channel = "my-channel";
int Limit = 10; // Limit to 10 objects
EPubnubTribool Count = PT_False; // Don't include total count

show all 16 lines

Returns​

This method returns the FOnGetChannelMembersResponse struct.

FOnGetChannelMembersResponse​

FieldTypeDescription
Status
int
HTTP code of the result of the operation.
MembersData
TArray<FPubnubGetChannelMembersWrapper>&
Aa array of FPubnubGetChannelMembersWrapper structs which are the members of the channel.
PageNext
FString
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
PagePrev
FString
Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the pageNext parameter is supplied.
FPubnubGetChannelMembersWrapper​

FieldTypeDescription
User
FPubnubUserlData
Contains user metadata, including unique channel identifier and other relevant information.
Custom
FString
JSON providing custom data about the member. Values must be scalar only; arrays or objects are not supported.
Status
FString
Status of the member. Max 50 characters.
Type
FString
Type of the member. Max 50 characters.
Updated
FString
The date when the channel's member was last updated.
ETag
FString
Version identifier of the member metadata.
JSON Response​
{
    "ChannelMembers": [
        {
            "UuidMetadata": {
                "Uuid": "uuid-1",
                "Name": "John Doe",
                "Email": "john.doe@pubnub.com",
                "ExternalId": "",
                "ProfileUrl": "",
                "Custom": "",
                "Updated": "2019-02-20T23:11:20.89375"
            },
            "Custom": {
                "role": "admin"
            },
show all 39 lines

Set Channel Members​

This method sets members in a channel.

Method(s)​

API limits

To learn about the maximum length of parameters used to set user metadata, refer to REST API docs.

Basic Usage​

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

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

FString Channel = "myChannel";
FString Include = ""; // No additional attributes
FString SetObj = TEXT([{"id": "some-user-id", "custom": {"starred": true}}, {"id": "user-0-id", "some_key": {"other_key": "other_value"}}]); // Example JSON object

// Call the SetChannelMembers method
PubnubSubsystem->SetChannelMembers(Channel, Include, SetObj);
API limits

To learn about the maximum length of parameters used to set channel members metadata, refer to REST API docs.

Returns​

{
    "ChannelMembers": [
        {
            "UuidMetadata": {
                "Uuid": "uuid-1",
                "Name": "John Doe",
                "Email": "john.doe@pubnub.com",
                "ExternalId": "",
                "ProfileUrl": "",
                "Custom": "",
                "Updated": "2019-02-20T23:11:20.89375"
            },
            "Custom": {
                "role": "admin"
            },
show all 39 lines

Remove Channel Members​

Remove members from a channel.

Method(s)​

API limits

To learn about the maximum length of parameters used to set user metadata, refer to REST API docs.

Basic Usage​

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

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

FString Channel = "myChannel";
FString Include = ""; // No additional attributes
FString RemoveObj = TEXT([{"id": "some-user-id", "custom": {"starred": true}}, {"id": "user-0-id", "some_key": {"other_key": "other_value"}}]); // Example JSON object

// Call the RemoveChannelMembers method
PubnubSubsystem->RemoveChannelMembers(Channel, Include, RemoveObj);

Returns​

{
    "ChannelMembers": [
        {
            "UuidMetadata": {
                "Uuid": "uuid-1",
                "Name": "John Doe",
                "Email": "john.doe@pubnub.com",
                "ExternalId": "",
                "ProfileUrl": "",
                "Custom": "",
                "Updated": "2019-02-20T23:11:20.89375"
            },
            "Custom": {
                "role": "admin"
            },
show all 39 lines
Last updated on
On this page