Home > Services & APIs > Engage > GameCircle

How Does Amazon GameCircle Work?

Introduction

Introduction

Amazon GameCircle is a mobile development platform that provides support for achievements, leaderboards, and Whispersync for Games. It works both offline and online, synchronizing content the next time a player goes online.

To use Amazon GameCircle, integrate the Amazon GameCircle libraries into your game, configure achievement and leaderboard assets using the GameCircle tab of the Developer Console, and test and publish your achievement and leaderboards assets. Then publish your game in a distribution portal such as Amazon Appstore.

Amazon GameCircle is supported on Android and Fire OS.

Whispersync for Games

Whispersync for Games is the first cross-platform data-syncing solution to automatically resolve conflicts and handle all the complexity and corner cases of syncing for you, such as offline and simultaneous game use. To use Whispersync for Games, save your game data using the Whispersync for Games API. When you do, you can either let Whispersync for Games automatically manage persistence and cloud synchronization for you, or have your game take full control and manage conflict resolution. Using Whispersync for Games is as easy as using SharedPreferences or saving to a file. This lets you spend more time building games players love and less time managing data.

Whispersync for Games leverages the power of Amazon Web Services to store data in the cloud, where it is stored securely and can be synchronized any time an internet connection is available. Because Whispersync for Games stores a copy of the synchronized data on your player’s device, data managed by Whispersync for Games is always available regardless of whether your player is connected to the internet or offline.

Your game simply retrieves values from the local data store. In the background, Whispersync for Games automatically synchronizes the data and resolves any conflict arising from offline and simultaneous game use. Whispersync for Games supports multiple devices and platforms, meaning that it keeps your data in sync when shifting between Android or Amazon Fire devices.

Whispersync for Games is similar in function to Whispersync for Kindle, which synchronizes the farthest point read in a book when you switch between Kindle devices and apps. Whispersync for Games, however, is a separate implementation with special error handling for many data types.

Achievements

Achievements are rewards that players earn in your game. When properly designed, they increase player retention and engagement by spurring them to spend more time in the game in order to earn the next achievement. Once a user earns an achievement, it becomes part of their profile.

On Fire tablets, achievements for all games that integrate Amazon GameCircle are displayed in the Games library and achievements for an individual game are displayed by the user interface of that game. On Android devices, achievements are integrated into a game’s user interface, and there is no integrated view of achievements across multiple games.

You define achievements for your game in the GameCircle panel of the Amazon Apps & Games Developer Portal, enter metadata associated with that achievement and upload the images to display for that achievement. When a player performs an action that earns them an achievement, your game calls Amazon GameCircle to award that achievement to the player.

Amazon GameCircle collects metrics on those achievements, such as progress and completion rates across your players. You can use achievement metrics to better understand your players and how they interact with your game.

Amazon GameCircle collects achievement metrics whether or not the player is online while they are playing the game. When they next connect to the Internet, any achievement data is synchronized with the Amazon GameCircle service.

Leaderboards

Leaderboards display a ranked list of player scores. When designed properly, they can increase player engagement by creating competition between players and opportunities for advancement. This encourages them to play longer to improve their score. It can also extend the audience of your game, as players encourage their friends to play the game so they can be ranked against people they know.

On Fire tablets, leaderboards for all games that integrate Amazon GameCircle are displayed in the Games library and leaderboards for an individual game are displayed by the user interface of that game. On Android devices, leaderboards are displayed only by the user interface of the game and there is no integrated view of leaderboards across multiple games.

You define leaderboards for your game in the GameCircle panel of the Amazon Apps & Games Developer Portal, enter metadata associated with that leaderboard and upload the images to display in the background of that leaderboard. When a player earns a score, your game calls Amazon GameCircle to record the score and Amazon GameCircle adjusts the leaderboard rankings accordingly.

GameCircle Friends

With the GameCircle social APIs, you can add GameCircle friends data to your game for players who use Amazon devices. Players using Amazon devices are able to create a profile for themselves, including a nickname and profile image, and can add other GameCircle players to their friends list. You can access this data and display it in your own games or use it to leverage custom social interaction features.

These social APIs are available in the following client libraries: Java, C# (for Unity), and C++ (JNI), and support Amazon and Android devices. You can also get scores and percentile ranks for friends using the ActionScript APIs for Adobe AIR.

For more on how to integrate GameCircle friends data into your games, see Adding GameCircle Social Features.

Game Configuration

In the Amazon GameCircle Developer Console, you’ll register your game with GameCircle and configure GameCircle service settings for the game. The configuration identifies and describes your game to GameCircle and defines the GameCircle experience shown to your players. Setting up a configuration involves five steps in which you’ll describe your game, generate a unique identifier, set up achievements and leaderboards, and specify one or more test accounts.

The unique identifier (in the form of an API key) needs to be referenced in your game APK. Amazon checks the API key to ensure that the game is the original version, and has not been altered since you published it. This is also what enables the GameCircle service to serve up the right achievements and leaderboards and sync the correct gameplay data when requested by your game.

Once your game is published to the world, you’ll continue to use the Developer Console to create new achievements and leaderboards, work on them in draft mode and then push them live when ready. This gives you the flexibility to add new elements without having to update and redeploy your game. You’ll also retrieve achievement reports by configuration.

Shared Configurations

