We recently released an update to the Amazon Mobile App SDK that includes improvements to GameCircle and some related components on both Android and iOS. It updates GameCircle’s dependency on the latest version of Amazon Insights, corrects a few bugs, and expands API coverage of the Unity3D plug-in. For all of these reasons, we recommend migrating to the latest SDK when convenient.

Both GameCircle and its Unity3D plug-in now take advantage of the latest version of Insights, part of Amazon’s Analytics service and the piece responsible for generating Achievements Reports. Insights SDK on iOS removed a dependency on CoreTelephony.framework, while the Android version corrected an issue specific to certain device Locales and improved support for other IAP frameworks. In addition, session timeouts now behave more consistently across platforms.

GameCircle initialization has also been optimized on both iOS and Android, and GameCircle now ensures that its Javascript components are updated when migrating to a new version of the SDK. The Unity3D plug-in supports the latest Whispersync for Games syncable type, DeveloperString, which should make it easier to store arbitrary, non-mergeable game data from your Unity3D game. The plug-in also exposes the ability to show the GameCircle sign-in page.

Check out these latest changes to the SDK, and watch this space or future updates. We’re always working to improve performance, usability, and reliability of our services for mobile apps and games.

Amid all the hoopla around GameCircle’s expansion to iOS and a major update to Whispersync for Games, you may not have noticed two other powerful features were also released recently. The GameCircle team quietly added support for bulk creation of leaderboards and achievements on the Mobile App Distribution Portal, as well as the ability to internationalize them in up to eight languages besides US English. Both have been popular feature requests.

Internationalization means that GameCircle will display the title and description of your leaderboard or achievement in the language appropriate to your player’s locale, provided they have specified it in their mobile device settings. You can provide translated descriptions in any or all of these languages:

You enable these alternative versions by selecting them from the Add a Language dropdown list on the Leaderboard or Achievement view for your game. To view your game’s leaderboards, for example, go to the GameCircle configuration page and follow the View link in Leaderboards column.

Adding an additional language is not reversible, but you specify which ones to publish, so there’s no harm done if you change your mind or add the wrong one: simply don’t publish that version of the title and description.

Once you add a language, you will see a new corresponding line item for each leaderboard or achievement, which is independently editable.

Providing alternative versions for each title and description, while straightforward, may become unwieldy when you are translating for a lot of locales, or just have lots of leaderboards or achievements. In fact, as the number of leaderboards and achievements goes up, entering all of the other information required to create them definitely makes manual entry time-consuming.

This is where GameCircle’s new bulk upload facility becomes really handy. Rather than create each achievement individually, for example, you can create a file of comma-separated values (CSV) defining all of your achievements at once. From the list of Achievements for your game, click the Bulk Add Achievements button.

On the page that appears, download a CSV template via the click here link. Open the template and fill in the columns as appropriate, then save it locally. See the Create Multiple Achievements section of Implementing Achievements for more information on each column. You will notice, for example, that there are separate columns for each possible translation of title, locked description, and unlocked description. Icon ids for locked and unlocked versions of the achievement are shared across all languages.

Before you can upload the CSV file defining your achievement (or leaderboard) metadata, however, you must upload the icons it refers to. GameCircle provides an Icon Gallery for this purpose, which allows you to add, delete, and rename icons individually or by dragging and dropping them on a web page. You can view the Icon Gallery for your game from the GameCircle configuration page. See Using the Icon Gallery for more information.

Once the icons have been saved and the CSV file updated to reflect your achievement metadata, you’re ready to upload. Click Choose File and navigate to the file you just edited, and then upload it.

Mobile apps and games distributed through the Amazon Appstore for Android are available in nearly 200 countries worldwide, and now GameCircle allows you to provide title and description translations for several of them. Entering the metadata that defines your achievements and leaderboards also got easier, now that you can upload it as a CSV file. Added in response to developer feedback, these features were designed to complement each other and make working with GameCircle fast and simple.

Amazon GameCircle and the other game services we offer are designed to make mobile game development easier, but knowing where to start may still be difficult. To offer a bit of guidance, I thought it might be worthwhile to take a small, simple game and walk through the process of extending its functionality, one service at a time. Together we’ll gradually add features over the course of several posts, each one focusing on a specific way Amazon services speed development or reduce code complexity. At the end of the series, we’ll have a working game application that shows these services in action and demonstrates how you might incorporate them into other projects.

