Amazon GameCircle API Frequently Asked Questions


This page lists Frequently Asked Questions (FAQs) and answers for GameCircle.

General Questions

Q: What is Amazon GameCircle?
Amazon GameCircle is a set of services for game developers that enable them to add features to increase customer engagement such as leaderboards, achievements, and Whispersync for Games to their games. These services can be added to games played on Fire tablets, earlier Kindle devices and generic Android devices.
Q: Is there a charge for developers to use GameCircle?
At this time, GameCircle services are free.
Q: Which game platforms does GameCircle support?
Android and Fire OS.
Q: Which version of GameCircle system application is required on Fire tablets in order to use GameCircle SDK 2.2?
Version 2.5.2500310. The current version can be determined by navigating to Settings > Apps > All > Amazon GameCircle.

If your Fire tablet shows an earlier version of Amazon GameCircle, follow these steps to upgrade:

  1. Ensure the device is charged to at least 40%.
  2. Swipe down from the top of the screen to display the notification bar.
  3. Touch Sync.
  4. Leave your device turned on but idle.
Q: How will customers be able to view leaderboards and achievements?
Add links to your game to enable players to view their leaderboards and achievements. Refer to the gamecircle/leaderboards and gamecircle/achievements documentation for more information on how to set it up.
Q: Should I remove testing data from my leaderboards and achievements before my game goes live?
Yes. We recommend clearing out all user data from leaderboards and achievements just prior to launch so that customers start with a clean slate. You can only clear data while a leaderboard or achievement is in a draft state, so it's good practice to make clearing the data and then publishing the achievements or leaderboards a part of your live submission process.
Q: Will Amazon GameCircle work on any Android device?
GameCircle API 2.1 or API 2.2 enable developers to incorporate leaderboards, achievements, and Whispersync for Games into games that will run on Fire tablets and on generic Android devices that meet minimum system requirements. Developers who choose to do so can update GameCircle apps built by using an earlier version of the GameCircle API to use the latest GameCircle API. For detailed information about the features supported in each version of the GameCircle API, see GameCircle API Version Information.
Q: What are the system requirements for GameCircle games?
Fire HDX 8.9, Fire HD 7, Fire HD 6 (4th Generation) are based on Android 4.4.2 (Kit Kat), API level 19. Kindle Fire HDX 8.9" and Kindle Fire HDX 7" (3rd Generation) are based on Android 4.2.2 (Jelly Bean), API level 17. Kindle Fire (2nd Generation), Kindle Fire HD 7", and Kindle Fire HD 8.9" are based on Android 4.0.3 (Ice Cream Sandwich), API level 15. Kindle Fire (1st Generation) is based on Android 2.3.3 (Gingerbread), API level 10.

The Fire tablets support all earlier versions of the Android SDK, but we recommend that you set a minimum API level of 10 to ensure compatibility with all Fire tablets. GameCircle currently supports up to API level 16 on non-Amazon devices and will continue to update for newer versions. For additional information about supported API levels, services, and features, see Migrating an Existing App to the Amazon Appstore. For information about specifying API levels in your app, see Specify Minimum and Target API Levels in the Android training guide topic Supporting Different Platform Versions.

Q: Which countries does Amazon GameCircle support?
Amazon GameCircle is available in more than 200 countries, including the United States, the United Kingdom (England, Scotland, Wales, and Northern Ireland), Germany, France, Spain, Italy, Japan, and Brazil. In China and other non-supported countries, your customers can earn achievements and track their high scores without logging in; the data is stored locally and not synced to the cloud.
Q: Can I localize my achievements and leaderboards?
GameCircle provides a mechanism to display translated versions of your achievements and leaderboards in UK English, French, Spanish, Chinese, German, Italian, Japanese and Portuguese. Your players must have the language set on their device, and you must provide the translated description strings. For more information see GameCircle Leaderboards and Achievements Now Support Multiple Languages, Bulk Upload.
Q: I have a question about implementing GameCircle that isn't answered here. How I can get additional help?
Check the GameCircle documentation and GameCircle forums to see if your question has already been answered. You can post a thread there if it hasn't, or contact us directly with your question.
Q: How can I handle null results from getScore() and getLeaderboards() when offline?
GameCircle callbacks for getScore() and getLeaderboards() do not return errors in offline mode, but the returned data will be null. To avoid NullPointerException-type errors, developers should check returned data for null before use.


Q: How do I create leaderboards for my game?
See "Step 4: Add Leaderboards" on Create a GameCircle Configuration.
Q: How do I clear a leaderboard?
You can only clear data from a leaderboard that is in a draft state. Once it has been published, the data cannot be reset. In the developer portal, select the draft leaderboard you wish to reset, click Edit, and then click Reset Score. Refer to "Reset Leaderboard Data" section of Using GameCircle Testing Features for more information.
Q: How do I delete a leaderboard?
You can't delete a leaderboard yourself. Please contact us< with the name of the game and the leaderboard, and we'll delete it for you.
Q: How do leaderboard time filters work?
GameCircle leaderboards come with three time filters 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.


