Implementing Leaderboards

Before continuing, confirm that you have completed all steps in Setting Up Your GameCircle Configuration and Initializing GameCircle in Your Game. GameCircle leaderboards will not function unless you have configured and initialized GameCircle.


You can have up to 50 leaderboards for each game in the Amazon Mobile App Distribution portal. You can create one leaderboard at a time, or create up to 50 leaderboards at once by uploading images to an Icon Gallery and then uploading a CSV file containing your leaderboard metadata, including titles and descriptions in up to 10 languages in addition to English. The instructions below document both leaderboard creation scenarios.

When creating leaderboards, be sure to follow the guidelines in the Requirements section; your leaderboards will not load properly otherwise.

Setting up leaderboards in your game requires these steps:

  1. Create a Draft Leaderboard
  2. Send a Score to Your Leaderboard
  3. Add a Link to the Leaderboard Overlay in Your Game
  4. Test Leaderboards
  5. Publish Leaderboards

Metadata and Image Icon Requirements

Review these requirements when you are ready to start creating leaderboards.


Keep leaderboard names to 25 characters (text and spaces only) and descriptions to 48 characters (text and spaces only). Amazon will automatically shorten your text to fit the available UX space.

Leaderboard IDs

You will supply a leaderboard ID when submitting a score from your game code to a leaderboard in your customers’ games. Leaderboard IDs can contain the letters A-Z (uppercase or lowercase), numbers, dashes, and underscores. Your customers don’t see the IDs.


Use PNG files that are 512 pixels x 512 pixels and have no transparent areas. When you submit a leaderboard image, Amazon applies a mask with rounded corners on a transparent background. The mask we use, mask-rounded-inverse-v2.png, is in the ../GameCircle/resources/image-masks directory of the SDK.


Score units should be plural nouns such as coins, zombies or points. It’s okay to add adjectives such as golden coins or blue zombies, but don’t combine score units with words that aren’t adjectives, such as coins earned, zombies killed or points scored. Round scores to whole numbers.

Step 1. Create a Draft Leaderboard

All GameCircle leaderboards are created with a status of Draft for testing purposes. After creating draft leaderboards, you must publish them in order to enable their display in your game. For instructions on publishing leaderboards, see Publish Leaderboards

There are two ways to add leaderboards to your game:

Option 1: Create a Single Leaderboard

These instructions assume that you have a game in the Amazon Mobile App Distribution Portal. If you do not have a game in the portal, sign in and in your Dashboard click Add a New App.

Follow these steps to create a single draft leaderboard:

  1. Sign in to your account on the Amazon Mobile App Distribution portal, and then click the Apps & Services tab.
  2. Click the GameCircle tab to open your dashboard.
  3. In the Leaderboards column, click the View link for a game.
  4. On the leaderboards page for your game, click Add a Leaderboard.

    Add a leaderboard

    Illustration 1: Add a Leaderboard page, showing one draft leaderboard

  5. Enter the required information: Display Title, Leaderboard ID, Description, and so forth.
  6. Select a Sort Order (Highest Scores First for games where the highest score is the best score or Lowest Scores First for games like racing and golf where the lowest score is the best score).

    Add a Leaderboard user interface

    Illustration 2: Leaderboard metadata page

  7. In the Leaderboard Icon area, click Select an Icon to open the Select an Icon window. This window will display image icons that you have previously uploaded. If you do not have an appropriate image icon in the window to represent the leaderboard, click Upload an Icon and navigate to an image on your computer. Follow the instructions to upload the image, and then return to the Add a Leaderboard page and use the Select an Icon control to select the image that you just uploaded.
  8. When you are ready, click Save.

If you want to add leaderboard titles and descriptions for your customers who speak other languages, follow the steps below to add translations.

Add Descriptions and Titles in Other Languages

If you wish, you can add titles and descriptions in additional languages. These translations will be displayed to your customers who have selected the appropriate locales in the settings control on their mobile devices.