As the title implies, this post will kick off the series with a look at GameCircle, which supports leaderboards, achievements, and Whispersync for Games, a powerful mechanism to synchronize local and cloud data. Games have been saving progress and celebrating player success since the beginning, so GameCircle seems like a good place to begin our journey.

Prerequisites

Note that this blog series assumes that you are comfortable developing for Android using Java and Eclipse, and that your development environment is set up and working properly with the Android Developer Tools (ADT). Some Amazon services are available only on Kindle Fire, so that will be our target device throughout the series. You must install the Kindle Fire SDK add-ons in order to use those features. For more information, see the Get Started section of Kindle Fire Development Resources.

Importing the Monster Tag Project

Before we begin, we need a simple game that will serve as the base for our experimentation and improvements. Monster Tag displays a horde of monsters and asks the player to tag them as they bounce around the screen. Every time a monster is tagged, it gets startled and speeds off in another direction. The faster a monster is moving when it’s tagged, the more points are awarded to the player.

To import the Monster Tag project into Eclipse, download and extract the source bundle to a convenient location, then choose File | New | Project… from Eclipse’s main menu. Expand Android and select Android Project from Existing Code, then click Next. 

Click Browse… to navigate to the temporary location where you extracted the source code, then click OK. Check Copy projects into workspace and click Finish. 

Once the project has been loaded successfully, you will see it in the Package Explorer:

Launch the application in the debugger for the first time by selecting the MainActivity and choosing Run | Debug As | Android Application from Eclipse’s main menu. You should see a lot of little orange guys flying around, daring to be tagged.

Establishing Trust

We have a basic game application running, but we’re still not ready to integrate GameCircle and use it to track high scores online. The GameCircle service won’t accept connections from just any mobile application—it authenticates requests to ensure they’re coming from trusted apps. Every app or game that wants to access GameCircle (and some other Amazon services) must have an “API key,” which is associated with a security profile for that app. The key tells GameCircle that our app is trustworthy.

To establish a security profile and obtain an API key, we must first let Amazon know about our game, which we do on the Mobile Application Distribution Portal. Sign in or create a developer account there if you don’t already have one. (If you’re creating an account for the first time, you’ll be asked to supply some basic information and agree to some terms and conditions. If you intend to create paid apps, you’ll have to provide some extra info, as well.)

Once you’ve logged in, go to the Apps & Services tab and hover over the Add a New App drop-down, then select Add new Android App. Now we can tell Amazon the details of our game:

Generating a Security Profile

After clicking Save we could add more details, such as pricing, icons, and screenshots, but for now we’ll skip those steps and jump right to creation of a security profile. Follow the Security Profile link that appears under the app title on the next screen, then click the Create a New Security Profile button.

You’ll be asked to name the security profile. Note that you can share security profiles between applications, which we’ll discuss in a later post. For now, we’ll assume only Monster Tag will use this one, so we’ll name it accordingly:

Creating an API Key

Now we have a security profile, but no API key has been associated with it yet. Follow the API Keys link that appears after the profile name, then fill in the required fields and click Generate.

NOTE: What you enter in the signature field, below, will depend on your own development environment; you must supply the MD5 signature of your own debug keystore. You can find information about obtaining this value in the Debug application signature section of Getting Your OAuth Credentials and API Key. Typically this involves using keytool (installed as part of the JDK) from the command line:

keytool -list -v -alias androiddebugkey -keystore /path/to/debug.keystore

You should be asked to supply a password, which is “android” by default (no quotes). Check the output for the MD5 signature, highlighted below:

...

Certificate fingerprints:

         MD5:  D4:81:0C:AA:3D:45:DE:45:59:F2:BE:DE:95:A8:E1:65
         SHA1: A1:DF:DD:0D:89:77:81:24:E0:AF:47:AA:B6:55:B6:14:58:7D:4C:E4
         SHA256: 5:50:7F:6F:43:2C:3E:CD:D6:46:F1:F7:96:F2:ED:DE:E8:DD:3A:53:00
         Signature algorithm name: SHA1withRSA
         Version: 3

Adding an API Key to an Eclipse Project

Generating the API key will result in a long base64-encoded string. This is the magic value we need to include in our project to identify our app as trustworthy.

To add it to the project, create a new file called /assets/api_key.txt and paste in the value. Note that api_key.txt must be located in the /assets subfolder.

