Title Region Config Data

1. Overview

Title Region Config Data is a set of data associated with the title region. It is commonly used to store configuration data that is applicable across the title-region-wide, such as level experience ramp, damage rules, and so on. Currently, developers can construct title region config data by customizing a set of key-value pair data on portal. The title region config data can be modified either through CLI tools or manually on the portal. However, it is read-only for the game client/server.

After completing this tutorial, you will learn the following content:

• How to customize title region config data on the portal.
• How to query title region config data in code.

The usage of Title Region Config Data is almost the same as Title Config Data, with the main difference being that the scope of Title Region Config Data is limited to the title region, while Title Config Data applies to the entire title.

2. Customize Title Region Config Data

Log in to the web portal, enter the console and go to Title Region > Config Data:

2.1 Add New Item

Click the Add button to add a new item:

Field description:

• Key: Name of the item, composed of letters, numbers, underscores, and spaces, it must start with a letter and cannot exceed 128 characters.

• Is Json: Whether the Item value is required to comply with JSON constraints. If the developer wants to access this item value as a JsonValue in the code, it is recommended to set it to true and this will make a JSON constraint checking when editing the value.

• Server Only: Whether the item can only be accessed by the server.

  • True: readable to the game sever and invisible to the game client.
  • False: readable to the game sever and the game client.

• Description: Item description information, only used for item management, invisible to PgosSDK.

• Value: Value of the item, the maximum character length is 1048576 (1*1024*1024).

  • The string value obtained through PgosSDK query will be:

    • If Is Json is false: the same string as in the Portal edit box.

    • If Is Json is true: the string after removing blank characters in the Portal edit box.

Item value will be presented in the form of FKVDataValue structure, the developer can use the functions: AsStr, AsInt32, AsInt64, AsFloat, AsDouble, AsJson to get the data format he/she wants. The upper limit for the number of Title Region Config Data Items that can be created is 1000.

2.2 Edit Item Fields

If the developer wants to modify the item field, click the Edit link in the Operation column:

Pop-up editing panel:

When Is Json is set to true, the Value edit box will check JSON constraints.

2.3 Remove Existing Item

If you no longer need some items, you can select them and click the Remove button. Items that have been removed cannot be queried through PgosSDK.

2.4 Upload JSON

Title Region Config Data can be imported through a local JSON file. The content of the JSON file is a JsonObject, corresponding to the key-values in the Title Region Config Data, which means the first-level key-values in JsonObject will be used as the key-values of Title Region Config Data. For example:

{
    "AndroidPushSenderId": "594923569376",
    "CharacterLevelRamp": {
        "1": 0,
        "2": 2725,
        "3": 5440,
        "4": 8155,
        "5": 10875,
        "6": 13595,
        "7": 16310,
        "8": 19035,
        "9": 21750,
        "10": 24465
    },
    "CommunityWebsite": "http://mygame.community.gl",
    "MinimumInterstitialWait": "10.0",
    "NPC Bios": [
        {
            "NPC ID": "Dave",
            "Birthday": "6/15/74",
            "Loyalty Reward": "5pc Discount"
        },
        {
            "NPC ID": "Joan",
            "Birthday": "9/24/83",
            "Loyalty Reward": "Extra Slot"
        }
    ],
    "StandardStores": [
        "Gem Store"
    ],
    "StartingCharacterSlots": "3"
}

Click the Upload JSON button:

After uploading, you can see the imported Title Region Config Data items as follows:

The imported JSON is merged to Title Region Config Data in the way of supplement + overwrite, that is:

• If the key does not exist, then add a new item to the end, and set Server Only as true.
• If the key already exists, then overwrite its value, and keep its Server Only permission, description and position.

If the imported item value meets the JSON constraint, the Is Json will be automatically set to true.

2.5 Download JSON

Developers can select some items and export them to a local JSON file (if no items are selected, all items will be exported).

The format of the exported JSON file is the same as the imported one:

• If Is Json is true: the value is written to the file as the JsonValue.

• If Is Json is false: the value is written to the file as a normal string value.

3. Query Title Region Config Data

You can query title region config data of the specified keys, and you can query title region config data of all keys.

3.1 For Game Client

API	Description
GetTitleRegionConfigKVData	Query the specified key-value data of the title region config data.
GetAllTitleRegionConfigKVData	Query all key-value data of the title region config data.

GetTitleRegionConfigKVData Client API

Interface prototype:

/**
* Query the specified key-value data of the title region config data.
* 
* @param QueryKeys Keys to query
*/
void GetTitleRegionConfigKVData(
    const TArray<FString>& QueryKeys,
    TFunction<void(const FPgosResult& Ret, const FTitleRegionConfigKVDataQueryResult* Data)> Callback) const;

Example Code:

#include "PgosSDKCpp.h"

