Implementing Achievements

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


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

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

Setting up achievements in your game requires these steps:

  1. Create a Draft Achievement
  2. Send an Achievement Update
  3. Add a Link to the Achievement Overlay in Your Game
  4. Test Achievements
  5. Publish Achievements

Metadata and Image Icon Requirements

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


Keep achievement names to 25 characters (text and spaces only) and descriptions to 68 characters (text and spaces only). Your game displays achievement names in multiple locations. Amazon will automatically shorten your text to fit the available UX space.

Provide two descriptions (which can be identical) for each achievement:

  • Pre-completion, such as “Reach X”
  • Completion, such as, “Reached X”
Achievement IDs

You will supply an achievement ID when submitting an achievement from your game code to your customers’ games. Achievement IDs can contain the letters A-Z (uppercase or lowercase), numbers, dashes, and underscores. Players don’t see achievement IDs.


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

Step 1. Create a Draft Achievement

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

There are two ways to add achievements to your game:

Option 1: Create a Single Achievement

Follow these steps to create a single draft achievement. 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.

  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 Achievements column, click the View link for a game.
  4. On the achievements page for your game, click Add an Achievement.

    Add a language

    Illustration 1: Add an Achievement page, showing one Published and two Draft achievements

  5. On the Add an Achievement page, enter the required information: Display Title, Achievement ID, Locked Description, Unlocked Description, and so forth.
  6. Use the radio buttons to choose whether the achievement will be hidden from users until they obtain it.
  7. In the Locked Icon Upload area, click Select an Icon to open the Select a Locked 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 achievement in its locked state, click Upload an Icon and navigate to an image on your computer. Follow the instructions to upload the image.
  8. In the Unlocked Icon Upload area, click Select an Icon to open the Select an Unlocked 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 achievement in its unlocked state, click Upload an Icon and navigate to an image on your computer. Follow the instructions to upload the image.

  9. Add an achievement user interface

    Illustration 2: Achievement metadata page

  10. When you are ready and all fields are complete, click Save.
  11. If you want to add achievement 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 achievement in English (en_US), and then edit the achievement by adding metadata in the selected language(s). GameCircle does not translate achievement metadata for you.

  1. On the achievements home page, click the Add a Language dropdown and select one of these languages:
    • English (U.K.)
    • German
    • French
    • Italian
    • Spanish
    • Japanese
    • Chinese
    • 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 achievement, on the achievement home page, in the language dropdown box, select the language you just added.

    Add a Language box

    Illustration 4: Language selection dropdown list

  4. Select an achievement to edit, and then click Edit 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 achievement adds metadata fields with placeholder text in English for the selected language(s) for all of your other achievements for that game. Before publishing your achievements, replace the placeholder text with the appropriate translations.

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

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

Option 2: Create Multiple Achievements

The GameCircle bulk upload feature enables you to upload up to 100 achievements in just a few steps. Use this procedure if you expect to display more than a handful of achievements in your game. Developers who plan to display achievements 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 achievements in one operation. You can upload additional achievement information and images later, as long as the total number never exceeds 100.

In the following workflow, you must upload your achievement icon images to the Amazon Mobile App Distribution portal before you upload your achievement metadata. 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 achievement icons and upload them to Amazon. If you wish, you can rename the 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 windows opens.

    Image upload window

    Illustration 5: Upload New Icons box

  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 achievement icons that you will use in your game. You will see thumbnails of your uploaded achievement 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 additional information about using the Icon Gallery, see:

Step 2: Using the CSV Template to Upload Achievement Metadata

After uploading your icon images, follow these steps to download a CSV template file and upload the metadata for multiple draft achievements:

  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 achievements column, click the View link for a game, and then click Bulk Add Achievements.
  3. In the Bulk Add Achievements window, you can download a sample CSV file that contains all of the correct header fields to use as a template for your achievements. To get the template, after "For a template CSV file," click click here. On your computer, save and rename the template to match the name of your game.

    All fields in the template are required except for foreign language fields (for example, LockedDescription_pt_PT). The required fields are:

    • achievementId The value of the achievement that you will use to access the achievement in your code. This value is not seen by game players.
    • unlockIconID The name of the image associated with an unlocked achievement. You enter unlockedIconID’s in the CSV file after uploading your achievement images.
    • lockedIconID The name of the image associated with a locked achievement. You enter lockedIconID’s in the CSV file after uploading your achievement images.
    • isHidden Value is always TRUE or FALSE. Represents whether an achievement is hidden.
    • DisplayTitle_en_US The title that will be shown to game players.
    • UnlockedDescription_en_US The description of an unlocked achievement that will be shown to game players.
    • lockedDescription_en_US The description of a locked achievement that will be shown to game players.
  4. Type achievement metadata into the CSV file, or copy metadata 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 achievements. Navigate to the CSV file that you saved and then click Upload.

    If there are no errors, click Submit If you find 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 achievements, and also buttons for Upload More Achievements and View Achievements.

    Bulk Upload Progress Report

    Illustration 6: Bulk Upload Progress Report

  8. 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 100 achievements that can be posted in a game. If it is necessary, scroll down in the popup window to see the full list of errors.

  9. Review Your Achievements

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

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

  • Invalid Icon IDs and exceeds max number of achievements
  • Issues with reaching the GameCircle service
  • If there is a service error or the limit of achievements would be exceeded, then all remaining achievements 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 an achievement, click Select an Icon and select the correct icon from the gallery. See Using the Icon Gallery for further information.

