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.

To start using the leaderboards API, your game must first obtain a UM_iLeaderboardsClient object. You can do this by calling the UM_GameService.LeaderboardsClient property.

using SA.CrossPlatform.GameServices;
...

var client = UM_GameService.LeaderboardsClient;

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 UM_iLeaderboardsClient.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.CrossPlatform.GameServices;
...

var client = UM_GameService.LeaderboardsClient;

//The identifier for the leaderboard.
var leaderboardId = "YOUR_LEADERBOARD_ID_HERE";

/// The score earned by the player.
/// You can use any algorithm you want to calculate scores in your game. 
/// Your game must set the value property before reporting a score, otherwise an error is returned.
/// The value provided by a score object is interpreted by Game service provided only when formatted for display.
int score = 250;

/// An integer value used by your game.
/// 
/// The context property is stored and returned to your game, 
/// but is otherwise ignored by Game Center. 
/// It allows your game to associate an arbitrary 64-bit unsigned integer value 
/// with the score data reported to Game Center. 
/// You decide how this integer value is interpreted by your game. 
/// For example, you might use the context property 
/// to store flags that provide game-specific details about a player’s score, 
/// or you might use the context as a key to other data stored on the device or on your own server. 
/// The context is most useful when your game displays a custom leaderboard user interface.
int context = 0;

client.SubmitScore(leaderboardId, score, context, (result) => {
    if(result.IsSucceeded) {
        Debug.Log("Score submitted successfully");
    } else {
        Debug.Log("Failed to submit score: " + result.Error.FullMessage);
    }
});

Displaying a leaderboard

To bring up the native leaderboards UI, use the ShowUI method. See the code snippet below:

using SA.CrossPlatform.GameServices;
...

var client = UM_GameService.LeaderboardsClient;
client.ShowUI((result) => {
    if(result.IsSucceeded) {
        Debug.Log("User closed Leaderboards native view");
    } else {
        Debug.Log("Failed to start Leaderboards native view: " + result.Error.FullMessage);
    }
});

You may also specify the leaderboard you want to show the UI for:

using SA.CrossPlatform.GameServices;
...

var client = UM_GameService.LeaderboardsClient;
var leaderboardId = "YOUR_LEADERBOARD_ID_HERE";
client.ShowUI(leaderboardId, (result) => {
    if(result.IsSucceeded) {
        Debug.Log("User closed Leaderboards native view");
    } else {
        Debug.Log("Failed to start Leaderboards native view: " + result.Error.FullMessage);
    }
});

Or even set a TimeSpan:

using SA.CrossPlatform.GameServices;
...

var client = UM_GameService.LeaderboardsClient;
var leaderboardId = "YOUR_LEADERBOARD_ID_HERE";
client.ShowUI(leaderboardId, UM_LeaderboardTimeSpan.Weekly, (result) => {
    if(result.IsSucceeded) {
        Debug.Log("User closed Leaderboards native view");
    } else {
        Debug.Log("Failed to start Leaderboards native view: " + result.Error.FullMessage);
    }
});

Creating In-Game leaderboards UI

If instead of using the default UI provided by a game service, 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.CrossPlatform.GameServices;
...

var client = UM_GameService.LeaderboardsClient;
client.LoadLeaderboardsMetadata((result) => {
    if(result.IsSucceeded) {
        foreach(var leaderboard in result.Leaderboards) {
            Debug.Log("leaderboard.Identifier: " + leaderboard.Identifier);
            Debug.Log("leaderboard.Title: " + leaderboard.Title);
        }
    } else {
        Debug.Log("Failed to load leaderboards metadata " + result.Error.FullMessage);
    }
});

Apart from that, if you want to display the currently signed player score in your custom UI, you may load score using the LoadCurrentPlayerScore method.

using SA.CrossPlatform.GameServices;
...

var client = UM_GameService.LeaderboardsClient;
//The identifier for the leaderboard.
var leaderboardId = "YOUR_LEADERBOARD_ID_HERE";

//The period of time to which a player’s best score is restricted.
var span = UM_LeaderboardTimeSpan.AllTime;

//The scope of players to be searched for scores.
var collection = UM_LeaderboardCollection.Public;

client.LoadCurrentPlayerScore(leaderboardId, span, collection, (result) => {
    if (result.IsSucceeded) {
        UM_iScore score = result.Score;
        Debug.Log("score.Value: " + score.Value);
        Debug.Log("score.Rank: " + score.Rank);
        Debug.Log("score.Context: " + score.Context);
        Debug.Log("score.Date: " + score.Date); 
    } else {
        Debug.Log("Failed to load player score " + result.Error.FullMessage);
    }
});