Leaderboards

This guide shows you how to use leaderboards APIs in an Android application to create visual leaderboards, record a player's score, and compare the score against the player's score from previous game sessions.

If you haven't already done so, you might find it helpful to review the leaderboards game concepts.

To start using the leaderboards API, your game must first obtain a AN_LeaderboardsClient object. You can do this by calling the AN_Games.GetLeadeboardsClient() method.

Updating the player's score

When the player's score changes (for example, when the player finishes the game), your game can update their score on the leaderboard by calling AN_LeaderboardsClient .SubmitScore(), and passing in the leaderboard ID and the raw score value. The following code snippet shows how your app can update the player’s score:

using SA.Android.GMS.Games;
...

string leaderboardsId = "YOUR_LeaderboardsId_HERE";
var leaderboards = AN_Games.GetLeaderboardsClient();
leaderboards.SubmitScore(leaderboardsId, 250);

You may also use the SubmitScoreImmediate method. This form of the API will attempt to submit the score to the server immediately within the callback, returning a AN_ScoreSubmissionData on success with information about the submission. See the snippet below:
 

using SA.Android.GMS.Games;
...

long score = 200;
string scoreTag = "Tag";
string leaderboardsId = "YOUR_LeaderboardsId_HERE";
var leaderboards = AN_Games.GetLeaderboardsClient();
leaderboards.SubmitScoreImmediate(leaderboardsId, score, scoreTag, (result) => {

    if(result.IsSucceeded) {
        var scoreSubmissionData = result.Data;
        AN_Logger.Log("SubmitScoreImmediate completed");
        AN_Logger.Log("scoreSubmissionData.PlayerId: " + scoreSubmissionData.PlayerId);
        AN_Logger.Log("scoreSubmissionData.LeaderboardId: " + scoreSubmissionData.LeaderboardId);

        foreach (AN_Leaderboard.TimeSpan span in (AN_Leaderboard.TimeSpan[])System.Enum.GetValues(typeof(AN_Leaderboard.TimeSpan))) {
            var scoreSubmissionResult = scoreSubmissionData.GetScoreResult(span);
            AN_Logger.Log("scoreSubmissionData.FormattedScore: " + scoreSubmissionResult.FormattedScore);
            AN_Logger.Log("scoreSubmissionData.NewBest: " + scoreSubmissionResult.NewBest);
            AN_Logger.Log("scoreSubmissionData.RawScore: " + scoreSubmissionResult.RawScore);
            AN_Logger.Log("scoreSubmissionData.ScoreTag: " + scoreSubmissionResult.ScoreTag);
        }
    } else {
        AN_Logger.Log("Failed to Submit Score Immediate " + result.Error.FullMessage);
    }

});

Displaying a leaderboard

To display leaderboard, call AN_LeaderboardsClient.GetLeaderboardIntent() to get an Intent to create the default leaderboard user interface. Your game can then bring up the UI by calling StartActivityForResult. The following code snippet shows how your app can display the default leaderboards user interface.

using SA.Android.App;
using SA.Android.GMS.Games;
...

var leaderboards = AN_Games.GetLeaderboardsClient();
leaderboards.GetAllLeaderboardsIntent((result) => {
    if (result.IsSucceeded) {
        var intent = result.Intent;
        AN_ProxyActivity proxy = new AN_ProxyActivity();
        proxy.StartActivityForResult(intent, (intentResult) => {
            proxy.Finish();
            //Note: you might want to check is user had sigend out with that UI
        });

    } else {
        Debug.Log("Failed to Get leaderboards Intent " + result.Error.FullMessage);
    }
});

An example of the default leaderboards UI is shown below.

Creating In-Game leaderboards UI

If instead of using the default Google Play UI, you may build your own leaderboards in-game UI. In order to do so, you are going to need to load the leaderboards metadata. See the snippet below:

using SA.Android.GMS.Games;
...

var leaderboards = AN_Games.GetLeaderboardsClient();
leaderboards.LoadLeaderboardMetadata(false, (result) => {
    if (result.IsSucceeded) {
        AN_Logger.Log("Load Leaderboards Metadata Succeeded, count: " + result.Leaderboards.Count);
        PrintLeaderboardsInfo(result.Leaderboards);

    } else {
        AN_Logger.Log("Load Leaderboards Failed: " + result.Error.FullMessage);
    }
});