void SomeUObjectClass::SomeFunction()
{
 auto TitleRegionConfigData = IPgosSDKCpp::Get().GetClientTitleRegionConfigDataAPI();
 if (TitleRegionConfigData)
 {
     TArray<FString> QueryKeys = {TEXT("level_exp_ramp"), TEXT("use_cdn")};
     TitleRegionConfigData->GetTitleRegionConfigKVData(QueryKeys, [](const FPgosResult& Ret, const FTitleRegionConfigKVDataQueryResult* Data) {
         if (Ret.err_code == (int32)Pgos::PgosErrCode::kSuccess)
         {
             UE_LOG(LogTemp, Log, TEXT("GetTitleRegionConfigKVData Success"));
         }
         else
         {
             UE_LOG(LogTemp, Log, TEXT("GetTitleRegionConfigKVData Failed: err_code=%d, err_msg=%s"), Ret.err_code, *Ret.msg);
         }
     });
 }
}

GetAllTitleRegionConfigKVData Client API

Interface prototype:

/**
* Query all key-value data of the title region config data.
*/
void GetAllTitleRegionConfigKVData(TFunction<void(const FPgosResult& Ret, const FTitleRegionConfigKVDataQueryResult* Data)> Callback) const;

Example Code:

#include "PgosSDKCpp.h"

void SomeUObjectClass::SomeFunction()
{
 auto TitleRegionConfigData = IPgosSDKCpp::Get().GetClientTitleRegionConfigDataAPI();
 if (TitleRegionConfigData)
 {
     
     TitleRegionConfigData->GetAllTitleRegionConfigKVData([](const FPgosResult& Ret, const FTitleRegionConfigKVDataQueryResult* Data) {
         if (Ret.err_code == (int32)Pgos::PgosErrCode::kSuccess)
         {
             UE_LOG(LogTemp, Log, TEXT("GetAllTitleRegionConfigKVData Success"));
         }
         else
         {
             UE_LOG(LogTemp, Log, TEXT("GetAllTitleRegionConfigKVData Failed: err_code=%d, err_msg=%s"), Ret.err_code, *Ret.msg);
         }
     });
 }
}

3.2 For Game Server

API	Description
GetTitleRegionConfigKVData	Query the specified key-value data of the title region config data.
GetAllTitleRegionConfigKVData	Query all key-value data of the title region config data.

GetTitleRegionConfigKVData Server API

Interface prototype:

/**
* Query the specified key-value data of the title region config data.
* 
* @param QueryKeys Keys to query
*/
void GetTitleRegionConfigKVData(
    const TArray<FString>& QueryKeys,
    TFunction<void(const FPgosResult& Ret, const FTitleRegionConfigKVDataQueryResult* Data)> Callback) const;

Example Code:

#include "PgosSDKCpp.h"

void SomeUObjectClass::SomeFunction()
{
 auto TitleRegionConfigData = IPgosSDKCpp::Get().GetServerTitleRegionConfigDataAPI();
 if (TitleRegionConfigData)
 {
     TArray<FString> QueryKeys = {TEXT("level_exp_ramp"), TEXT("use_cdn")};
     TitleRegionConfigData->GetTitleRegionConfigKVData(QueryKeys, [](const FPgosResult& Ret, const FTitleRegionConfigKVDataQueryResult* Data) {
         if (Ret.err_code == (int32)Pgos::PgosErrCode::kSuccess)
         {
             UE_LOG(LogTemp, Log, TEXT("GetTitleRegionConfigKVData Success"));
         }
         else
         {
             UE_LOG(LogTemp, Log, TEXT("GetTitleRegionConfigKVData Failed: err_code=%d, err_msg=%s"), Ret.err_code, *Ret.msg);
         }
     });
 }
}

GetAllTitleRegionConfigKVData Server API

Interface prototype:

/**
* Query all key-value data of the title region config data.
*/
void GetAllTitleRegionConfigKVData(TFunction<void(const FPgosResult& Ret, const FTitleRegionConfigKVDataQueryResult* Data)> Callback) const;

Example Code:

#include "PgosSDKCpp.h"

void SomeUObjectClass::SomeFunction()
{
 auto TitleRegionConfigData = IPgosSDKCpp::Get().GetServerTitleRegionConfigDataAPI();
 if (TitleRegionConfigData)
 {
     
     TitleRegionConfigData->GetAllTitleRegionConfigKVData([](const FPgosResult& Ret, const FTitleRegionConfigKVDataQueryResult* Data) {
         if (Ret.err_code == (int32)Pgos::PgosErrCode::kSuccess)
         {
             UE_LOG(LogTemp, Log, TEXT("GetAllTitleRegionConfigKVData Success"));
         }
         else
         {
             UE_LOG(LogTemp, Log, TEXT("GetAllTitleRegionConfigKVData Failed: err_code=%d, err_msg=%s"), Ret.err_code, *Ret.msg);
         }
     });
 }
}

3.3 Key Errors Handling

Error Code	Relevant API	Handling Suggestion
kBackendServerValidateFail	GetTitleRegionConfigKVData Client API GetAllTitleRegionConfigKVData Client API GetTitleRegionConfigKVData Server API GetAllTitleRegionConfigKVData Server API	the input parameter is invalid, check error msg for detail.
kBackendAllFailed	GetTitleRegionConfigKVData Client API GetAllTitleRegionConfigKVData Client API GetTitleRegionConfigKVData Server API GetAllTitleRegionConfigKVData Server API	all the data to be queried failed, please check the 'fails' field to get the failure reason.
kSdkNetworkError	All Network API	network error, check error msg for detail.