iOS Support Comes to GameCircle and Whispersync for Games, Including Built-In Achievement Analytics and Visualization

Amazon GameCircle and Whispersync for Games is live on iOS and Android!  You can store game data in the AWS Cloud so players don’t lose their game progress, high scores, or achievements when switching between devices.  We know programming for multiple platforms is standard practice for many developers—iOS support has been a frequent feature request—so we’re excited to make GameCircle available on a whole new class of devices. GameCircle and Whispersync are free for you and your players.  Plus, when you integrate GameCircle achievements, you automatically get access to Achievement Reports as well. These reports help you get a better understanding of how players interact with your game so you can make sure they're having a great experience. 

GameCircle and Whispersync are architected and maintained entirely using Amazon Web Services.  Because Amazon manages the creation and maintenance of the client SDK and web services that interact with each other, all the complexity and edge cases associated with synchronizing data, tracking and submitting high scores and achievements, and managing these services while offline are handled.  With Whispersync, for example, simply save your game data to a local Whispersync database and Amazon handles the rest.

You can get started with all of these free services in under an hour.  Download the SDK from the Mobile App Distribution Portal, where you’ll also find full documentation.



What’s New?

With this release, GameCircle v2 officially supports Whispersync, Achievements, and Leaderboards across the most popular mobile platforms.  We’ve found that on average games using GameCircle produce higher user retention rates than games that don’t, which is why we’re excited to offer all of these services for free to both you and your players.  You can choose to integrate any or all of them.

Auto-conflict resolution and improved offline support distinguish the latest version of Whispersync, and new analytic features are built in to the GameCircle service. On iOS and Android, GameCircle also now supports guest mode, so customers can get right into your game, tracking their achievements and high scores without having to sign in.

Whispersync for Games with Auto-conflict Resolution

The new Whispersync greatly simplifies how game data is saved to the cloud; you can have it up and running in less than an hour and never worry about corner cases again.  It provides a completely automatic mechanism for resolving multiple conflicting updates, even when data is received out of order, from different devices, or from different versions of your game.  The service also manages network connectivity, and will queue updates for later if a device is temporarily offline.  Just use a local key-value store to save your players’ game data (similar to Android Shared Preferences or iOS User Preferences) and the Whispersync client handles everything else. You can choose a conflict resolution strategy for each variable, which will always return the most recent value, highest or lowest number, or a running total that you can increment and decrement.

Player data is stored securely in the AWS Cloud.  You don’t have to set up, maintain, or pay for any servers of your own. Players can complete a level on a Kindle Fire, for example, then switch to an iPhone and pick up right where they left off.  Whispersync’s friction-free data sharing across devices and platforms improves the player experience, leading to higher engagement and less customer churn.

Not to mention the fact that losing your progress is just painful.  As a gamer, I hate it when this happens. I also want to be able to play anywhere.  We hear this from players all the time: “Why can't I transfer my game progress from one device to another?”

We’ve tried to address this in our own games.  Amazon Game Studios integrated GameCircle into Air Patriots, Amazon’s action strategy game for Kindle Fire, Android, and iOS. Game data is synchronized seamlessly, regardless of which mobile device is used, so players can continue their campaign across all of their devices.

Sourabh Ahuja is Vice President of Android Development at Glu Mobile, a leading global developer and publisher of freemium games for smartphone and tablet devices.  “Amazon's Whispersync service is one of the most effective cloud save services available on mobile platforms,” he says. “Its ease-of-use, auto-conflict resolution and intuitive design save time and require little custom development. We simply set up our variables and Whispersync handles the rest.”

Availability Across Platforms

Originally available only on Kindle Fire, GameCircle now works on all Android mobile devices supporting API level 10 or above. GameCircle supports Android games regardless of the marketplace in which they are sold, without changes to the underlying code. 

GameCircle supports iOS 5.0 and up. We designed the iOS build for easy integration, and even provide direct support for Apple’s Game Center, allowing you to submit your achievement and high score updates to their system and ours with a single method call.

