Tips and Best Practices for the Amazon GameCircle API - Amazon Mobile App Distribution Blog

Tips and Best Practices for the Amazon GameCircle API

Not familiar with Amazon GameCircle? Read how easy it is to add achievements, leaderboards, and save-to-cloud features to your next game.

From a game developer's perspective, the Amazon GameCircle API offers a lot of advantages over home-grown achievements and leaderboards, not to mention data synchronization to the cloud or between devices. It instantly provides a social aspect to your game with very little coding, and simplifies progress saving and back-up (two of the features most requested by customers).

GameCircle isn't just about developer convenience, though--customer experience is also critical. We see again and again how integrating GameCircle improves user engagement and conversion, so we know it provides value to game players as well as game developers. More engagement and better conversion leads to increased average revenue per user, so GameCircle may add directly to your bottom line.

With this in mind, we've developed a few guidelines to help maximize GameCircle's contribution to your game. These best practices have grown out of our own experience, as well as those of other developers with successful games using GameCircle. If they seem like common sense ways to make the user experience better, you're right.


Order – Keep in mind that the first leaderboard listed for your game will be the one to appear on the GameCircle summary screen. Give that slot to a leaderboard that will provide useful information game-wide, as opposed to a specific level or section. The Amazon Mobile App Distribution Portal supports drag-and-drop ordering of leaderboards, so making changes is easy.

Descriptions – It seems obvious, but each leaderboard should have a description, making it clear to the player what is being tracked.

Draft/sandbox – Remember that leaderboards (and achievements, too) are considered "draft" until they're published from the Distribution Portal. Only players who have been added to the GameCircle sandbox for your app can view unpublished leaderboards or post scores to them. When you're ready to make the leaderboard publicly available, check the appropriate Status box to mark it Ready to Publish, then click Start Publishing.

Note that this step cannot be undone, as un-publishing a live leaderboard might lead to a poor user experience if an app expects a leaderboard to be available. However, after publishing a leaderboard, you'll still be able to reset a leaderboard's high scores from the Distribution Portal, which may be useful for weekly quests or contests.

Multiple game support – You can easily share one set of leaderboards (and achievements) with multiple versions of your game. If you release separate Free and Paid versions, or offer Standard and High Definition variations of your game, choose one version of your game to be identified as the "master," and then create your leaderboards and achievements for that version only. Then just add the package/signature pair of each version that will use the shared leaderboards and achievements to the “master” whitelist registry.


Order – GameCircle automatically shows users the next locked achievement, encouraging them to keep on playing. Arrange achievements in the order they're likely to be earned and they'll be recommended in the same order and the progression will seem natural. Like leaderboards, achievements may be reordered on the Distribution Portal using its simple drag-and-drop interface.

Descriptions – Like leaderboards, achievements should have clear descriptions so players know what they're striving for. You don't have to lay out the precise steps to earn each achievement—hints or a simple phrase are fine—but keep in mind that a rich description may provide more incentive to unlock the achievement. If the description is too vague, earning it may feel like luck rather than skill.

Locked/unlocked descriptions and icons – GameCircle allows you to specify different text and icons for locked and unlocked versions of each achievement. Adjust the description for an earned achievement to describe what was done or to congratulate the player. For example, "Defeat the Spider King" may describe an achievement until it's unlocked, after which "You Killed the Spider King!" might be more appropriate.

Similarly, the images should be noticeably different. Color is a good mechanism to indicate lock status, with neutral or gray-scale imagery signifying an achievement not yet earned. Other options include different backgrounds, an overlay or watermark, or a common image shared by all locked achievements (with an achievement-specific icon for the unlocked state).

Use hidden achievements sparingly – GameCircle supports "hidden" achievements, which are not visible to the player until actually earned. Since the user doesn't know about them (let alone how to earn them), hidden achievements are best used for incidental progress—things that might happen through ordinary game play, requiring no specific effort. If your game's achievements are all earned through special actions, you should probably avoid hiding them.

Mix up the difficulty – If all the achievements in your game are easy to earn, users may do so quickly and be less likely to keep playing. If the achievements are all hard, there may not be enough regular rewards to keep players coming back. A mix of easy and hard achievements delivers positive reinforcement while rewarding those who put in the extra effort to complete them all.