Enabling GameCircle Data for a Security Profile

Next, we must indicate that there will be GameCircle data associated with the security profile we just created, and that our Monster Tag game will use it. Go to the GameCircle configuration page, select the security profile we created and click Confirm.

Connect a Security Profile to the App

To connect our game to the correct GameCircle data, go to the My Apps tab of your profile, click the Monster Tag app, then follow the Security Profile link. Click the Monster Tag radio button and confirm the action by selecting Apply Profile on the dialog that appears.

Next Steps

Success! Our app is registered with Amazon, there’s a security profile associated with it, and we generated a corresponding API key and added it to our project. We’re ready to use GameCircle and it’s ready to accept requests from our mobile application.

In the next installment of this series, we’ll use GameCircle’s built-in leaderboard functionality to track high scores and let users compete with each other. Now that we have the app and security bookkeeping out of the way, it will be a cakewalk.

Following up on the second in a series of webinars covering Amazon devices, game services, and mobile applications, here’s a list of questions we collected during and after our presentation on Amazon GameCircle, including Achievements, Leaderboards, and Whispersync for Games.

Does the developer have access to the GameCircle nickname?

Yes, you can call getLocalPlayerProfile(), which returns a structure containing player id and player alias (same as nickname/username). NULL is returned if the player is in guest mode (they have not logged in). Player id is unique for each player.

When updating Achievement Progress can you decrement it as well or does the GameCircleCient hold onto the latest highest progress value?

Achievement progress is strictly increasing, which means updates must be greater than the current value or they’ll be ignored. Note that you can reset achievement data for draft achievements (those that have not yet been published).

With the update, does GameCircle still support Kindle Fire 1?

Yes. The GameCircle system app must be updated to v1.1_1101110, however. This should have been delivered OTA. On KF2, the GC system app should be v2.5.2500310 or greater.

Can leaderboards/achievements be translated?

Not yet, but localization is in development and will be available in a future release.

Is the same game discovery mechanism on Kindle Fire available on all Android devices as well?

The dedicated Games Tab is built in to the games library on Kindle Fire only. It’s not available on other Android devices.

What is the minimum OS supported?

GameCircle supports API level 10 up to API level 16 on all Android devices.

Is GameCircle available internationally?

Yes, GameCircle works internationally. Players in China are limited to Guest mode for now, due to data storage requirements imposed by the Chinese government, but we will address that in a future release.

Is the old version of GameCircle still supported?

Yes, for legacy games. Games that have been published using GameCircle v1.x will continue to work. If you had a game in development when GameCircle v2.0 was released, you can proceed to publish it using the old version. Since the Mobile App Distribution Portal no longer provides direct support for GameCircle v1.x app whitelisting, however, you must contact us to add or update package name/signature pairs. See the Whitelisting Notice on the GameCircle configuration page for more information.

What happened to the FileSync and BlobSync from Whispersync?

We greatly simplified the Whispersync interface to make it easier to integrate and expand auto-resolution of data conflicts. As a result, we dropped support for the blob and multifile sync options. They were complicated to integrate and forced the developer to manually reconcile data on occasion (or to ask the customer to do so). The new Whispersync requires significantly less integration overhead and provides a better customer experience in most cases.

Can I migrate old Whispersync data to the new format?

Yes, there are two methods on the WhispersyncClient that can help in the migration process. migrateVersion1GameData() and unpackVersion1MultiFileGameData() will download and unpack data stored using the previous version, respectively. They’re only meant to be used by games that integrated Whispersync prior to July 1, 2013. See the Javadoc for more info.

Is there any way to integrate game circle in Air apps?

Amazon provided an Adobe Native Extension (ANE) for GameCircle v1.x, but none is yet available for the new version. We are actively researching an upgrade to the existing ANE, but don’t have an official timeline. Check back here or follow @peterdotgames for updates on the availability of a new ANE. In the meantime, you can continue to the existing extension with GameCircle v1.x for games currently in development.

Where can I learn more about Unity plugin for game circle?

Check out the Amazon Unity Plug-Ins page on the Amazon Mobile App Distribution Portal.

Do users need to login with Amazon account username and password to use the game services?

No, GameCircle now supports a Guest Mode for users who don’t want to log in to an Amazon account. In this case, data will not be synchronized to the cloud or across devices.

Is there a good game to play to check out the features?