Q: How do I create achievements for my game?
See "Step 3: Add Achievements" on Create a GameCircle Configuration.
Q: How do I delete an achievement?
You can only delete an achievement that is in a draft state. In the developer portal, select the draft achievement you wish to reset, click the Edit button, and then click Delete. Refer to the "Delete an Achievement" section of Using GameCircle Testing Features for more information.

Whispersync for Games 2.2

Q: How does Whispersync for Games 2.2 work?
Whispersync for Games enables you to get and set values in a data map.
  • Active sync events occur when you call the synchronize() method, and when a customer signs in to your game. However, syncing occurs even if you never call the synchronize() method, due to passive sync events.
  • Passive sync events occur any time that you choose to change game data, such as by setting a high score or accumulating number. Passive sync events are batched, rather than synced immediately. Whispersync throttles passive sync events to conserve network bandwidth and battery life.
  • Whispersync easily manages offline scenarios involving mergeable data types.
  • You can model both simple and complex game data by using Whispersync’s syncable data types, and, if necessary, by nesting data maps.
  • You can test your Whispersync for Games implementation by using a single test device. Whispersync doesn’t require nickname whitelisting. If the game is registered, Whispersync will work.
Q: What kinds of data can't be synced?
If a player creates data on multiple devices that can't be merged, Whispersync can't sync it. For example, say that a player starts a chess match on an online device, and then continues playing the game on two offline devices. The player will almost certainly make different moves on each offline device. When the two offline devices later go online, the individual moves and final game piece positions can’t be synced among the three devices. No code that you write can resolve the conflicts among the games.

Achievement Reports

Q: Which version of the GameCircle API is required to support Achievement Reports?
The lowest version of the GameCircle API that supports Achievement Reports is API 2.1 (September 2013) for Fire OS and Android.
Q: Which app or apps are included in my GameCircle Achievement Reports?
Each Achievement Report includes all of the apps associated with the security profile that you selected.
Q: How frequently is the data for GameCircle Achievement Reports updated?
Achievement Reports are continuously updated and include results for the most recent completed day in GMT. However, data uploads from an individual device may be delayed for reasons including offline play, low battery, and data conservation.
Q: Do Achievement Reports include data from both GameCircle and Guest accounts?
Yes. Achievement data from users with GameCircle accounts is collected across devices. Achievement data from Guest accounts is tracked separately for each device.
Q: Should I expect consistency between Engagement Reports and Achievement Reports?
You should not expect consistency between the two reports. GameCircle Achievement reports can include multiple apps and platforms, and report on accounts and devices. Engagement Reports only include apps distributed through our Amazon store, and report on devices only.
Q: What are the metrics in the "Unlocked Averages" section of the Achievement Reports?
Here are the metrics you will see:
  • Play Time (min): The average total of in-game play time required to complete the achievement.
  • Sessions: The average number of play sessions required to complete the achievement.
  • True Time: The average real-world time between when customers first play the game and when the achievement is completed.


Q: I am developing in Java (not using JNI) and am getting E/AGSJniHandler errors. Can I ignore these errors?
You can safely ignore these E/AGSJniHandler errors, which will be silenced in a future release:
  • E/AGSJniHandler(12653): Could not load AmazonGamesJni
  • E/AGSJniHandler(12653): java.lang.UnsatisfiedLinkError: Couldn't load AmazonGamesJni from loader


Q: Can I reorganize and move the GameCircle Unity plugin files?
No. Unity uses many special folder names as a part of its build process. Moving files will likely result in GameCircle causing build errors.
Q: How do I fix this error: "Exception: JNI: Init'd AndroidJavaClass with null ptr!"
This error occurs when files in the GameCircle Unity plugin have been moved from their original folders. Verify that all plugin Java archive files in Assets\Plugins\Android (gcunity.jar, gamecirclesdk.jar, AmazonInsights-android-sdk.jar, login-with-amazon-sdk.jar), and the other GameCircle files are in the correct locations. Re-importing the GameCircle Unity package can help you identify and resolve missing or moved files.

Developer Console

Q: How do I get an API key for my iOS game?
This function has been moved out of GameCircle for iOS. You can get an API key for any GameCircle app by going to the Security Profiles tab of the Developer Console. Select the security profile for your game (it has the same name as your GameCircle configuration), and select the iOS Settings tab. You can either get an existing key or generate a new one. To generate a new API key, fill in the Application Key namd and Bundle ID.
  • Application Key Name. This can be any name you want. Key names must be unique within a security profile.
  • Bundle ID. This is the name of the package or bundle that contains the code and resource files of your iOS game. For more information about bundles, see Code Signing or About Bundles in the Bundle Programming Guide provided by Apple. Keep in mind that package/bundle names in GameCircle configurations cannot be duplicated.
