How To Use Additional Ranking Fields

Summary

BACKND rankings have additional field values that allow you to add data outside the score provided by default in the rankings.

Nearly all data types for game information management, such as numbers and strings, may fit into the values. However, caution is required during actual development as the data size is limited to 64 bytes.

The calculation of bytes is as follows:

• Foreign characters including Korean: 2 bytes(Up to 32 characters can be entered if the additional field consists of Korean only.)
• Characters supported by the computer, such as English, numbers, and special characters: 1 byte

If a piece of data called 'magician' goes inside the additional field, its size is 8 bytes.
If a piece of data called '10000' goes inside the additional field, its size is 5 bytes.
If a piece of data called '2022-11-10T09:39:56.850Z' goes inside the additional field, its size is 24 bytes.

Therefore, the way of storing data may vary depending on the number and size of data cases.

• When there is 1 piece of data to be expressed in the additional field
• When there are 2 or more pieces of data to be expressed in the additional field

When there is 1 piece of data to be expressed in the additional field

If there is only one piece of data and its value is below 64 bytes, you may use the data without any changes.
If you wish to express only one item outside of the score provided by default in the ranking, such as level and combat power, you may implement it.

The following is the code that stores only one piece of level data in the additional field.

Data storage type

{
    extraData : 15
}

Data registration code

Param rankParam = new Param();

// userData is an arbitrary class and userData.Score is a number-type piece of data.  
rankParam.Add("score", userData.Score);

// userData.Level is a number-type piece of data.  
rankParam.Add("extraData", userData.Level);

Backnd.Leaderboard.Player.UpdateMyDataAndRefreshLeaderboard("aa6609c0-****-****-****-ffd79d523912", "DAILY_USER_RANK", rankDataIndate, rankParam);

Look up data

var bro = Backnd.Leaderboard.Player.GetLeaderboard("aa6609c0-****-****-****-ffd79d523912");

foreach(BACKND.LitJson.JsonData json in bro.FlattenRows()) {
    int level = int.Parse(json["extraData"].ToString());
}

When there are 2 or more pieces of data to be stored in the additional field

This is used to indicate all items outside of the score provided by default in the ranking, such as level and combat power.

In the additional field, two pieces of data are divided with a discriminator(comma, slash, special characters, etc.) inside the string value and stored in Param.
The order of listing the pieces of data and the order of parsing them after loading them from the server must be implemented within the client.

However, if data in a class or dictionary format are registered to the additional field and used without any changes, such as in the example below, the column names are added automatically, and the 64-byte limit will likely be exceeded even if there are two to three pieces of data.

Invalid way of storing data 1 - class converted to JSON

{
    "extraData": "{\"atk\":99999,\"def\":5,\"currentStage\":0,\"currentQuestClear\":0,\"clearTime\":0.0,\"nickname\":\"User1\"}"
}

Invalid way of storing data 2 - class stored

{
    "userinfo": {
        "atk": 99999,
        "def": 5,
        "currentStage": 0,
        "currentQuestClear": 0,
        "clearTime": 0.0,
        "nickname": "User1"
    }
}

Invalid data storage method

public class UserInfo {
    public int atk = 99999;
    public int def = 5;
    public int currentStage = 0;
    public int currentQuestClear = 0;
    public int clearTime = 0;
}
public void InsertRank() {
    Param param = new Param();
    param.Add("score",1);

    UserInfo userInfo = new UserInfo();

    // case 1. Registered as class format
    param.Add("extraData", userInfo);

    // case 2. Registered after being parsed into JSON
    var userInfoString = JsonMapper.ToJson(userInfo);
    param.Add("extraData", userInfoString);

    Backnd.Leaderboard.Player.UpdateMyDataAndRefreshLeaderboard("aa6609c0****-ffd79d523912", "tableName", "rowInDate", param);
}

Recommended way of storing data

Therefore, if you wish to register multiple pieces of data to the additional field, you must exclude the column names.
Also, the logic for the data must be configured so that the order of addition upon data registration from the client and the order of parsing upon data lookup are identical.

The following is a way of storing the above data by differentiating with an arbitrary delimiter(| special character) after excluding the column name.

Data indication example

{
    // Level|Stage information
    extraData : "99999|5|0|0|0.0|User1"
}

Storing data

Param rankParam = new Param();

rankParam.Add("score", userData.Score);

// userData.Level is an int type and the userData.StageInfo is a string.  
// The two values are separated by |.  
// The order goes from level to stageInfo.  
rankParam.Add("extraData", $"{userData.atk}|{userData.def}|{userData.currentStage}|{userData.currentQuestClear}|{userData.clearTime}|{userData.nickname}");

Backnd.Leaderboard.Player.UpdateMyDataAndRefreshLeaderboard("aa6609c0-****-****-****-ffd79d523912", "DAILY_USER_RANK", rankDataIndate, rankParam);

Look up data

var bro = Backnd.Leaderboard.Player.GetLeaderboard("aa6609c0-****-****-****-ffd79d523912");

foreach(BACKND.LitJson.JsonData json in bro.FlattenRows()) {
    // The delimiter, |, used for data registration is used to separate the string data.  
    string[] extraData = json["extraData"].ToString().Split("|");

    UserInfo userInfo = new UserInfo();

    userInfo.atk = int.Parse(extraData[0].ToString());
    userInfo.def = int.Parse(extraData[1].ToString());
    userInfo.currentStage = int.Parse(extraData[2].ToString());
    userInfo.currentQuestClear = int.Parse(extraData[3].ToString());
    userInfo.clearTime= float.Parse(extraData[4].ToString());
    userInfo.nickname = extraData[5].ToString();

}

Below is an example of indicating a ranking UI using two or more pieces of data.