The workflow for this procedure is to create a draft leaderboard in English (en_US), and then edit the leaderboard by adding metadata in the selected language(s). GameCircle does not translate leaderboard metadata for you.

  1. On the leaderboards home page, click the Add a Language dropdown and select one of these languages:
    • English (U.K.)
    • German
    • French
    • Italian
    • Spanish
    • Chinese
    • Japanese
    • Korean
    • Portuguese
    • Russian
  2. In the Add Language Options dialog box, click Add Language to confirm your choice.

    Options confirmation page

    Illustration 3: Add Language Options page

  3. To edit the leaderboard, on the leaderboard home page, in the language dropdown box, select the language you just added. In the Actions column, click Edit.

    Add a Language box

    Illustration 4: Language selection dropdown list

  4. On the Leaderboards page, click on any editable field, such as Title and then edit English or other language fields in-line as necessary. Click Save when you are ready. Adding a new language for one leaderboard adds metadata fields with placeholder text in English for the selected language(s) for all of your other leaderboards for that game. Before publishing your leaderboards, replace the placeholder text with the appropriate translations.

    The Leaderboards page will display one row of information for each language that you have chosen for the selected leaderboard.

Repeat the steps above to add additional languages to your leaderboards, or to edit the language for a selected leaderboard.

Option 2: Create Multiple Leaderboards

The GameCircle bulk upload feature enables you to upload up to 50 leaderboards in just a few steps. Use this procedure if you expect to display more than a handful of leaderboards in your game. Developers who plan to display leaderboards in multiple languages to match the locale of their game players should use the bulk upload procedure.

You do not have to upload all of your leaderboards in one operation. You can upload additional leaderboard information and images later, as long as the total number never exceeds 50.

In the following workflow, you must upload your leaderboard icon images to the Amazon Mobile App Distribution portal (Step 1) before you upload your leaderboard metadata (Step 2). Your metadata upload will fail if you do not upload the images first.

These instructions assume that you have at least one game in the Amazon Mobile App Distribution Portal.

Step 1: Using the Icon Gallery

In this procedure, you will select the images for your leaderboard icons and upload them to Amazon. If you wish, you can rename image files in the Icon Gallery before confirming the upload. For icon image standards, see the Requirements section.

  1. In the Mobile App Distribution Portal, return to the index page by clicking Apps & Services and then clicking the GameCircle link in the second row of links.
  2. For your game, in the Icon Gallery column, click the View link. On the Icon Gallery page that opens, click the Upload Multiple Icons tab. The Upload New Icons window opens.

    Image upload window

    Illustration 5: Upload New Icons box, before adding images

  3. In the Upload New Icons box for your game, drag-and-drop one image file from your computer into the box for each of the leaderboard icons that you will use in your game. You will see thumbnails of your uploaded leaderboard icons. If you wish, rename images by using the text box next to each image thumbnail.
  4. Review your icons to confirm that they are correct, and then click Save.
  5. For information about other uses of the Icon Gallery, see:

Step 2: Using the CSV Template to Upload Leaderboard Metadata

After uploading your icon images, follow these steps to upload the metadata for multiple draft leaderboards:

  1. If you have signed out, sign in to your account on the Amazon Mobile App Distribution portal. Click the Apps & Services tab and then click the GameCircle tab.
  2. In the Leaderboards column, click the View link for a game, and then click Bulk Add Leaderboards.
  3. Click Get Template to download a template file in CSV format. On your computer, save and rename the template to match the name of your game.

    The template has required and optional fields. The required fields are:

    • LeaderboardId
    • IconId The name of the image associated with a leaderboard. You enter iconId’s in the CSV file after uploading your leaderboard images.
    • SortOrder The only valid values are Highest Scores First and Lowest Scores First.

    • ScoreThreshold You do not need to enter data for ScoreThreshold, but do not delete the column. Score threshold is used to determine cheaters. Players with scores better than the threshold score are cheaters.
    • Title_en_US Columns with “en_US” cannot be deleted
    • Description_en_US Columns with “en_US” cannot be deleted
    • ScoreUnits_en_US Columns with “en_US” cannot be deleted

    The localized fields except for en_US are optional. They can be deleted it you do not want to provide translations.

    • Title_[locale] For example, Title_ru_RU
    • Description_[locale] For example, Description_de_DE
    • ScoreUnits_[locale] For example, ScoreUnits_it_IT

      Important: If you choose to delete language fields, you must delete all three localized fields. Upload will produce an error if you delete only one or two of these fields.

  4. Type your leaderboard metadata into the CSV file, or copy metadata into the file from an existing spreadsheet or other source.

    IMPORTANT: In Microsoft Excel, UTF-8 characters (such as Japanese or Chinese characters, or the tilde (~) used in Western languages) will be lost when exporting to a CSV file. As a workaround, use a program like Google Docs to export your data. If you have authored game metadata in Excel, you can import the Excel file into Google Docs and then export it as a CSV file with the proper encoding.

  5. Save the CSV file.
  6. When you are ready, return to the bulk upload page for your game and click Bulk Add Leaderboards. Navigate to the CSV file that you saved and then click Upload.

    If you find later that there are errors in your file, you can edit your CSV file and then re-upload it.

  7. On the Bulk Upload Progress Report screen, you will see the number of successful, failed, and skipped leaderboards, and also buttons for Upload More Leaderboards and View Leaderboards.

    Bulk Upload Progress Report

    Illustration 6: Bulk Upload Progress Report

    The popup window will display a progress bar and will list any errors that occur during upload. Errors at this step of the process should be rare. The two most likely errors are that an icon image was deleted on your computer between the original upload and clicking Submit, or that you have exceeded the maximum number of 50 leaderboards that can be posted in a game. If it is necessary, scroll down in the popup window to see the full list of errors.

  8. Review Your Leaderboards

    After submitting your leaderboard icons and metadata, review your leaderboards by navigating to your game in the developer portal and clicking the View link in the Leaderboards column.

