Display a player's ranking using the new Leaderboard service

Last updated on October 24, 2024

Overview

The AccelByte Gaming Services (AGS) Leaderboard service allows you to create a competitive atmosphere among players by displaying the leaderboard and providing information about player rankings.

Goals

• Explain how to use the SDK to retrieve a leaderboard, or retrieve a specific player's ranking.
• Provide an overview of how to display the leaderboard.
• Explain how to display the leaderboard for all time and a specific time window.
• To explain how to use leaderboards using AGS SDK.

Prerequisites

• Access to the AGS Admin Portal.
• Access to AccelByte Unreal, Unity or Extend SDK.
• Access to the AGS Leaderboard. View the API documentation for more information.
• A leaderboard configuration you want to display. You can use the guide on new cycled leaderboards to create a leaderboard configuration.

Display the leaderboard rankings

To display the leaderboard rankings, you need to get the leaderboard data using the desired leaderboard code and time frame/cycle of the leaderboard. The total number of players that you want to display from the leaderboard also can be set based on your game's needs.

You can use the following function to get the leaderboard rankings:

Get leaderboard rankings

Unreal Engine

const FApiClientPtr ApiClient = FMultiRegistry::GetApiClient("Client1");


ApiClient->Leaderboard.GetRankingsV3(LeaderboardCode,Offset, Limit,
THandler<FAccelByteModelsLeaderboardRankingResultV3>::CreateLambda(
[&](const FAccelByteModelsLeaderboardRankingResultV3& Response)
{
   // Handle response data here
}),
FErrorHandler::CreateLambda(
[&](const int32 Code, const FString& Message)
{
   // Handle error here
}));

Unity

var leaderboard = AccelByteSDK.GetClientRegistry().GetApi().GetLeaderboard();

var leaderboardCode = "leaderboardCode";

leaderboard.GetRankingsV3(leaderboardCode, result => 
{
   if (result.IsError)
   {
      // Do something if GetRankingsV3 has an error
      Debug.Log($"Error GetRankingsV3, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");

      return;
   }

   foreach(var data in result.Value.data)
   {
      // Do something with the ranking data
   }
});

Go Extend SDK

leaderboardDataV3Service := &leaderboard.LeaderboardDataV3Service{
   Client:          factory.NewLeaderboardClient(&repository.ConfigRepositoryImpl{}),
   TokenRepository: &repository.TokenRepositoryImpl{},
}
leaderboardCode := "myleaderboardcode"
namespace := "mygame"
limit := int64(50)
offset := int64(0)
input := &leaderboard_data_v3.GetAllTimeLeaderboardRankingPublicV3Params{
   LeaderboardCode: leaderboardCode,
   Namespace:       namespace,
   Limit:           &limit,
   Offset:          &offset,
}
result, err := leaderboardDataV3Service.GetAllTimeLeaderboardRankingPublicV3Short(input)

Python Extend SDK

import accelbyte_py_sdk.api.leaderboard as leaderboard_service

result, error = leaderboard_service.get_all_time_leaderboard_ranking_public_v3(
    leaderboard_code="SomeLeaderboardCode",
    limit=99,
    offset=0,
)
if error:
   exit(error)

Java Extend SDK

final LeaderboardDataV3 leaderboardDataV3Wrapper = new LeaderboardDataV3(sdk);

String leaderboardCode = "<my-leaderboard-code>";
ModelsGetLeaderboardRankingResp response;
try {
  response = leaderboardDataV3Wrapper.getAllTimeLeaderboardRankingPublicV3(GetAllTimeLeaderboardRankingPublicV3.builder()
      .namespace("<namespace>")
      .leaderboardCode(leaderboardCode)
      .offset(0)
      .limit(50)
      .build());
} catch (Exception e) {
   // Do something when failed
   return;
}

if (response == null) {
    // Null response from server
} else {
   // Do something when success
}

C# Extend SDK

string leaderboardCode = "<my-leaderboard-code>";

var response = sdk.Leaderboard.LeaderboardDataV3.GetAllTimeLeaderboardRankingPublicV3Op
    .SetOffset(0)
    .SetLimit(50)
    .Execute(leaderboardCode, sdk.Namespace);
if (response != null)
{
    //do something when success
}

Display a specific player's ranking

You can display or highlight a specific player's ranking.

You can get a specific player's ranking using their user ID with the following function:

Get a specific player's ranking

Unreal Engine

const FApiClientPtr ApiClient = FMultiRegistry::GetApiClient("Client1");


ApiClient->Leaderboard.GetUserRankingV3("UserId",LeaderboardCode,
THandler<FAccelByteModelsUserRankingDataV3>::CreateLambda([&](const FAccelByteModelsUserRankingDataV3& Response)
{
   // Handle response data here 


}), FErrorHandler::CreateLambda([&](const int32 Code, const FString& Message)
{
   // Handle error here
}));

Unity

var leaderboard = AccelByteSDK.GetClientRegistry().GetApi().GetLeaderboard();;

var userId = "userId";
var leaderboardCode = "leaderboardCode";

leaderboard.GetUserRankingV3(userId, leaderboardCode, result => 
{
   if (result.IsError)
   {
      // Do something if GetUserRankingV3 has an error
      Debug.Log($"Error GetUserRankingV3, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");

      return;
   }

   // Do something with user data
   // result.Value.AllTime;
   // result.Value.Cycles;
});

Go Extend SDK

leaderboardDataV3Service := &leaderboard.LeaderboardDataV3Service{
   Client:          factory.NewLeaderboardClient(&repository.ConfigRepositoryImpl{}),
   TokenRepository: &repository.TokenRepositoryImpl{},
}
leaderboardCode := "myleaderboardcode"
namespace := "mygame"
userId := "myuserid"
input := &leaderboard_data_v3.GetUserRankingPublicV3Params{
   LeaderboardCode: leaderboardCode,
   Namespace:       namespace,
   UserID:          userId,
}
result, err := leaderboardDataV3Service.GetUserRankingPublicV3Short(input)

Python Extend SDK

result, error = leaderboard_service.get_user_ranking_public_v3(
    leaderboard_code="SomeLeaderboardCode",
    user_id="********************************",
)
if error:
   exit(error)

Java Extend SDK

final LeaderboardDataV3 leaderboardDataV3Wrapper = new LeaderboardDataV3(sdk);

String leaderboardCode = "<my-leaderboard-code>";
String userId = "<user-id>";
ModelsUserRankingResponseV3 response;
try {
  response = leaderboardDataV3Wrapper.getUserRankingPublicV3(GetUserRankingPublicV3.builder()
      .namespace("<namespace>")
      .userId(userId)
      .leaderboardCode(leaderboardCode)
      .build());
} catch (Exception e) {
   // Do something when failed
   return;
}

if (response == null) {
   // Null response from server
} else {
   // Do something when success
}

C# Extend SDK

string leaderboardCode = "<my-leaderboard-code>";
string userId = "<user-id>";

var response = sdk.Leaderboard.LeaderboardDataV3.GetUserRankingPublicV3Op
    .Execute(leaderboardCode, sdk.Namespace, userId);
if (response != null)
{
    //do something when success
}