There are many great games that include GameCircle features, including well-known blockbusters and high-quality indies. In the Amazon Appstore, look for the GameCircle badge to quickly identify games that use Achievements, Leaderboards, or Whispersync for Games.

Don’t miss out next webinar event: How to Integrate Amazon Mobile Ads and Lift Your App Revenues 
on August 15th, 2013 @ 10:00 AM.

Pre-register here!

Save game data in the cloud to protect your customers’ progress and support play from multiple devices

In just a few short years, the explosion in popularity of smart phones and tablets has transformed gaming, as touch controls, geolocation, and micropayments enter the mainstream. Online storage is also becoming more common, as developers adjust to a major challenge of mobile devices: physical durability. Keeping your data in the cloud starts to look mighty attractive compared to keeping it on a device that’s easily misplaced, damaged, or stolen.

Blob storage is a common way to save data online (game data is simply written to the cloud as one big chunk). If two devices update the same data, though, one of the updates must be ignored or overwrite the other. You have to decide which update to keep (based on a timestamp or version number, perhaps), or maybe prompt the user to choose between them. Either way, data is lost.

Because of the overhead involved, many developers don’t even bother with this naïve approach. This is a huge disservice to the player, whose game progress is completely lost if anything happens to his or her mobile device. Whispersync for Games saves game data for you, and works across all Android devices (including Kindle Fire).

Mergeable and Non-mergeable Data

Whispersync was designed to prevent data loss, make developer or player intervention unnecessary when resolving conflicts, and be dead-simple to integrate and use. It doesn’t distinguish between online and local storage, so the programmer doesn’t have to handle separate cases for saving to disk and cloud. It does this by manipulating only mergeable data.

Game data is mergeable if a simple rule can be defined to resolve conflicting values. For example, the rule associated with the best completion time might be, “Take whichever value is smallest.” To keep track of a player’s best score, we might use, “Take whichever value is highest.” In some cases, the most recent value may be the most important, so the appropriate rule would be, “Take whichever value is newest.” These rules apply at a granular level; Whispersync doesn’t treat game data as one big chunk.

Not all game data can be resolved using simple rules, though, in which case we call it non-mergeable. The current state of a chess board, for example, requires a complex tree structure to describe it. Reconciling two versions of the board is more complicated than just choosing the “lowest” or “highest” one.

Describing Game Data Using Syncable Types

Fortunately, a lot of game data is naturally mergeable or can be adjusted to be so. Whispersync offers many different syncable types with several built-in rules to resolve conflicts. They can be used to model simple and complex game data.

• SyncableNumber – A number that is the lowest, highest, or most recent.
• SyncableString – A string that is the most recent.
• SyncableAccumulatingNumber – A number that can be incremented and decremented.
• SyncableNumberList – A list of numbers in ascending, descending, or latest order.
• SyncableStringList – A list of strings ordered by most recent.
• SyncableStringSet – A set of strings.
• GameDataMap – A nested map, allowing hierarchical data.

A global GameDataMap object represents the root storage for your game, storing named values of the types above. Setting a value that doesn’t exist will create it on the fly. The accessor used to retrieve a value determines the conflict resolution strategy that will be associated with it.

  public static final String SKILLS = "skills";
  public static final String TOTAL_TIME = "totalTime";
  public static final String LEVEL_MAP = "levelMap";

  public static final int NUM_LEVELS = 5;
  public static final int MAX_ITEMS = 3;

  public static final String SCORE = "score";
  public static final String STARS = "stars";
  public static final String BEST_SCORES = "bestScores";
  public static final String BEST_TIMES = "bestTimes";

  GameDataMap gameDataMap;

  public void initGameData() {
    gameDataMap = AmazonGamesClient.getWhispersyncClient().getGameData();

    // These will be independent of level.
    gameDataMap.getStringSet(SKILLS);
    gameDataMap.getAccumulatingNumber(TOTAL_TIME);

    // Use nested maps to establish some per-level values.
    for (int i=0; i < NUM_LEVELS; i++) {
      GameDataMap levelMap = gameDataMap.getMap(LEVEL_MAP + i);

      // Each level will have its own copy of these values.
      levelMap.getLatestNumber(SCORE);
      levelMap.getHighestNumber(STARS);
      levelMap.getHighNumberList(BEST_SCORES).setMaxSize(MAX_ITEMS);
      levelMap.getLowNumberList(BEST_TIMES).setMaxSize(MAX_ITEMS);
    }
  }