If you’ve created multiple versions of your game, such as free vs. paid, localized, or device-specific versions, then you need to decide whether or not you want leaderboards, achievements, and synchronized data to be shared across those multiple versions. All versions referencing the same configuration (API key) are shared.

With a shared configuration, players of your game get a consistent GameCircle experience regardless of which version they happen to be playing—they see the same achievements and leaderboards, and player progress is sync’d across devices. Game leaderboards combine and rank all players regardless of version. In contrast, you can publish different GameCircle experiences for certain versions by creating separate configurations instead of sharing. For example, with versions that have special game play elements, you may want a different set of achievements. If a certain device offers significantly improved performance, you might want to set up special leaderboards.

Test Accounts

Setting up a test account lets you test draft achievements and leaderboards to verify that they display and are awarded properly. In the GameCircle configuration, you’ll designate special profile names to use as test accounts. When you do, players with those profile names are able to view and use draft achievements and leaderboards as if they were published.

How Do I Add Amazon GameCircle to My Game?

Prepare to Use Amazon GameCircle

Before you can add Amazon GameCircle to your game, there are some preliminary things you must do, such as create an Amazon developer account, download the Amazon Apps & Games Services SDKs, and create art assets. Most of these tasks only need to be done the first time you use Amazon GameCircle in an app. For more information, see Get Set Up for GameCircle.

Integrate Amazon GameCircle Features into your game

To synchronize data, report a score, or award an achievement to a player, your game communicates with the Amazon GameCircle service.

The Amazon Apps & Games Services SDKs contain libraries and game engine plugins you can use to call Amazon GameCircle from your game. For more information, see Integrate GameCircle Into Your Game. For a full list of the game engines, platforms, and programming languages supported by Amazon GameCircle, see “Tools for Amazon GameCircle” later in this page.

Add an Amazon GameCircle Configuration

A GameCircle configuration is how you register your game with GameCircle and set up features, including leaderboards and achievements, for your game. Sign in to the Developer Console and go to the Apps & Services > GameCircle tab to create a GameCircle configuration. During the configuration process, you’ll configure app security settings, define achievements and leaderboards and upload icon images for them, and set up test accounts for your game’s GameCircle features. For more information, see Create a GameCircle Configuration.

Test Your Amazon GameCircle Configuration

When you first create achievements and leaderboards, they are in a draft state. This gives you an opportunity to test them in your game before publishing them to players. To do so, create test accounts. Only players using test accounts can earn draft achievements and rank on draft leaderboards. For more information, see Test Your Game.

Publish Draft Achievements and Leaderboards

After you have finished testing your leaderboards and achievements in the draft state, you must publish them to make them available by players. Until you do, players who are not using test accounts will not be able to earn the achievements or rank on the leaderboards.

After you’ve integrated Amazon GameCircle into your game, configured the assets Amazon GameCircle should display for your game, and tested your game, the final step is to publish your achievements, leaderboards, and game and get it into the hands of players. For more information, see Publish Your Game.

Publish your game

There are three main mobile app distribution portals you can use to publicize and distribute your game: the Amazon AppStore, Apple App Store, and Google Play. For more information, see Publish Your Game.

What Devices and Platforms Does Amazon GameCircle Support?

Amazon GameCircle runs on the following devices and platforms.

Platform Supported Versions


Android Android 2.3.3 (API 10) or later.
Fire Tablet

GameCircle runs on the following Fire tablets.

  • Fire HDX 8.9, Fire HD 7, and Fire HD 6 (4th Generation), based on Android 4.4.2 (Kit Kat), API level 19.

  • Kindle Fire HDX 8.9” and Kindle Fire HDX 7” (3rd Generation), 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", based on Android 4.0.3 (Ice Cream Sandwich), API level 15.

  • Kindle Fire (1st Generation), 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 more information, see Adding Platforms and Packages.

For more information about supported API levels, services, and features, see Migrating an Existing App to the Amazon Appstore.

Tools for Amazon GameCircle

Game Engine Plugins

Amazon GameCircle provides plugins and instructions for integrating Amazon GameCircle into the following game engines. These plugins are available for download as part of the Amazon Apps & Games Services SDK.

Game Engine Plug In Location in the Amazon Apps & Games Services SDKs
Unity Amazon GameCircle Unity Plug-In Unity/GameCircle/
Corona Corona GameCircle Plug-In Available as part of the Corona SDK
Cocos2DX Amazon GameCircle JNI API (C++) Android/GameCircle/GameCircleSDK/jni
Adobe AIR Amazon GameCircle Adobe AIR ANE (Native Extension) AIR/GameCircle/

Software Development Kits

Amazon GameCircle provides SDK libraries for integrating Amazon GameCircle into your game. These are available for the following programming languages. These SDKs are available for download as part of the Amazon Apps & Games Services SDKs.

Language SDK Location in the Amazon Apps & Games Services SDKs
Java Amazon GameCircle SDK for Android Amazon-Android-SDKs/AmazonGameCircle/GameCircleSDK
C++ Amazon GameCircle JNI API (C++) Android/GameCircle/GameCircleSDK/jni

Amazon GameCircle Console

The GameCircle panel of the Amazon Apps & Games Developer Portal is a web-based user interface you can use to upload assets and specify your Amazon GameCircle configuration. Using the console, you can create leaderboards and achievements, manage test accounts, and publish your leaderboards and achievements.