Skip to main content
Version: 5.15.0

GetLeaderboardByScore

BackendUserLeaderboardByScoreReturnObject GetLeaderboardByScore(string leaderboardUuid, int score);
BackendUserLeaderboardByScoreReturnObject GetLeaderboardByScore(string leaderboardUuid, long score);

Parameters​

ValueTypeDescription
leaderboardUuidstringuuid of the ranking to look up
scoreint/longScore to look up

The leaderboardUuid value can be checked using the following methods:

Description​

Among the rank holders registered in the ranking, looks up the rank holder with the score value and rank holders above and below that score using a uuid value.

  • If there are multiple users with the looked-up score, all of them will be looked up.
  • Even if there are multiple users above and below the score, only one user above and below will be looked up.
  • This method cannot be called via SendQueue.

BackendUserLeaderboardByScoreReturnObject​

namespace BackEnd.Leaderboard
{
    public class UserLeaderboardItem
    {
        public string gamerInDate;
        public string nickname = string.Empty;
        public string score;
        public string index;
        public string rank;
        public string extraData = string.Empty;
        public string extraName = string.Empty;
    }

    public class BackendUserLeaderboardByScoreReturnObject : BackendUserLeaderboardReturnObject
    {    
        public long GetTotalCount();
        public List<UserLeaderboardItem> GetUserLeaderboardList();
        public List<UserLeaderboardItem> GetPreviousUserLeaderboardList();
        public List<UserLeaderboardItem> GetNextUserLeaderboardList();
    }
}

Example​

Synchronous​

var score = 0; //Score to look up
BackEnd.Leaderboard.BackendUserLeaderboardByScoreReturnObject bro = Backend.Leaderboard.User.GetLeaderboardByScore("01920445-a435-759e-bc3b-048a1e7a87aa", 5);

Debug.Log(bro.GetTotalCount());

// User with higher rank than the searched score
foreach(BackEnd.Leaderboard.UserLeaderboardItem item in bro.GetNextUserLeaderboardList())
{
    Debug.Log($"Rank {item.rank} : {item.nickname}");
    Debug.Log(item.ToString());
}

foreach(BackEnd.Leaderboard.UserLeaderboardItem item in bro.GetUserLeaderboardList())
{
    Debug.Log($"Rank {item.rank} : {item.nickname}");
    Debug.Log(item.ToString());
}

// User with lower rank than the searched score
foreach(BackEnd.Leaderboard.UserLeaderboardItem item in bro.GetPreviousUserLeaderboardList())
{
    Debug.Log($"Rank {item.rank} : {item.nickname}");
    Debug.Log(item.ToString());
}

Asynchronous​

var score = 0; //Score to look up
BackEnd.Leaderboard.User.GetLeaderboardByScore("leaderboardUuid", score, bro=> {
    Debug.Log(bro.GetTotalCount());

    // User with higher rank than the searched score
    foreach(BackEnd.Leaderboard.UserLeaderboardItem item in bro.GetNextUserLeaderboardList())
    {
        Debug.Log($"Rank {item.rank} : {item.nickname}");
        Debug.Log(item.ToString());
    }

    foreach(BackEnd.Leaderboard.UserLeaderboardItem item in bro.GetUserLeaderboardList())
    {
        Debug.Log($"Rank {item.rank} : {item.nickname}");
        Debug.Log(item.ToString());
    }

    // User with lower rank than the searched score
    foreach(BackEnd.Leaderboard.UserLeaderboardItem item in bro.GetPreviousUserLeaderboardList())
    {
        Debug.Log($"Rank {item.rank} : {item.nickname}");
        Debug.Log(item.ToString());
    }
});

ReturnCase​

Success cases​

When the lookup is successful
statusCode : 200
message : Success
returnValue : refer to GetReturnValuetoJSON

When the lookup is successful but the user of the ranking is not registered
statusCode : 200
message : Success
returnValue : {"rows":[],"previousRank":{"NULL":true},"nextRank":{"NULL":true},"totalCount":0}

When the lookup is successful but there is no user with that score
statusCode : 200
message : Success
returnValue : refer to GetReturnValuetoJSON

Error cases​

When the uuid is null or string.Empty
statusCode : 400
errorCode : ValidationException
message : leaderboardUuid is null or empty

When there is an attempt to look up with a non-existent uuid
StatusCode : 404
ErrorCode : NotFoundException
Message : leaderboard not found, leaderboard cannot be found

GetReturnValuetoJSON​

When the user with the score and users above and below that score all exist​

{
    "rows": [
        {
            "gamerInDate": "2024-05-08T07:17:20.455Z",
            "nickname": "match5",
            "rank": 5,
            "index": 4,
            "score": "5"
        }
    ],
    "previousRank": [
        {
            "gamerInDate": "2024-05-08T07:17:20.928Z",
            "nickname": "match6",
            "rank": 4,
            "index": 3,
            "score": "6"
        }
    ],
    "nextRank": [
        {
            "gamerInDate": "2024-05-08T07:17:19.951Z",
            "nickname": "match4",
            "rank": 6,
            "index": 5,
            "score": "4"
        }
    ],
    "totalCount": 10
}

When there are no users with the score but there is a user with a higher score​

{
    "rows": [],
    "previousRank": [
        {
            "gamerInDate": "2024-05-08T07:17:17.625Z",
            "nickname": "match0",
            "rank": 10,
            "index": 9,
            "score": "0"
        }
    ],
    "nextRank": {
        "NULL": true
    },
    "totalCount": 10
}

When there are no users with the score but there is a user with a lower score​

{
    "rows": [],
    "previousRank": {
        "NULL": true
    },
    "nextRank": [
        {
            "gamerInDate": "2024-05-08T07:17:22.518Z",
            "nickname": "match9",
            "rank": 1,
            "index": 0,
            "score": "9"
        }
    ],
    "totalCount": 10
}