Correcting errors in multiple achievements

If you wish to correct a large number of achievements, it may be faster to export your achievement 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 achievements column. Then at the bottom of that page click Export Achievements.

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 Achievements 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 100 achievements in a single file
  • Limit exceeded: This error is related to the “file too large” error. You will see this error if the achievements that want to add would cause there to be more than 100 achievements associated with your game.

Using the Icon Gallery

The Icon Gallery contains tools that you can use to upload and manage achievement and leaderboard 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 achievement 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 if you leave the field empty.

  • 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 an achievement or leaderboard anywhere in your game.
  • Replace You can use the Replace control on existing image icons. Any existing achievements 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 an achievement or leaderboard, follow these steps:

  1. On your computer, rename the image file for the icon that you want to rename, and then upload the image by using the Upload an Icon tab.
  2. Navigate to the achievement that contains the icon that you want to rename. The Edit Achievement 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 Achievement 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 an Achievement Update

After initializing Amazon GameCircle in your game, you can submit achievement progress updates to the service.

// Replace YOUR_ACHIEVEMENT_ID with an actual achievement ID from your game.
AchievementsClient acClient = agsClient.getAchievementsClient();
AGResponseHandle<UpdateProgressResponse> handle = acClient.updateProgress(YOUR_ACHIEVEMENT_ID, 100.0f);
// Optional callback to receive notification of success/failure.
handle.setCallback(new AGResponseCallback<UpdateProgressResponse>() {
   public void onComplete(UpdateProgressResponse 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.

The second input parameter to the updateProgress method is a floating-point value representing the player’s completion percentage for the achievement. The valid range of this parameter is 0.0 to 100.0, where 0.0 represents fully locked and 100.0 represents fully unlocked. Completion percentage can only increase. If the method submits a completion percentage value that is lower than the current value, the completion percentage shown for that achievement will not change.

Step 3: Add a Link to the Achievement Overlay in Your Game

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

Button btnAchievementsOverlay;
btnOpenAchievementsOverlay.setOnClickListener(new OnClickListener() {

    public void onClick(View v) {

Step 4: Test Achievements

To test your achievements, play your game on your test device and verify that you can unlock the achievements that you've set.

  1. Confirm that you’ve 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 into your game by using a test nickname.
  3. Play your game and verify that you can unlock the achievements that you've set.

Step 5: Publish Achievements

To make achievements available to your customers, 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 Achievements column, click the View link for a game that has draft achievements.
  4. In the Status column, select an achievement in Draft status. When the box is selected, the label will change to Ready to Publish. You can select as many draft achievements 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 achievement names and descriptions (if any) appear correctly.

  5. At the bottom of the page, click Start Publishing. Confirm that you want to publish, and all selected achievements will be published.

Use a Handle to Control Game Flow While Downloading an Achievement Icon

AGResponseHandle<LoadIconResponse> loadIconHandle = acClient.loadIcon(YOUR_ACHIEVEMENT_ID, IconSize.LARGE, true, null);

public void loadIconHandler(AGResponseHandle<LoadIconResponse> loadIconHandle)
    while(loadIconHandle.getStatus() == AGHandleStatus.WAITING)
        // Show a spinner animation
    LoadIconResponse response = loadIconHandle.getResponse();
    if (response != null)
        byte[] image = response.getImage();
        // Do something with the image

Control Placement of Achievement Toasts

You can control the placement of achievement 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 achievements 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

  • Don’t immediately create all 100 possible achievements. You may want to create some new achievements later for future game extensions.
  • The order of achievements matters. GameCircle will display the next achievement that the player hasn’t completed as a suggested achievement to attempt, so list achievements in the order that players are likely to unlock them.
  • To change the order of achievements, open the Amazon Mobile App Distribution portal and navigate to the Achievements link for your game. Hover your mouse pointer over the Position column of each achievement 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 achievement — deleting an achievement that is visible to your customers would be too disruptive to their experience — but you can modify a published achievement.
  • Achievements motivate players to continue playing, but if players can't see an achievement or know what they need to do to accomplish it, the benefit is lost.
    • Provide descriptions that tell the player how to earn the achievement. Hints rather than explicit directions are fine, but the less information a player has, the less incentive they have to earn the achievement. Without instructions, reaching an achievement can feel like luck rather than skill.
    • Use hidden achievements sparingly and generally for things the player is going to accomplish in the normal course of play. Every achievement should have two descriptions. The first description is for when the achievement is locked. The second is for when it’s unlocked. Use the unlocked description to praise the player for success and explain what the player did to earn the achievement.
  • Use a different graphic for the locked and unlocked versions of achievements. The graphics should be similar, but have a common element that differentiates locked from unlocked achievements. For example, use greyscale or a different color background for the locked versions of graphics. This enables players to distinguish earned achievements easily when doing side-by-side comparisons with other players.
  • Place achievements throughout the game. Let the player earn their first achievements by completing the tutorial or early levels, earn other achievements as they progress through the normal course of play, and have an achievement for completing the game.
  • Offer a good mix of difficulties for unlocking achievements. Players should earn a few achievements relatively easily, but having a few achievements that require significant skill or effort will encourage replay and reward completionists.

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

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

Return to the API overview

Unavailable During Maintenance