In the example above, we use initGameData() to establish the structure of the data we’ll synchronize, even though we don’t actually set any values. (It can be helpful to define the data layout in one place like this, even if it’s not strictly required.) The code effectively says,

• There will be a global set of strings called SKILLS. It will track every string added to it (strings may not be removed).
• There will be a global running total of time in the game called TOTAL_TIME. It will accumulate deltas submitted from all devices used by a single player.
• There will be NUM_LEVELS nested maps, each of which will have its own set of values:
  • SCORE will always reflect the last score submitted for that level.
  • STARS will always reflect the maximum stars attained for that level.
  • BEST_SCORES will always list the MAX_ITEMS highest scores for that level.
  • BEST_TIMES will always list the MAX_ITEMS fastest times for that level.

Updating and Retrieving Game Data

Whispersync abstracts all game data persistence, so we can update or retrieve values using simple getters and setters. We don’t have to worry about managing a network connection, saving to disk or the cloud, or reconciling local and online versions of variables we have in memory. When we add to the running total of time played, for example, Whispersync automatically saves the delta to disk and updates the cloud if connected. If the player’s device is currently offline, the update will be queued and delivered later.

  public void updateTotalTime(int timePlayed) {
    SyncableAccumulatingNumber totalTime = gameDataMap.getAccumulatingNumber(TOTAL_TIME);

    // Add the time played to the running total.
    totalTime.increment(timePlayed);

    // Output the new total to the console.
    System.out.println("Total Time Played = " + totalTime.asInt());
  }

Likewise, we can record skills as the player masters them and easily iterate over the set to display the ones learned so far:

  public void learnSkill(String skill) {
    SyncableStringSet skillSet = gameDataMap.getStringSet(SKILLS);

    // Add the new skill to the player's repertoire. Note that this list

    // can only expand; strings cannot be removed.
    skillSet.add(skill);

    // Output all skills to the console.
    for (SyncableStringElement s : skillSet.getValues()) {
      System.out.println("Skill = " + s.getValue());
    }
  }

Updating numbers and number lists is just as straightforward, so persisting all of the player’s progress at the completion of a level can be done in just a few lines:

  public void finishLevel(int level, int score, int stars, int time) {
    GameDataMap levelMap = gameDataMap.getMap(LEVEL_MAP + level);

    // Save the score for this level. Newer values will always overwrite
    // previous scores.
    levelMap.getLatestNumber(SCORE).set(score);

    // Try to set the new maximum stars attained on this level. If the
    // value is less than the current maximum, this call does nothing.
    levelMap.getHighestNumber(STARS).set(stars);

    // Try to add this score to the list of all-time bests. If it's not
    // high enough, this update will be ignored.
    levelMap.getHighNumberList(BEST_SCORES).add(score);

    // Try to add this completion time to the list of all-time bests. If
    // it's not low enough, this update will be ignored.
    levelMap.getLowNumberList(BEST_TIMES).add(time);
    updateTotalTime(time);
  }

The accessors on GameDataMap and Whispersync’s syncable types make it easy to manipulate game data and define how conflicts should be resolved.

Think Mergeable!

Whispersync for Games automatically resolves conflicts for data it can merge, which makes it worthwhile to describe game data using syncable types when possible. Since Whispersync supports high, low, and most recent numbers and number lists; running totals; latest strings and string lists; sets of strings; and nested maps supporting hierarchical structures, a wide range of game data can be modeled.

Thinking about your game data in mergeable terms lets you push a lot of overhead out of your code. Let Whispersync handle the heavy lifting. For more information on integrating Whispersync into your game, see the online documentation. 

Continuing our series of success stories from developers around the world, we go to France, where developers are witnessing strong positive results less than a year after the launch of the Amazon Mobile App Distribution Program in August 2012.

Ubisoft’s PC and console titles have been available on Amazon for a long time, helping to build a great partnership between both companies over the years. As Ubisoft strengthened its mobile offering, it was a natural progression for their Android games to be made available on Amazon and to Kindle Fire users. Dominique Tardieu, Sales and Marketing Director at Ubisoft Mobile, explains: “Amazon and Kindle Fire tablets hold a significant potential for our mobile games as they become more and more widespread. Also, Amazon has developed a meaningful ecosystem for Kindle Fire games via Amazon GameCircle. This gives us the possibility to leverage the social aspects of our games, through Player vs Player functionality and leaderboards, for instance.”

