Leaderboards can be a fun way to drive competition among your players, both for your most hardcore fans (who will be fighting for the top spot in a public leaderboard) and for your more casual players (who will be interested in comparing their progress to their friends').
The Google Play Games leaderboards service is supported on these platforms:
- Android through the Google Play services SDK
- iOS through the iOS SDK
- Web through the REST API
- C++ through the C++ SDK
To learn how to implement leaderboards for these platforms, see Client implementations.
When you create a leaderboard, the Game services will take care of managing most aspects of this leaderboard for you. The typical process works like this:
- 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.
- The Game services checks if this score is better than the player's current leaderboard entry for the daily, weekly, or all-time score. If it is, the Game services updates the corresponding leaderboards with the new score.
- The Game services sends 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 Game services will tell the client what the current daily, weekly, or all-time high score is for this player.
- 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 Game service performs all the necessary filtering, and then sends the results back to the client.
- In cases where there are a lot of scores to report, the Game 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's.
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 Game services SDK automatically creates daily, weekly, and all-time versions of every leaderboard that you create. There's no need for you to create 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 Game 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 user's 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.
For more information about social and public leaderboards, including important information to consider when building your own leaderboard widgets, see Advanced Topics in 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.
To create and manage leaderboards, you'll want to be familiar with these leaderboard attributes:
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.hideto 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.
While all scores are submitted to leaderboards and stored internally as long integers, the Game 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 of
314159, for example, would be displayed as
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
66032would be interpreted as
- 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
$19.95, 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 Game 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 Game 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.
12,345.78 in the US, and
12 345,78 in France.) If you are using
custom units and have added
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 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.
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 much fine detail. 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 recommend against 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 the Save 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're done editing 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.
Resetting a leaderboard
You can only reset player progress data for your draft leaderboards.
- To reset leaderboards in the Google Play Developer Console, click the button labeled Reset leaderboard progress at the bottom of the form for that event.
- To reset leaderboard data programmatically, call the
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 have created 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 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.
Hiding leaderboard scores
Play Game services provides a leaderboard tamper protection feature that checks for suspected tampered scores and hides them automatically. This feature is available for Android games only.
Tamper protection is enabled by default for new leaderboards that you create for your Android game, but is disabled for existing leaderboards. To enable tamper protection for your existing leaderboards that are already published, follow these steps:
- In the Google Play Developer Console, open the Games services tab, then select your game from the list.
- Open the Leaderboards tab, then select the leaderboard instance for which you want to enable tamper protection.
- Turn the Enable leaderboard tamper protection option to ON.
- Click Save and continue.
- Publish your game.
Once tamper protection is enabled for a leaderboard in the Google Play Developer Console, it may take up to 24 hours before this feature takes effect. Scores submitted before you enabled tamper protection are not retroactively hidden.
In some situations, you may want to disable tamper protection (for example, if your game also runs on iOS or the web in addition to Android, and shares leaderboards across these platforms).