Developers such as Driftwood Software, creator of popular mobile game titles like Floor is Lava and Flight Theory, have been happy with GameCircle’s expansion to additional devices. “GameCircle's cross-platform support is key because it provides a non-intrusive experience for our customers,” said Driftwood Software’s Jason Allen. “Implementation was straightforward and customers responded positively right away. We plan to update all our games using GameCircle's cross-platform support.”

GameCircle + Analytics

In addition to becoming fully cross-platform, GameCircle also includes brand new Achievement Reports. Now you can see at a glance, for example, whether an achievement is too hard or too easy to obtain.

Click to Enlarge
(Click to Enlarge)

Armed with this kind of detailed engagement information, you can fine tune the player experience and keep them coming back. After all, better player retention leads to better monetization.

Visualizations of achievement data, like those shown above, are supported today.  There’s no code to add or special steps to take; they’re automatically available when you integrate with the latest version of GameCircle and use achievements.

Using GameCircle on iOS

If you’re new to GameCircle, the online documentation is your first, best resource for understanding its features and APIs on iOS.  It explains how to use the Mobile Application Distribution Portal to configure the service and link your application to it through a security profile and API key.  It also has example code demonstrating in-app initialization, posting leaderboard and achievement updates, and syncing game data.

On the other hand, if you’ve used GameCircle on Kindle Fire or other Android devices, you’ll find GameCircle on iOS very similar.  As might be expected, the most significant changes are in how the SDK is included in your project and initialized, allowing for the basic differences between Objective-C and Java or C++.  Method names are similar across platforms, as is the way in which they’re generally called.

Security Profiles and API Keys

The authentication and authorization mechanism Amazon uses to control access to the GameCircle service is common across all platforms. This means that once you create a security profile for your mobile app or game, it can be used to generate API keys for both Android and iOS devices. This is necessary, in fact, to allow iOS and Android versions of your game to share GameCircle data. From the Security Profile Management page, select the security profile associated with your game, then click API Keys. There are now separate tabs for each device type:


Note that the Bundle Id is similar to the Package supplied when generating an API key for Android, but no certificate store signature is required in this case.

Adding GameCircle to your iOS Project

Once you’ve obtained the latest GameCircle SDK from the Mobile App Distribution Portal, updating your project to build with it is straightforward. Drag GameCircle.bundle, GameCircle.framework, and AmazonInsightsSDK.framework (necessary for analytics) to your project, then link the system frameworks that GameCircle depends on (some of which may already be present).


Finally, you must update your project’s info.plist file to include a few special properties. These include the API key you generated above, as well as a special URL type to allow users to log in to GameCircle.


See GameCircle iOS Configuration: Setting Up Your Game Project for a complete list of the system frameworks you must include, as well as the new properties needed and how to set them up.  


Initializing GameCircle in Your Game Code