Since September 2012, Ubisoft has successfully launched a variety of best-selling games on Amazon, including Rayman Jungle Run, Prince of Persia, and (more recently) Nutty Fluffies. An important element of these games’ success so far has been Amazon personalization and recommendations. Tardieu says, “The experience they bring in terms of customer relationship management and knowledge of the industry has made it possible for us to ensure a successful launch for all our titles. Amazon clearly benefits from the know-how acquired over the years working on Ubisoft’s console and PC games and has learned how to harness it to successfully promote the right content to the right consumers.”

About Ubisoft:
Ubisoft is a leading producer, publisher, and distributor of interactive entertainment products worldwide and has grown considerably through a strong and diversified line-up of products and partnerships. Ubisoft has offices in 26 countries and operates in more than 55 countries around the globe. It is committed to delivering high-quality, cutting-edge video game titles to consumers. For the 2011-12 fiscal year, Ubisoft generated sales exceeding €1 billion. To learn more, please visit: www.ubisoftgroup.com

We just released a major update to Amazon GameCircle, our free game service providing achievements, leaderboards, and Whispersync for Games. Games on all Android devices (including Kindle Fire, of course) can now integrate GameCircle, which is easy because we support Java, JNI, and Unity3D. Whether you submit your game to Amazon or Google, customers will benefit from the GameCircle experience. In addition, Whispersync has been dramatically improved, becoming the first and only cloud-save service to:

1) Automatically resolve data conflicts between mobile devices and the cloud,

2) Queue updates to support offline operation, and

3) Offer a simple interface that can be integrated in minutes.

The result: Your customers’ game data will automatically sync across devices—even if they play your game while temporarily offline—and you can concentrate on using the data instead of persisting it. You’re not locked in, though; you retain ownership and can always get a copy of the data you store.

We also give you flexibility when it comes to GameCircle display options, with no intrusive splash screen and configurable notification toasts. You’re in control and choose where they appear.

I’ll provide more technical details about these enhancements in future posts, but for now, let’s take a closer look Whispersync and explore its powerful new features and simplified interface.

Whispersync for Games

Whispersync does the heavy lifting when it comes to synchronizing local data to and from the cloud. It handles the tricky scenarios that you would normally have to deal with yourself, like conflicting updates from multiple devices or sync requests from a device that’s temporarily offline. You can also stop worrying about scalability; behind the curtain, Whispersync (and all of GameCircle) is powered by Amazon Web Services like S3 and DynamoDB.

Using Whispersync is easy through an API that has been completely redesigned, providing an interface similar to SharedPreferences. Saving game data to the cloud and synchronizing it between devices is as easy as retrieving a variable from a map and using (or changing) its value:

    // Get the global game data map for the current player.
    GameDataMap gameDataMap = AmazonGamesClient.getWhispersyncClient().getGameData();

    // Look up the object representing the player’s skill rating.
    // If none exists, one will be created.
    SyncableNumber skillRating = gameDataMap.getHighestNumber("skillRating");
    System.out.println("skillRating = " + skillRating.asLong());

    . . .

    // Update the value. As long as this device is online (or as soon as
    // it is), local and cloud storage will be synced.
    skillRating.set(MAX_SKILLRATING);

Whispersync maintains a singleton instance of GameDataMap that acts as the root of your game data. It can track numbers, strings, simple lists, and other maps, and gives you complete freedom in how you represent your game data using these basic syncable types. You add new variables simply by retrieving them by name; if they don’t exist, they’ll be created on the fly and synchronized from that point on.

How Whispersync applies updates and resolves conflicts depends on the way you access each syncable variable. For example, suppose you want to retrieve the current user’s best (highest) level across all devices:

    GameDataMap gameDataMap = AmazonGamesClient.getWhispersyncClient().getGameData();
    SyncableNumber bestLevel = gameDataMap.getHighestNumber( "bestLevel" );
    System.out.println( "bestLevel = "  + bestLevel.asLong());

In this case, because “bestLevel” is retrieved as a highest number, it will always reflect the maximum value ever assigned to it, from anywhere, on any device.

String values can also be synced. You could easily set the name of the latest power-up collected:

    gameDataMap.getLatestString( "lastPowerUp" ).set("Super Boingo"); 

