Leaderboards can be a funny way to drive a competition among your players, both for your most hardcore fans (who will be fighting for the top spot in a public leaderboard) and more casual players (who will be interested in comparing their progress to their friends').

Understanding leaderboards

When you create a leaderboard, the Games services will take care of managing the majority of aspects of this leaderboard for you. The typical process works like this:

  1. At the end of a game (or at an appropriate moment that you've determined), the game submits the player's score to one or more leaderboards you've created for the game.
  2. The Games services check if this score is better than the player's current leaderboard entry for the daily, weekly or all-time score. If it is, the Games services update the corresponding leaderboards with the new score.
  3. The Games services send a score report back to the game client. This report tells the client whether this is a new daily, weekly or all-time high score. If it isn't, the Games services will tell the client what the current daily, weekly or all-time high score is for this player.
  4. To retrieve a player's results for a leaderboard, you can requests a time frame (daily, weekly, or all-time) and specify whether or not the user wants to see a social or public leaderboard. The Games service performs all the necessary filtering and then sends the results back to the client.
  5. In cases where there are a lot of scores to report, the Games service sends back only the data for the top leaderboard scores. You can also retrieve raw score data for the top scores or the scores adjacent to the player.

Multiple leaderboards

Games can have multiple leaderboards, up to a maximum of 70. For example, a multi-level game might provide a different leaderboard for each level, and a racing game might have a separate leaderboard for each track.

Leaderboard-time frames

The Play Games services SDK automatically creates daily, weekly, and all-time versions of every leaderboard that you create. There's no need for you to create the separate leaderboards for each time frame.

Daily leaderboards reset at midnight PST every day, and weekly leaderboards reset at Saturday midnight PST.

Public and social leaderboards

The Play Games services SDK can display two different versions of each leaderboard to the player:

The social leaderboard is a leaderboard made up of people in the users' circles (or, more accurately, members of the circles that the user has chosen to share with your application) who have decided to share their gameplay activity to the user.

The public leaderboard is a leaderboard made up of players who have chosen to share their gameplay activity publicly. If your player has not chosen to share their gameplay activity publicly, they won't appear in this leaderboard.

Note: Social leaderboards will initially be empty until you publish the corresponding leaderboard by using the Google Play Developer Console. To learn how to publish your leaderboard, see Publishing your game changes.

For more information about social and public leaderboards, including important information to consider when building your own leaderboard widgets, see Advanced Topics in Leaderboards.

Displaying leaderboards

In the mobile client libraries, the libraries take care of all the formatting and displaying of leaderboards. You can specify whether a player can see a specific leaderboard or see a list of all of your leaderboards that they can choose from.

You can also implement your own versions of the leaderboards by accessing the data directly from the client libraries.

Warning: Player names that you retrieve directly using the client libraries may contain Unicode characters (for example, if the name has non-English characters). If you are implementing your own version of a leaderboard UI that uses decorative fonts, make sure that your UI can display these names correctly.


To create and manage leaderboards, you'll want to be familiar with these leaderboard attributes:

The basics

These basic elements are associated with every leaderboard:

  • ID is a unique string that the Google Play Developer Console will generate for you. You'll use this unique ID to refer to the leaderboard in your game clients.
  • Name is a short name of the leaderboard (for example, " High Scores" or "Level 3"). This can be up to 100 characters.
  • Icon is a square icon that will be associated with your leaderboard. For best practices when creating your leaderboard icons, see the Icon Guidelines section below.
  • List order is the order in which the leaderboard will appear when a player views the leaderboards associated with your game.
  • Limits are optional values that define the lower and upper limits of scores that are allowed in the leaderboard. This can help you discard score submissions that are clearly fraudulent. You can also use Players.hide to hide players that you believe have submitted fraudulent scores from all leaderboards in your app.


Leaderboards can have one of two ordering types:

  • Larger is better leaderboards are the default. This is typically what you would see in most games where players earn points.
  • Smaller is better leaderboards are occasionally used in cases where a smaller score would be better. The most common examples of this type of leaderboard are in racing games, where the score represents the player's time to finish the race.

Note: Once a leaderboard is published, its ordering type ('Larger is better' or 'Smaller is better') is fixed and cannot be changed. You can still change a leaderboard list order after it is published.

Score formatting

While all scores are submitted to leaderboards and stored internally as long integers, the Games service can present them to the user in a number of different formats:

  • Numeric leaderboards present scores as numbers. These can be displayed as integers or as real numbers with a fixed number of decimal places. You submit the score as integers and the decimal point is inserted in the specified location. A score, for example, would be displayed as 3.141593141.59, or 314159, depending on the decimal place you specified.
  • Time leaderboards present scores in hours / minutes / seconds / hundredths of a second format. You must submit scores as milliseconds, so 66032 would be interpreted as 1:06.03.
  • Currency leaderboards present scores in a currency format. You submit scores as 1/1,000,000th of the main currency unit. For example, a score of 19,950,000 would be interpreted as, assuming you specified your currency as USD.

Numeric leaderboards also support custom units. For instance, if your game measures high scores in meters, you can specify "meters" as the default unit for your leaderboard.

Translations and score formatting

When the mobile client libraries request leaderboard data from the Games service, they specify a language and locale in which to display these scores. The REST API allows you to specify a locale-based language as well. The Games service returns formatted leaderboard scores appropriate for that language and locale. These formatted scores will appear whether or not you have added translations for your leaderboard.

For Numeric leaderboards, the number format is displayed differently per language. (For example, 12,345.78 in the US, and 12 345,78 in France.) If you are using custom units and have added translations to your game, you must supply translated units for every language you have added. The service then displays these translated units where appropriate.

Depending on the language you choose, you might need to supply different versions of the names of your units. In English, you'll need a version for one item and another for everything else (for instance, "meter" and "meters"). In Polish, on the other hand, you would need to provide a version for one unit, a few units, many units, and everything else. To learn more about the plural rules, see Quantity Strings (Plurals).

For Time leaderboards, the time format is displayed according to the player's language and locale. This will mainly be noticeable if you are using fractions of a second or have an hours value with more than 3 digits (for example, 4,815:16:23.42 in the US and 4.815:16:23,42 in Germany).

For Currency leaderboards the currency format will be displayed according to the player's language and locale. However, you cannot change the unit of currency. For example, if you specify your currency in USD, the game will display $19.95 in the US and 19,95 $ in France. But you cannot specify that your game shows dollars in the US and Euros in France.

Icon guidelines

Icons should be created as 512 x 512 PNG or JPEG files. Your icons will be scaled down in most game clients, so you should avoid creating icons with too many details. You can submit icons with an alpha channel, and the transparency will be retained. The leaderboard icon will be shown against a light gray background on iOS devices and against a somewhat darker gray background on Android devices, so choose an icon that can work well in both situations.

The same icon is used in all locales, so we do not recommend including any text or localized content in an icon.

Creating a leaderboard

For a new game

To create a leaderboard for a new and unpublished game, go to the Google Play Developer Console entry for your game, select the Leaderboard tab on the left, then click the Add new Leaderboard button.

Then, simply fill out the information required for this leaderboard.

Click Save, and your leaderboard will be made available in "Ready to publish" mode. Once you publish your game, all of your game's leaderboards will be published with it.

For a published game

To create an additional leaderboard for a game that has already been published, follow the same steps as above. The only difference is that theSave button will be relabeled as Save as draft and your leaderboard will be in a "Ready to test" mode. For more information on testing an updated version of a game, see Publishing Your Game Changes.

Once you've tested your leaderboard and are happy with it, you can republish your game with the new leaderboards, and they will be pushed out to the world.

Editing a leaderboard

To edit a leaderboard that you've already created, click the leaderboard in the Leaderboards tab of the Google Play Developer Console. At this point, you will see the same form you used when first creating the leaderboard, and you will be able to edit any of the fields as you wish.

When you have edited a leaderboard, click the Save as draft button. The newly edited leaderboard will be in a "ready to test" stage, and you'll be able to test it out. If it is working correctly, select Republish from the drop-down list, and this will republish your game, along with all your updated leaderboards to the public.

Undoing an edit

If you decide you don't like your newly-edited leaderboard and want to go back to the way it was beforehand, simply select "Revert" from the drop-down list, and all of your leaderboards will revert back to the already published version.

Deleting a leaderboard

You can delete leaderboards that are in draft state or that have been published. To delete a leaderboard in the Google Play Developer Console, click the button labeled "Delete" at the bottom of the form for that leaderboard.

Alternatively, you can call Players.hide to hide a player's leaderboard in the app.

Adding translations for leaderboards

You can specify your own translations for leaderboards that are associated with your game. Before you do so, first, make sure to complete the steps described in Adding translations for your game. You must also creat one or more leaderboards for your game.

To add your own translations for leaderboards, open the Leaderboards tab for your game in the Google Play Developer Console, then select an existing leaderboard. On the leaderboard details page, click the tab for a language that you have previously added in the Game details tab. In the leaderboard details page for that language, edit the form with your translations for that leaderboard. Click Save to store your translated leaderboard details.


Once the player is signed in and the GooglePlayConnection.State == GPConnectionState.STATE_CONNECTED, your game can start using the leaderboards APIs.

Loading Leaderboards

It's a good practice  to load leaderboards info after connection to google play, basic leaderboard info will contain leaderboard id and name + score data for current signed player. The following example will show the basic implementation:

GooglePlayManager.ActionLeaderboardsLoaded += OnLeaderBoardsLoaded;
GooglePlayManager.Instance.LoadLeaderBoards ();

private void OnLeaderBoardsLoaded(GooglePlayResult result) {
	GooglePlayManager.ActionLeaderboardsLoaded -= OnLeaderBoardsLoaded;
	if(result.IsSuccess) {
		if( GooglePlayManager.Instance.GetLeaderBoard(LEADERBOARD_ID) == null) {
			Debug.Log("Leader boards loaded", LEADERBOARD_ID + " not found in leader boards list");

        GPLeaderBoard leaderboard = GooglePlayManager.Instance.GetLeaderBoard(LEADERBOARD_ID);
        long score = leaderboard.GetCurrentPlayerScore(GPBoardTimeSpan.ALL_TIME, GPCollectionType.GLOBAL).LongScore;

		Debug.Log(LEADERBOARD_NAME + "  score",  score.ToString());
	} else {
		AndroidMessage.Create("Leader-Boards Loaded error: ", result.Message);

After leaderboards are loaded, you may use the following GooglePlayManager methods to get info about the leaderboards and scores inside the leaderboards:

public GPLeaderBoard GetLeaderBoard(string leaderboardId)
public Dictionary<string, GPLeaderBoard> LeaderBoards {get;}


The Leaderboard is represented as  GPLeaderBoard class and score is represented as GPScore class. These two classes use GPBoardTimeSpan and GPCollectionType enums.

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 submitScore, and passing in the leaderboard ID and the raw score value.

GooglePlayManager.Instance.SubmitScoreById(LEADERBOARD_ID, score);

A good practice is to define the leaderboard ID in your ids.xml file, so your game can reference the leaderboards by resource ID.

GooglePlayManager.Instance.SubmitScore (LEADERBOARD_NAME, score);

You can always find if the scores were submitted successfully by subscribing to the action:

GooglePlayManager.ActionSoreSubmited += OnScoreSubmited;
GooglePlayManager.Instance.SubmitScore (LEADERBOARD_NAME, score);

private void OnScoreSubmited(GP_LeaderboardResult result) {
	GooglePlayManager.ActionSoreSubmited -= OnScoreSubmited;

	string leaderboardId = result.LeaderboardId;
	string msg = result.Message;
	Debug.Log("Score Submit Result for leaderboard " + leaderboardId + " :" + msg);

The result is represented as a GP_LeaderboardResult object.

 Displaying a leaderboard

To display a leaderboard, call ShowLeaderBoardsUI:

GooglePlayManager.Instance.ShowLeaderBoardsUI ();

or you can show specific leaderboard UI with the ShowLeaderBoardById method:

GooglePlayManager.Instance.ShowLeaderBoardById (LEADERBOARD_ID);

An example of the default leaderboard UI is shown below.


Loading Global / Friends Scores

For example, if we want to show In-Game UI with friends or global scores result from the specific leaderboard, it may be very useful. For this purpose, we can use the following functions:


LoadPlayerCenteredScores(string leaderboardId, GPBoardTimeSpan span, GPCollectionType collection, int maxResults)

Asynchronously load the player-centered page of scores for a given leaderboard. If the player does not have a score on this leaderboard, this call will return the top page instead.


LoadTopScores(string leaderboardId, GPBoardTimeSpan span, GPCollectionType collection, int maxResults)

Asynchronously load the top page of scores for a given leaderboard


The following code snippet shows how you can retrieve and print player-centered page of scores with 10 scores results

private bool ScoresLoaded = false;
private GPLeaderBoard loadedLeaderBoard = null;

private void StartScoresLoadRequest() {
  GooglePlayManager.ActionScoreRequestReceived += ActionScoreRequestReceived;
  GPBoardTimeSpan displayTime = GPBoardTimeSpan.ALL_TIME;
  GPCollectionType displayCollection = GPCollectionType.FRIENDS;
  GooglePlayManager.Instance.LoadPlayerCenteredScores(LEADERBOARD_ID, displayTime, displayCollection, 10);

private void ActionScoreRequestReceived (GooglePlayResult result) {
  GooglePlayManager.ActionScoreRequestReceived -= ActionScoreRequestReceived;
  if(result.SsSuccess) {
    loadedLeaderBoard = GooglePlayManager.Instance.GetLeaderBoard(LEADERBOARD_ID);
    Debug.Log("Scores loaded, we can not print score list");
    ScoresLoaded = true;

private void PrintScores() {

  //Getting current player score
  int displayRank;
  GPScore currentPlayerScore = loadedLeaderBoard.GetCurrentPlayerScore(displayTime, displayCollection);
  if(currentPlayerScore == null) {
    //Player does not have rank at this collection / time
	//so let's show the top score
	//since we used loadPlayerCenteredScores function. we should have top scores loaded if player have no scores at this collection / time
	displayRank = 1;
  } else {
	//Let's show 5 results before curent player Rank
	displayRank = Mathf.Clamp(currentPlayerScore.rank - 5, 1, currentPlayerScore.rank);
	//let's check if displayRank we what to display before player score is exists
	while(loadedLeaderBoard.GetScore(displayRank, displayTime, displayCollection) == null) {

  for(int i = 1; i < 10; i++;) {
    GPScore score = loadedLeaderBoard.GetScore(i, displayTime, displayCollection);
	if(score != null) { 
      Debug.Log("Rank: "   + i.ToString());
      Debug.Log("Score: "  + score.LongScore.ToString());
      Debug.Log("PlayerId: " + score.PlayerId);
      GooglePlayerTemplate player = GooglePlayManager.Instance.GetPlayerById(score.playerId);
	  if(player != null) {
        Debug.Log("Player Name: "  + player.Name);
        Debug.Log("Player Avatar: "  + player.Icon);
	  } else {
        Debug.Log("Player Info Not yet loaded");


Full custom leaderboard implementation can be found at the CustomLeaderborUIExample example scene.


Displaying Score Tips 

When you are loading leaderbord info using:



You will get info of avaliable leaderboards ids and names. And also you are getting the current player Scores and Ranks. (6 results, 2collection type and 3 time spans)

Which can be easily accessed like this:

GPScore currentPlayerScore = loadedLeaderBoard.GetCurrentPlayerScore(displayTime, displayCollection);


When you are submiting score using:

GooglePlayManager.Instance.SubmitScoreById(LEADERBOARD_ID, score);

As result you will get ActionSoreSubmited action fired which will contain only updated  Scores results. (3 results for all time spans) But you will not get player Rank info updated. If you want ot know new rank of your player, you will have two ways how to do this.


1) By using UpdatePlayerScore method:

GooglePlayManager.Instance.UpdatePlayerScore(LEADERBOARD_ID, displayTime, displayCollection);

As a result, you will get ActionPlayerScoreUpdated action fired. And your current player Score and Rank will be updated in the leaderboard score collection for requested Time and Collection.

Warning: it may trigger duplicate entries with your player id in the leaderboard score collection.

2) By using LoadPlayerCenteredScores which will load new updated score table.



The full API use example can be found under the PlayServiceExample.cs script.