As on Android, your game code must initialize GameCircle before attempting to submit updates or sync data to the service. Do this in the application:didFinishLaunchingWithOptions: protocol method of your project’s UIApplicationDelegate, just as you would in the onResume() method of an Android Activity.  For example:

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
  self.window = [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]];

  if ([[UIDevice currentDevice] userInterfaceIdiom] == UIUserInterfaceIdiomPhone) {
    self.viewController = [[ViewController alloc] initWithNibName:@"ViewController_iPhone"
  } else {
    self.viewController = [[ViewController alloc] initWithNibName:@"ViewController_iPad

  // Initialize GameCircle before first use, passing the features we will
  // actually want to utilize and a completion handler (callback) to be

  // executed when initialization is complete.
  [GameCircle beginWithFeatures:@[AGFeatureAchievements,
        completionHandler:^(NSError *error) {
          // GameCircle not ready until this completion handler executes.

  self.window.rootViewController = self.viewController;
  [self.window makeKeyAndVisible];
  return YES;

You must also implement application:openURL:sourceApplication:annotation: to enable Login With Amazon, necessary to allow users to log in to GameCircle.

- (BOOL)application:(UIApplication *)application
    openURL:(NSURL *)url
    sourceApplication:(NSString *)sourceApplication
  return [GameCircle handleOpenURL:url sourceApplication:sourceApplication];

See GameCircle iOS Configuration: Initializing the GameCircle SDK for more information, including how you can map Game Center achievements and leaderboards to their GameCircle counterparts. This mapping makes it possible to update Game Center and GameCircle with a single method call.

Syncing Game Data Using Whispersync for Games

With this release, game data is now truly portable between devices with extremely little developer effort.  Persisting it locally and to the cloud is handled with a single method call, and the data is always available, even if the player is temporarily offline.

You access game data on iOS through the same map-like interface available on Android and Kindle Fire. Individual data items are stored in a shared structure as key-value pairs, with specialized accessors that determine the data type and resolution strategy associated with the data. The map is always accessible by sending a gamedata: message to the AGWhispersync object:

// Hold our reference.
AGGameDataMap *gameDataMap;

void setupGameData() {
 // Save a reference to the root object for later use.
 gameDataMap = [[AGWhispersync sharedInstance] gameData]; 

  . . .

Once you have a pointer to the game data map, you can access and update items using the accessors appropriate to the data you want to store. If you attempt to retrieve a value that doesn’t exist in the map, it will be created on the fly and be available from that point forward.

  // Retrieve the most pies collected on the current level.
 AGSyncableNumber *piesCollected = [gameDataMap highestNumberForKey:@"piesCollected"];
 NSLog(@"Most pies collected on current level: %d", [[piesCollected value] intValue]);

The AGSyncableNumber type in the snippet above represents a numeric value (integer or floating point), but other data types are also supported. These include numbers, number lists, running totals, strings, string lists, string sets, and maps. See the online documentation for a complete list. Conflicting updates to variables of each type are resolved according to which accessor is used to retrieve it. In the case above, highestNumberForKey: was used to look up the variable, so any updates to it will be discarded unless the new value is higher than the current one.

  // Accessor (highestNumberForKey) determines how conflicts are resolved.
 AGSyncableNumber *goblinsAxed = [gameDataMap highestNumberForKey:@"goblinsAxed"];

  // Assuming goblinsAxed starts at 0...
 [goblinsAxed setValue:@(50)]; // set new value to 50
 . . .
 [goblinsAxed setValue:@(87)]; // fine, since the value is increasing
 . . .
 [goblinsAxed setValue:@(15)]; // ignored, since new value is less than current

Generally, synchronization happens without prompting from the developer, but there may be times when you want to force a sync (for instance, just before your game exits). In those cases, simply call synchronize: explicitly:

  // Force a sync before shutdown, for example.
 [AGWhispersync synchronize];

You can also listen for notifications from Whispersync, which broadcasts updates about its actions during the course of normal operation. You may wish to know when new data is retrieved from the cloud, for example, or when Whispersync has successfully uploaded local data there. Whispersync posts these updates to NSNotificationCenter using predefined names (see the online documentation for a complete list). To be notified when data has been written to disk locally, for example:

// This constant name corresponds to the disk write event.
NSString *const AGWhispersyncNotificationDiskWriteComplete;

// Register as a listener for AGWhispersyncNotificationDiskWriteComplete events.
[[NSNotificationCenter defaultCenter] addObserver:self

// Define a method to handle the notifications.
- (void)updateGameInfo:(NSNotification*)notification
 // Executes whenever AGWhispersyncNotificationDiskWriteComplete happens.

This has been a whirlwind tour of Whispersync for Games on iOS, but there is a wealth of additional information online, including examples of additional resolution strategies, using hierarchical game data, and handling conflicts in your own code.

Using Leaderboards and Achievements

GameCircle Leaderboards and Achievements are set up on the Mobile App Distribution Portal, independent of your mobile application. That process is described in detail online (see Implementing Leaderboards and Implementing Achievements) and doesn’t change for iOS. However, to enable simultaneous updates to Game Center and GameCircle, you must create corresponding leaderboards and achievements on iTunes Connect, mapping them to GameCircle as mentioned above.

Actually sending score and achievement updates is remarkably simple.

  // Send a score (1589) to a specific leaderboard.
 [[AGLeaderboard leaderboardWithID:@"YOUR_LEADERBOARD_ID"]
   completionHandler:^(NSDictionary *rank, NSDictionary *rankImproved, NSError *error) {
     // This block executes if score is submitted successfully.

  . . .

  // Update an achievement to unlock it (100% complete).
 [[AGAchievement achievementWithID:@"YOUR_ACHIEVEMENT_ID"]
   completionHandler:^(BOOL newlyUnlocked, NSError *error) {
     // This block executes if progress is submitted successfully.

Be sure to provide some way for your players to access their Leaderboards and Achievements from your UI. Include a button or menu item that allows a player to display the appropriate GameCircle overlay with a call to showWithState:animated:. For example,

  // Overlay the GameCircle Leaderboards for this game.
 [[AGOverlay sharedOverlay] showWithState:AGOverlayLeaderboards animated:YES];

Note that setToastLocation: and setToastsEnabled: may be used to customize how GameCircle notifications are displayed in your game, adjusting their position or disabling them altogether (except for the Welcome toast, which is always displayed). See the online documentation for details on supported screen positions.

 // Display all notifications (except Welcome) in the lower right
 // corner of the screen. The Welcome toast always appears in the
 // bottom center.

 [GameCircle setToastLocation:AGToastLocationBottomRight];

  . . .

  // Optionally turn off non-Welcome update notifications entirely.
 [GameCircle setToastsEnabled:NO];

All GameCircle features are fully supported on iOS, so you may retrieve a list of leaderboards or filter leaderboard scores just as you would from your mobile game running on Android.

 // Get an array of all leaderboards associated with this game’s
 // GameCircle configuration.

 [AGLeaderboard allDescriptionsWithCompletionHandler:
  ^(NSArray *leaderboards, NSError *error) {
     // Do what we want with the list of leaderboards

  . . .

  AGLeaderboard *leaderboard = [AGLeaderboard leaderboardWithID:@"YOUR_LEADERBOARD_ID"];

  // Retrieve the weekly high score for a specific leaderboard.
 [leaderboard localPlayerScoreWithFilter:AGLeaderboardFilterGlobalWeek
        completionHandler:^(AGScore *score, NSError *error) {
     if (error)
       NSLog(@"Unable to get high score with error: %@", [error description]);
       // Handle error
       NSLog(@"High score: %lld, rank: %d on leaderboard with ID: %@",
         score.score, score.rank, score.leaderboardID);
       // Do work with weekly high score


Continuous Improvement

This is an exciting release for us, but we’ve barely stopped to catch our breath before diving in to the next set of features. We find that most developers are able to integrate GameCircle in less than a day or two (often in just a few hours!) , but we’re constantly working to increase the ROI of your valuable time.

“We’ve been very impressed with Amazon’s development of the GameCircle API. It functions well beyond the Kindle to link all Android users together,” says Brad Young, CEO at Flashman Studios, an entertainment services firm that provides services to video game developers, brand holders, and game publishers. “Our development team has found the API easy to implement and very powerful. Amazon has been rolling out new features at an impressive rate with a focus towards keeping our users engaged and feeling as if they are a part of a bigger community.”

Join the discussion! Register for our upcoming webinar, “Integrating GameCircle in Your iOS Games,” airing 10:00-11:00am on Wednesday, October 16. You can also get more technical details from our online documentation, available on Amazon’s Mobile Application Distribution Portal.

Meet us at AWS re:Invent, where we are bringing together mobile and game developers for three days of deep technical content and monetization strategies, as part of the Mobile and Gaming track.  Learn how to build your games to scale on the AWS Cloud and to integrate GameCircle into your cross-platform games.

Unavailable During Maintenance