The syncable string associated with “lastPowerUp” will always reflect the value most recently assigned to it.

The online documentation and Javadoc included with the SDK have more information on the syncable types Whispersync supports, as well as the ways in which each may be accessed.

Practical Applications

Let me provide a few more examples to illustrate just how straightforward synchronization can be.

Recording Star Count for Several Levels

A common pattern in many games is to show stars and unlock status for each level on a level selection screen. Here’s an example of using Whispersync to track individual star values for multiple levels:

  SyncableNumber[] getLevelStars() {
     GameDataMap gameDataMap = AmazonGamesClient.getWhispersyncClient().getGameData();
     SyncableNumber[] stars = new SyncableNumber[NUM_LEVELS];

     // Get the star counts for all levels.
     for (int i = 0; i < stars.length; i++) {
        stars[i] = gameDataMap.getHighestNumber("levelStars" + i);
     }

     return stars;
  }

The first time the score values are accessed (from anywhere), Whispersync will create entries for them in the cloud, so there’s no need to declare them ahead of time.

Accumulating a Running Total

Some progress, like coins collected or time played, represents a running total that is always updated using a delta amount. Instead of setting the value directly, you just submit the amount by which it should change. Whispersync automatically adds or subtracts this value to update the current total. For example:

 void addTimePlayedToTotal(long timePlayed) {
    GameDataMap gameDataMap = AmazonGamesClient.getWhispersyncClient().getGameData();
    SyncableAccumulatingNumber totalTime =        gameDataMap.getAccumulatingNumber("totalTime");

    // This object may be incremented/decremented with long, double, and
    // BigDecimal values.
    totalTime.increment(timePlayed);
    System.out.println("Total time played: " + totalTime.asLong());
 }

Keeping a Map of Maps

By embedding a map within a map, you can create a hierarchical data structure. If your game has multiple worlds, for example, you might keep a separate GameDataMap for each one. Each of these might contain additional maps—say, one for each level.

 GameDataMap getWorldData(String name) {
    GameDataMap gameDataMap = AmazonGamesClient.getWhispersyncClient().getGameData();

    // Get all the string keys associated with top-level GameDataMap objects.
    Set<String> worldNames = gameDataMap.getMapKeys();

    // Look for a match among the maps.
    for (String currentName : worldNames) {
       if (currentName.equals(name)) {
          // A map exists for the name specified.
          return gameDataMap.getMap(currentName);
       }
    }

    // No match found. Don't create one.
    return null;
 }

Maintaining a List of Numbers

A racing game might save a player’s top three best times using a syncable number list. In this case, you could create a list for low numbers—they decrease as times improve—but you could easily choose to retain a collection of the highest or most recent values in other situations.

 // We'll initialize this once the application has launched.
 AmazonGames agsGameClient;
 GameDataMap agsGameData;
 SyncableNumberList agsBestTimes;

 // Create a callback to handle initialization result codes.
 AmazonGamesCallback agsGameCallback = new AmazonGamesCallback() {
    @Override
    public void onServiceReady(AmazonGamesClient client) {
       agsGameClient = client;
       agsGameData = AmazonGamesClient.getWhispersyncClient().getGameData();

       // Establish how many slots will be allocated and preserved.
       agsBestTimes = agsGameData.getLowNumberList("bestTimes");
       agsBestTimes.setMaxSize(3);
    }

    . . .
 };

  void finishLap(double time) {
   // Every time a lap is completed, try to add the lap time
   // to our list of best times. Only the lowest three will
   // ever be preserved.
   agsBestTimes.add(time);
 }

Every time the player finishes a lap, finishLap() would be called to update the number list. The value specified will be discarded unless it is lower than one of the current entries.

More to Come

The GameCircle improvements released in the latest update deserve more attention than the brief overview I’ve given here, so I’ll add details in the coming weeks. Look for articles dedicated to JNI; advanced API features; and using GameCircle with frameworks such as Unity3D, Cocos2d-x, and Marmalade. I’ll also dive deeper into Whispersync, discussing the difference between mergeable and non-mergeable data (and why it’s important), considerations when synchronizing currency across offline devices, and migration from the previous version. Stay tuned!

In the meantime, check out the new GameCircle release and give it a whirl. You’ll benefit whether you use the simplified Whispersync API and its expanded functionality, create a universal build to run on Kindle Fire and Android, or take advantage of the other features included with this update.

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.