When you click Submit and see the progress bar popup, you may see a message indicating that specific Leaderboards failed. Possible reasons include:

  • Invalid Icon IDs and exceeds max number of Leaderboards
  • Issues with reaching the GameCircle service
  • If there is a service error or the limit of leaderboards would be exceeded, then all remaining leaderboards will be skipped

Correcting minor errors

If it is necessary to correct an error, click Edit in the Actions column and make any corrections. After making any changes, click Save.

Note: If you have associated the wrong icon image with a leaderboard, click Select an Icon and select the correct icon from the gallery. See Using the Icon Gallery for further information.

Correcting errors in multiple leaderboards

If you wish to correct a large number of leaderboards, it may be faster to export your leaderboard data in a CSV file, make bulk corrections, and re-upload the CSV file by using the procedure above. To export your CSV file, navigate to your game and click the View link in the Leaderboards column. Then at the bottom of that page click Export Leaderboards.

Error Messages

When you select a file and click Upload, you see either a confirmation screen or an error screen. If you get a confirmation screen, you can click Submit to confirm the data.

You may see these types of errors on the Bulk Add Leaderboards screen:

  • Missing or unexpected headers
  • Lines that are invalid or are duplicates, or fields that are not valid (exceeds character limit, should be a number within a certain range, should be in enum options, etc.)
  • Icon IDs that are invalid (the iconId doesn’t exist)
  • File too large: More than the max of 50 leaderboards in a single file
  • Limit exceeded: This error is related to the “file too large” error. You will see this error if the leaderboards that want to add would cause there to be more than 50 leaderboards associated with your game.

Using the Icon Gallery

The Icon Gallery contains tools that you can use to upload and manage leaderboard and achievement icons. The default view for Icon Galley is View Gallery, which displays thumbnails of your uploaded icons, the IconID associated with the icon, and controls for deleting and replacing icons.

IMPORTANT: Exercise care in naming the images that you will use as leaderboard and achievement icons. Renaming icons requires multiple steps, and you will save time by naming images correctly before you upload them.

You can use these controls to perform icon operations:

  • Upload an Icon Can be used to upload a single image with an iconId that does not already exist. This operation will fail if the iconID already exists. Upload a New Icon page

    Illustration 7: Upload a New Icon page

    When you click the Upload an Icon tab, the Upload a New Icon screen opens. The screen displays a text box for entering a new iconID (up to 80 characters), and a Browse control to navigate to an image on your computer. When you have identified a new icon image, click Save. If the operation is successful, the Icon Gallery opens and displays your new icon. The GameCircle service converts the file name to an iconID.

  • Upload Multiple Icons Can be used to upload multiple image files in a single drag-and-drop operation. All images in an upload must have file names that do not already exist for the selected game. This operation will fail if an iconID in the upload already exists in the game.

    When you click the Upload Multiple Icons tab, a screen opens where you can drag-and-drop multiple images. After dragging your image files into the box, they will be displayed as thumbnails with file names; if you wish, you can change those names before uploading. The GameCircle service converts the file names to iconIDs.

    When you are ready, click Save. The Icon Gallery will open and display your new icons.

  • Delete You can use the Delete control to permanently remove an icon from the gallery, but you can do this only as long as the icon is not currently associated with a leaderboard or achievement. This operation will fail if the icon is associated with a leaderboard or achievement anywhere in your game.
  • Replace You can use the Replace control on existing image icons. Any existing leaderboards or achievements that use the image will also receive updated masked versions.

    When you click Replace, the Replace an Icon screen opens. The screen displays your existing icon and iconID, plus a Browse control to navigate to another image on your computer than can be substituted for the current icon. When you have identified the replacement image, click Save. If the replacement is successful, the Icon Gallery opens and displays your new icon.