private void PrintLeaderboardsInfo(List<AN_Leaderboard> leaderboards) {
    foreach (var leaderboard in leaderboards) {
        AN_Logger.Log("------------------------------------------------");
        AN_Logger.Log("leaderboard.LeaderboardId: " + leaderboard.LeaderboardId);
        AN_Logger.Log("leaderboard.Description: " + leaderboard.DisplayName);
        AN_Logger.Log("leaderboard.Name: " + leaderboard.IconImageUri);
        AN_Logger.Log("leaderboard.UnlockedImageUri: " + leaderboard.LeaderboardScoreOrder);

        AN_Logger.Log("leaderboard.Variants.Count: " + leaderboard.Variants.Count);

        foreach (var variant in leaderboard.Variants) {
            AN_Logger.Log("***************************");
            AN_Logger.Log("variant.Collection: " + variant.Collection);
            AN_Logger.Log("variant.DisplayPlayerRank: " + variant.DisplayPlayerRank);
            AN_Logger.Log("variant.DisplayPlayerScore: " + variant.DisplayPlayerScore);
            AN_Logger.Log("variant.NumScores: " + variant.NumScores);
            AN_Logger.Log("variant.PlayerRank: " + variant.PlayerRank);
            AN_Logger.Log("variant.PlayerScoreTag: " + variant.PlayerScoreTag);
            AN_Logger.Log("variant.RawPlayerScore: " + variant.RawPlayerScore);
            AN_Logger.Log("variant.TimeSpan: " + variant.TimeSpan);
            AN_Logger.Log("variant.HasPlayerInfo: " + variant.HasPlayerInfo);

        }
    }
    AN_Logger.Log("------------------------------------------------");
}

Once you able to build your own leaderboards UI. You may also want to load leaderboards scores content in order to display it inside your game. And you able to do it with the following methods of AN_LeaderboardsClient object:

void LoadPlayerCenteredScores(string leaderboardId, int maxResults, Action<AN_LinkedObjectResult<AN_LeaderboardScores>> callback);
void LoadPlayerCenteredScores(string leaderboardId, AN_Leaderboard.TimeSpan span, AN_Leaderboard.Collection leaderboardCollection, int maxResults, bool forceReload, Action<AN_LinkedObjectResult<AN_LeaderboardScores>> callback);

void LoadTopScores(string leaderboardId, int maxResults, Action<AN_LinkedObjectResult<AN_LeaderboardScores>> callback);
void LoadTopScores(string leaderboardId, AN_Leaderboard.TimeSpan span, AN_Leaderboard.Collection leaderboardCollection, int maxResults, bool forceReload, Action<AN_LinkedObjectResult<AN_LeaderboardScores>> callback);

void LoadMoreScores(AN_LeaderboardScoreBuffer buffer, int maxResults, AN_PageDirection pageDirection, Action<AN_LinkedObjectResult<AN_LeaderboardScores>> callback);

Let's, for example, use the LoadTopScores method to load top leaderboards scores:

using SA.Android.GMS.Games;
...

int maxResults = 20;
string leaderboardsId = "YOUR_LeaderboardsId_HERE";
var leaderboards = AN_Games.GetLeaderboardsClient();
leaderboards.LoadTopScores(leaderboardsId, maxResults, (result) => {

    if(result.IsSucceeded) {
        var scores = result.Data;
        var buffer = scores.Scores;
        AN_Logger.Log("scores.Leaderboard.DisplayName: " + scores.Leaderboard.DisplayName);
        AN_Logger.Log("Loaded scores Count: " + buffer.Scores.Count);

        foreach (var score in buffer.Scores) {
            AN_Logger.Log("score.DisplayRank: " + score.DisplayRank);
            AN_Logger.Log("score.DisplayScore: " + score.DisplayScore);
            AN_Logger.Log("score.Rank: " + score.Rank);
            AN_Logger.Log("score.RawScore: " + score.RawScore);
            AN_Logger.Log("score.ScoreHolder: " + score.ScoreHolder);
            AN_Logger.Log("score.ScoreHolderDisplayName: " + score.ScoreHolderDisplayName);
            AN_Logger.Log("score.ScoreHolderIconImageUri: " + score.ScoreHolderIconImageUri);
            AN_Logger.Log("score.ScoreHolderHiResImageUri: " + score.ScoreHolderHiResImageUri);
            AN_Logger.Log("score.ScoreTag: " + score.ScoreTag);
            AN_Logger.Log("score.TimestampMillis: " + score.TimestampMillis);
            AN_Logger.Log("------------------------------------------------");
        }
    } else {
        AN_Logger.Log("Failed to Load Top Scores " + result.Error.FullMessage);
    }
});