Leaderboards

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.

Achievements

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.

Troubleshooting

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

In a recent study of more than 500 games that utilize in-app purchasing on Amazon, we found that mobile games using Amazon GameCircle’s leaderboards and achievements monetized significantly better than other games.

For the three-month period from November 2012 to January 2013, games using GameCircle produced 38 percent higher conversion rates and 33 percent more in-app orders per paying customer than games that didn’t use GameCircle. Conversion was measured by calculating the percentage of app users that made at least one in-app purchase. Combining the impact of both of these variables, GameCircle-enabled games earned 83 percent more average revenue per user (ARPU) than non-GameCircle games. 

The free-to-play (or freemium)  model, where consumers download and play a game for free, has become one of the most prominent business models in mobile gaming today. However, the biggest challenge for game developers following the freemium model is figuring out how to generate more revenue by converting non-payers into payers and keeping those paying users engaged.

Many of Amazon’s mobile game developers have discovered how GameCircle’s services–Achievements, Leaderboards and Whispersync–have contributed to their success at Amazon. GameCircle lets players connect with other players to compare achievements and compete for higher scores. These social elements get the competitive juices flowing, which may increase a user’s willingness to pay for in-game content, leading to higher conversion rates for developers. “PlayFirst's games on Amazon have performed above and beyond our expectations, and we believe GameCircle has enhanced our ability to connect and engage with Amazon customers, encouraging more play sessions," said Paul Chen, VP of Business Development at PlayFirst.

GameCircle also offers new discovery mechanisms that are an important factor helping drive increased engagement rates. For games that have integrated with GameCircle, players can see their friends, achievements, and leaderboard activity before launching the application, since all of this information is visible right from the user’s game library. Leading games such as Skylanders Cloud Patrol, Diner Dash, and Temple Run 2 have already integrated with GameCircle. The image below showcases how a user’s library is populated with GameCircle meta-data.

This added visibility is a powerful engagement tool. A related study that we conducted in January 2013 found that, on average, games using GameCircle over-indexed on the number of player sessions (defined by the number of times users opened the applications on their device) by 32 percent when compared to the average for the entire games category. For freemium games that monetize by selling in-game content, this enhanced level of engagement is critical to expanding customer lifetime values. "We see superior engagement, retention and monetization from players who download our games from Amazon. The GameCircle integration is helping us achieve 40 percent better per user monetization rates compared to non-Amazon players," said Sean Thompson, Vice President of Mobile Deluxe.

For you, GameCircle represents another opportunity to provide gamers with a more seamless and entertaining in-game experience, which can lead to increased engagement and monetization. Please visit the following links if you would like to learn more about the Amazon GameCircle and In-App Purchasing APIs.

Today we released a new tool to help you integrate Amazon APIs into your Android apps. The AmazonMobile App SDK Eclipse Plugin (beta) allows you to rapidly and reliably integrate Amazon APIs into your Android projects, speeding up development and cutting down on project setup time.

The Amazon Mobile App SDK Eclipse Plugin (beta) is a design-time tool that is easy to install, simple to control, and builds on your familiarity with Eclipse to increase your productivity in developing apps and games for distribution on Amazon. The plugin generates the appropriate config entries for the APIs you select, then copies over the relevant API jar files. If desired, you can also use it to quickly undo API integration, without affecting the original state of your Eclipse project.

Benefits of Using the Amazon Mobile App SDK Eclipse Plugin:

• Free to use: As with other resources we make available, the plugin is free for developers distributing their apps on Amazon.

• Easy to use: Developers have indicated that it is surprisingly fast to deploy and use the plugin. The deployment of this tool follows the typical Eclipse plugin download and installation experience and does not require a new usage paradigm.

• Gives you control of APIs and versions: The plugin allows you to use the latest version of the APIs in the Amazon Mobile App SDK that you have on your system and will alert you if your project is using an older version of the APIs.

• Works for all apps and games: The plugin helps you to quickly develop any Android app that you plan to offer via the Amazon marketplace, including Kindle Fire tablets and Android smartphones.

What’s Next?

Click here to learn how to install the Amazon MobileApp SDK Eclipse Plugin. Take it for a spin, add it to your toolbox, and then tell us what you think by completing this brief survey. We welcome your feedback and appreciate learning what more we can do to help increase your productivity.