Renaming an Icon

To rename an icon in the developer portal that is associated with a leaderboard or achievement, follow these steps:

  1. Re-upload the image to be renamed by using the Upload an Icon tab; if it is necessary, rename the image as part of the upload process.
  2. Navigate to the leaderboard that contains the icon that you want to rename. The Edit Leaderboard page opens.
  3. Click Select an Icon. On the Select an Icon screen, click on the image that you uploaded in Step 1.

    Note: If you do not see the new image, click Refresh Icons.

  4. The Edit Leaderboard page re-opens and displays your selected icon. Click Save.
  5. If you wish, navigate to the Icon Gallery and delete the icon with the name that you no longer want to use.

Step 2. 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.

Step 3. Add a Link to the Leaderboard Overlay in Your Game

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) {

Step 4. Test Leaderboards

To test your leaderboards, follow this procedure:

  1. Confirm that you have added test nicknames in the Amazon Mobile App Distribution portal. If it is necessary, add one or more test nicknames. Instructions for adding test nicknames are here.

  2. On your test device, sign in to your game by using a test nickname.

  3. Play your game so that you have score data.

    Optional: If you wish, sign in to your game by using more than one test nickname, and create score data for each player.

  4. In the Amazon Mobile App Distribution portal:

    1. Navigate to your game.

    2. Click the GameCircle tab.

    3. Click the Leaderboards tab to see your leaderboard data.

Step 5. Publish Leaderboards

To make leaderboards available for players, you must publish them.

  1. Sign in to your account on the Amazon Mobile App Distribution portal, and then click the Apps & Services tab.
  2. Click the GameCircle tab.
  3. In the Leaderboards column, click the View link for a game that has a draft leaderboard.
  4. In the Status column, select a leaderboard in Draft status. When the box is selected, the label will change to Ready to Publish. You can select as many draft leaderboards as you wish.

    Note: The default publishing experience is to show all languages. If you do not wish to publish all languages, de-select the check boxes for those languages. You should confirm at this point that your translated leaderboard names and descriptions (if any) appear correctly.

    Illustration 8: Start Publishing button location

  5. Click Start Publishing. Confirm that you want to publish, and all selected leaderboards will be published. Publishing your leaderboards makes them available to players after the game itself is published to an app store.

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 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.

Before Publishing, Associate Your Game with a Security Profile

After adding leaderboards or other GameCircle features to your game, you can submit the game to the Amazon mobile store.

Important: Most developers choose to have Amazon sign their applications. To enable this, you must associate a security profile with your game in the Amazon Mobile App Distribution Portal before submitting the game to Amazon for testing. Your game will not launch if you do not associate a security profile with your game before submitting it. The reason is that when Amazon signs your app, a new API key is generated that is linked to the security profile, rather than to the game.

Developers who followed the steps in Setting Up Your GameCircle Configuration already have a security profile that they can associate with their game.

For step-by-step instructions for associating your game with a security profile, see Publishing to the Amazon Mobile Store.

Best Practices

  • GameCircle displays the first leaderboard in your list on the front of the summary screen for players. Make sure that the first leaderboard has value to the overall game, rather than to a specific level or subsection.
  • Provide descriptions that make it obvious to which part of the game each leaderboard pertains.
  • Don’t immediately create all 50 possible leaderboards. You may want to create some new leaderboards later for future game extensions.
  • When creating your leaderboards, sort them in the overview list in the correct order. The order of leaderboards in the overview determines the order that customers will see them.
  • To change the order of leaderboards, open the Amazon Mobile App Distribution portal and navigate to the Leaderboards for your game. Hover your mouse pointer over the Position column of each leaderboard line item to reveal a handle that you can drag and drop to a new position in the column.
  • You can never delete a published leaderboard — deleting a leaderboard that is visible to your customers would be too disruptive to their experience — but you can modify a published leaderboard.

Take the Next Step: Add More GameCircle Features in Your Game

Now that you've integrated GameCircle leaderboards into your game, take the next step and add Achievements and Whispersync for Games (if you haven't done so already).

Return to the API overview

Unavailable During Maintenance