Q: Why did my internationalized text not upload correctly into GameCircle?
Are you bulk uploading achievements or leaderboards with multiple languages into your GameCircle configuration and seeing question marks (�) where you should be seeing international characters? Chances are the file you uploaded wasn’t properly encoded. GameCircle supports the following encoding:
  • UTF-8 without byte order mark (BOM)
  • UTF-8 with BOM
  • UTF-16 with BOM

Using the wrong encoding can happen even if you downloaded the template CSV file, if you edited and saved the file using an application that applies a non-supported encoding. To solve this problem, use a tool (such as UltraEdit) that allows you to specify exactly the type of encoding and BOM you want. You can manually edit your content in the GameCircle Developer Console to include international characters.

Q: Why did my GameCircle configuration disappear or change names? OR
Why did my game name change/not change in GameCircle?
If you’re seeing unexpected behavior related to the name of your GameCircle configuration or game name, this is probably caused by changes to an Amazon security profile made outside of the GameCircle configuration workflow. Most developers using GameCircle will never need to do anything with security profiles. But if your game has any association with non-GameCircle apps registered in the Amazon AppStore, one of the following conflicts may happen:
  • If it looks like your GameCircle configuration has disappeared, it’s possible the name was changed inadvertently. A GameCircle configuration name is always the same as the security profile it’s linked to, so if the security profile name is changed outside of GameCircle, the GameCircle configuration name also changes. Look for your missing configuration under a new name. Note: once you open the configuration under its new name and save it, your game name (as shown to players in the GameCircle UI) will also change to the new name.
  • If the name of your game, as shown to players in the GameCircle UI, isn’t what you expect, it’s likely because of a security profile change outside of GameCircle. When you change a security profile name, it automatically syncs the GameCircle configuration name, but does not sync the game name in the GameCircle UI. There’s a quick fix for this: open the configuration in GameCircle and save it under its new name.
Q: Why do I get a duplicate package error when trying to generate an API key for my game?
When generating a new API key for your Android or Kindle game, you will get this error if you enter a package name that is already being used in another GameCircle configuration. To resolve this issue, you need to change the package name for your game. Using a more specific package name will help avoid this error.

Amazon GameCircle now requires that package names be unique to a GameCircle configuration. This requirement ensures that GameCircle can continue to support shared configurations (multiple game versions using the same leaderboards & achievements) and avoid returning ambiguous game data.

Q: Why did the bulk uploader not recognize or incorrectly read my CSV file?
This is likely a case where your CSV file is using an encoding type not recognized by the GameCircle bulk uploader. Use a text editor such as UltraEdit to specify the exact type of encoding when saving the file. GameCircle recognizes the following encoding:
  • UTF-8 without byte order mark (BOM)
  • UTF-8 with BOM
  • UTF-16 with BOM

Known issue: The following known issue causes the GameCircle bulk uploader to incorrectly parse a UTF-16 file. If you open and save a UTF-16 file in Microsoft Excel, Excel automatically converts the file to UTF-8 but retains the UTF-16 BOM. As a result, the GameCircle bulk uploader incorrectly reads the file as UTF-16. A simple fix is to open the file in Notepad and save it as UTF-16BE ("Unicode big endian").

Fire TV and Fire Phone

Q: Why doesn't the GameCircle summary overlay for my game display when I push the beach ball button on my Fire TV controller?
This experience happens only if you install your game on a Fire TV device via file transfer (sideloading) rather than downloading it through the Amazon AppStore. In this scenario, Fire TV doesn't recognize that the game is GameCircle-enabled, so it displays the screen shown for non-GameCircle games. This issue does not affect your game's ability to display the overlay via an API call (such as with showAchievementsOverlay()), and is not a factor with the beach ball soft key on Fire tablet devices. Players who install your game through the AppStore will see the correct GameCircle overlay.

You can verify that the problem doesn't affect games download from the AppStore by testing your game with Live App Testing. This new tool lets you do real-world testing before your game goes live, including distributing your app via the Amazon AppStore to a limited set of testers and testing against all Android and Amazon devices, including Fire TV and Fire phone.

Note: You'll also get the non-GameCircle screen if you haven't yet published any leaderboards or achievements AND you're not using a test account. In this scenario, you would get the non-GameCircle screen in response to API calls and on Fire tablet devices as well Fire TV. To resolve this issue, publish at least one achievement or leaderboard in the Amazon Developer Console. Alternatively, set up a test account (also in the Developer Console), and use it to view draft achievements and leaderboards in the GameCircle overlay.

Adobe AIR

Q: Why won't my AIR project with GameCircle initialize?
If you're getting a CANNOT_INITIALIZE error when running your GameCircle enabled AIR app, it may be that you haven't included the "air." prefix to your application ID:
  • In your application descriptor, the value of android:host must be "air.".
  • When you generate API keys for your app in the GameCircle Developer Console, your package name/bundle ID must also include this prefix.

See Build & Test your AIR App: Add Your API Key File for more details.