Implementing Leaderboards in Your Android or Fire OS Game


This page describes how to implement the Leaderboards feature in your GameCircle app.

Step 1. Send a Score to Your Leaderboard

After initializing Amazon GameCircle in your game, you can submit scores to the service. Scores must be positive numbers.

// Replace YOUR_LEADERBOARD_ID with an actual leaderboard ID from your game.
LeaderboardsClient lbClient = agsClient.getLeaderboardsClient();
AGResponseHandle<SubmitScoreResponse> handle = lbClient.submitScore(YOUR_LEADERBOARD_ID, longScoreValue);

// Optional callback to receive notification of success/failure.
handle.setCallback(new AGResponseCallback<SubmitScoreResponse>() {

    public void onComplete(SubmitScoreResponse result) {
        if (result.isError()) {
            // Add optional error handling here.  Not strictly required
            // since retries and on-device request caching are automatic.
        } else {
            // Continue game flow.

Throughout the API, the _userData_ parameter in _submitScore()_ represents arbitrary object parameters that provide easy access to your own data from within a corresponding _RequestResponse_ handler, typically a callback method that you specify. This parameter can be set to null if it isn’t needed.

To help customers find the leaderboard, make sure to add a link to the in-game overlay somewhere in your game.

Button btnLeaderboardsOverlay;
btnOpenLeaderboardsOverlay.setOnClickListener(new OnClickListener() {

    public void onClick(View v) {

Get a Time-Filtered High Score

All Amazon GameCircle leaderboards come with three time filters by default: All-Time, Weekly, and Daily. All-Time leaderboards include the highest scores for each player since the leaderboard was created or was reset manually. Weekly leaderboards are cleared every Saturday night at midnight Pacific Daylight Time (PDT). Daily leaderboards are reset every day at midnight PDT.

lbClient.getLocalPlayerScore (YOUR_LEADERBOARD_ID, LeaderboardFilter.GLOBAL_WEEK, null).setCallback(new AGResponseCallback<GetPlayerScoreResponse>() {

    public void onComplete(GetPlayerScoreResponse result) {
        if (result.isError()) {
            // Handle getLocalPlayerScore error
        else {
            int rank = result.getRank();
            long score = result.getScoreValue();
            // Do work with weekly high score


The valid values for the LeaderboardFilter enum are:


Get a List of Leaderboards

The leaderboards client can generate a list of leaderboards in your game.

lbClient.getLeaderboards().setCallback(new AGResponseCallback<GetLeaderboardsResponse>() {

    public void onComplete(GetLeaderboardsResponse result) {
        if (result.isError()) {
            // Handle getLeaderboards error
        else {
            List<Leaderboard> leaderboards = result.getLeaderboards();
            // Do work with leaderboards

Control Placement of Leaderboard Toasts

You can control the placement of leaderboard toasts in your game.

The possible PopUpLocation values are listed here:




The default location is BOTTOM_CENTER.

To turn off all toasts in your game except for welcome toasts, execute the following:


Welcome toasts are always BOTTOM_CENTER.