Likewise, you may wish to alternate between incidental rewards and ones that require complicated actions or special effort. As with hidden achievements, this depends on your philosophy—some developers prefer not to define achievements that are awarded through the course of normal game play. If you do choose to include incidental rewards, maintain a balance by offering complex achievements, too.

Pace achievements throughout the game – An achievement early on (completing a tutorial, for instance) should kick off a steady flow of positive feedback throughout the game, leading to a final achievement at completion (if appropriate).

Draft/sandbox – Like leaderboards, achievements are created in "draft" mode by default. This means that they're only visible to players who have been added to your game's sandbox via the Distribution Portal. The process for publishing an achievement is identical to that for a leaderboard, and is also irreversible, for similar reasons.

Note that unlike leaderboards, achievements cannot be reset once they're published. Until then, the Distribution Portal can be used to clear an achievement from all users in the sandbox, but that option disappears once the achievement becomes publicly available.

Multiple game support – See the note under Leaderboards, above.

Whispersync For Games

First sync on a fresh device – The very first time your game is run on a fresh device, there will be no local saved data; the game should simply copy down whatever cloud data exists for the user. To do this, call synchronize() with a conflict resolution strategy of AUTO_RESOLVE_TO_CLOUD (the default, PLAYER_SELECT, will prompt the user to choose between device and cloud—obviously not appropriate in this situation.)

First sync of the game – Every time your game starts (except on a brand new device—see above), you should call synchronize(). The latest cloud data will be retrieved, if appropriate, or updated, if a local data change is pending. If the data conflicts, the user will be prompted to choose the authoritative source.

Sync at major checkpoints, pause, and exit – Whenever a player reaches a significant milestone or stopping point in your game, you should save state to the cloud with synchronizeProgress().

Sync description – It's critical to associate a useful description with each progress update, since this information will be presented to the user in the case of a conflict, or if you allow them to restore to a save point. GameCircle will include the date and time automatically, but a friendly description such as, "Completed Level 3," or, "Round 7: 12 minutes in," can help the player choose which data they want to use.

Virtual goods – If you store entitlements locally (that is, you don't handle virtual goods through an authoritative server), it's important to either exclude this data from Whispersync updates or disallow save points. If you don't, a restore to an earlier save point may wipe out your customer's purchases—a guaranteed way to generate complaints.


CANNOT_BIND from the emulator – Remember that GameCircle works only on registered Kindle devices, including emulators. If you encounter this error while running on the emulator, make sure you have actually registered and signed in from there as well. You can do this from Settings | My Account.

This problem can also arise if the Target is incorrect for the Android Virtual Device you are using. It should start with "Kindle Fire…" to ensure Amazon functionality is available.

Don't forget to publish Achievements/Leaderboards – This is a very common oversight, but fortunately simple to correct. Be sure to publish your achievements and leaderboards using the Distribution Portal once your game is ready be made publicly available.

Game alias only available if corresponding setting is enabled – If you are unable to retrieve the GameCircle alias/nickname when testing, make sure the appropriate setting is enabled. This is accessible from Applications | Amazon GameCircle. "Share your GameCircle Nickname" should be set to Show.

CANNOT_AUTHORIZE due to app signature – Note that on most platforms, the keytool command line program will silently accept the wrong password when generating a keystore signature. In some circumstances, you may need to run the command in the same directory as the keystore you are processing. See Authenticate Your Game with Amazon GameCircle for more information.

NoClassDefFoundError at runtime – If your application links without errors but throws this exception at runtime, ensure that the amazon-gamecircle-1.2.x.jar is actually included in the .apk. Simply adding the jar file to the build path is not necessarily sufficient. In Eclipse, for example, you may need to add the file or create a link to it in /libs.

No negative leaderboard values – Leaderboards do not currently support negative scores, so you will experience errors if you submit them.

Javadoc errata

·       FRIENDS_ALL_TIME is not currently a valid LeaderBoardFilter value

·       AchievementsClient.resetAchievement() and its plural counterpart do nothing