Implementing Whispersync for Games in Unity for GameCircle 1.x

These instructions are for existing games using the Unity Plug-In with the GameCircle 1.x SDK. If you are creating a new game using the updated Unity Plug-In for GameCircle 2.x, refer to those instructions instead.

Rules and Guidelines

Whispersync for Games allows you to synchronize game progress to the cloud and across multiple Kindle Fire devices.

With Whispersync for Games, players can:

  • Uninstall and reinstall their games without losing their progress
  • Synchronize progress across multiple Kindle Fire devices
  • Revert their game to a previous save in history (up to 5 saves)

Rules and Guidelines

Customer Experience

The following statement encapsulates the desired experience for customers using Whispersync for Games:

With Whispersync and Kindle Fire, it doesn't matter where you play the game. Your saved progress, achievements, leaderboard scores, and all the content you've unlocked are stored securely in the cloud whenever you go online. The next time you play the game, even if it's on a different Kindle, they'll be there waiting for you. Items purchased to be consumed in a game, such as coins or energy, may only be available on the device where they were originally purchased.

Developer Guidelines

When moving from device to device or reinstalling a game after uninstalling it, the customer will be prompted as to whether they'd like to sync up to the latest data. Make sure you've included a simple description for their saved progress so they have the proper information to make that decision. After choosing to sync, the game should perform as if they were still playing on the original device or with the previous install.

The following items are expected to sync across devices or between deleting a game and reinstalling it:

  • Saved game progress
  • All earned achievements if built into the game
  • All high scores and rankings on leaderboards if built into the game
  • All permanently purchased content
  • All unlocked content

The following items may remain device specific:

  • Items purchased specifically for consumption within the game (e.g. coins, energy, health potions, etc.)

In addition, Amazon will sync game meta-data for Whispersync enabled games, including the following information:

  • Earned achievements leveraging GameCircle
  • Leaderboards leveraging GameCircle

Rules

  • Whispersync is intended solely for saving a customer's game progress. No other type of data should be stored in the system (e.g. personally identifiable data). Using Whispersync to store any data beyond game progress can result in your access to Amazon GameCircle being revoked.
  • Store only what you need in the cloud. While Whispersync is currently free, in the future there may be a charge for storage space. Whispersync is currently capped at 1Mb max upload per save.
  • Every time you call Synchronize Progress set a simple description of the save (e.g. Level 6-1). The description should be no more than 38 characters. This will allow customers to make a better decision when resolving conflicts.

Whispersync Sample Flow

When integrating with Whispersync, it is important to ensure that you are synchronizing data at the appropriate points. The diagram below describes a potential flow for a game. When the game is first run, it will run synchronize, to see if new data is available. When the game is between levels, or at an equivalent checkpoint, it will synchronize progress with the cloud.

Whispersync will manage detecting and managing conflicts for you. As a developer, you only need to be aware of when new data is available to you.

Whispersync Sample Flow


How to Sync Files

Create your methods for handling Whispersync events. This assumes that you have already initialized GameCircle by calling GameCircle.init and have succesfully received and handled a GameCircleManager.serviceReadyEvent. Refer to the setup page for details.

Step 1: Setup Whispersync event handling code

 
//Setup the event handlers

GameCircleManager.onAlreadySynchronizedEvent += onAlreadySynchronized;
GameCircleManager.onConflictDeferralEvent += onConflictDeferral;
GameCircleManager.onGameUploadSuccessEvent += onGameUploadSuccess;
GameCircleManager.onNewGameDataEvent += onNewGameData;

//You may choose to implement additional event handlers in this to handle the other events fired by the plugin
//Also remember that you may have unregistered your event handlers if you share handlers accross multiple unity scripts and components
//For example by doing the following GameCircleManager.onAlreadySynchronizedEvent -= onAlreadySynchronized;
//You can view all the events fired by the plugin by looking at the GameCircleManager.cs file packaged with the plugin

//Setup the methods to handle the events

public void onAlreadySynchronized() {
// nothing to do, data is already in sync.  Optionally communicate the result to the customer.
}

public void onConflictDeferral() {
// Nothing to do here.  A conflict was encountered, but the gamer chose to ignore it.
// Optionally communicate the result to the customer.
}

public void onGameUploadSuccess() {
// Nothing to do here.  Current data has been synchronized.  Optionally communicate result to customer.
}

public void onSynchronizeFailure(String error) {
// Nothing to do here.  Optionally communicate the result to the customer.
}

public void onNewGameData() {
// Sync success, the unity plugin automatically unpacks the data.
// Update your application state.
}

Step 2: Sync When Game Is First Run

When your game has no previous save state

The first time your game runs, and you have no data to synchronize send a synchronize request that will download data from the cloud if it is available. This will support the case with customers buying new devices or redownloading your game. A common place to execute this code is in the onServiceReady callback from the AmazonGamesClient initialize method.

Note: If you do not do this on the first run, when you do not have data, customers will incorrectly be presented with conflict message.

GameCircle.whisperSyncSynchronize (GameCircleConflictStrategy.AUTO_RESOLVE_TO_CLOUD);

When your game has save state

This synchronization step should happen when your game is first started and your game has existing game progress. If an attempt to synchronize progress previously failed, it will now be synchronized to the cloud.

GameCircle.whisperSyncSynchronize ();

Step 3: Sync Game Progress

At an appropriate checkpoint in the game, synchronize the current game progress. In many cases, this should happen immediately upon a level completion. This will synchronize all data for your game. This includes shared preferences, sqlite databases, or any other files you have saved that is not on the SD card. Optionally you can specify a filename extension when calling synchronize and this will only sync those files with the specified extension

Note: Please include a useful description of your customer's progress. This will help them make decisions as to which progress to use to resolve conflict. We recommend that you provide recommendations based on the most important marker in your game (levels, stars, etc.). We'll display time and device that the save was made on, so we recommend you do not use either of these pieces of data.

//Synchronizing progress
GameCircle.whisperSyncSynchronizeProgress ("Level 5 - 2 hours played");
//Synchronizing progress with an optional file extension filter
GameCircle.whisperSyncSynchronizeProgress ("Level 5 - 2 hours played", ".xml", GameCircleConflictStrategy.PLAYER_SELECT);

Step 4: Sync Game Progress When Game is Paused

When the game is paused you can synchronize progress. In this case you will want to set the conflict strategy to AUTO_RESOLVE_TO_IGNORE. This will prevent the potential for the customer being presented with a conflict dialog while exiting the game

Note: Please include a useful description of your customer's progress. This will help them make decisions as to which progress to use to resolve conflict. We recommend that you provide recommendations based on the most important marker in your game (levels, stars, etc.). We'll display time and device that the save was made on, so we recommend you do not use either of these pieces of data.

GameCircle.whisperSyncSynchronizeProgress ("Level 5 - 2 hours played", "", GameCircleConflictStrategy.PLAYER_SELECT);

Step 5 (Optional): Allow Customer to Revert to Previous Version

Some developers have asked to give their customers the ability to revert to previous saves. This feature is entirely optional and is not accessible in a game unless the developer chooses to integrate. With revert you can allow gamers to use previous save points (last 5).

GameCircle.whisperSyncRequestRevert()

//In this scenario you would need to handle addition events and have your game code respond appropriately depending on the actions of the player.

// Fired when a player cancels the sync
GameCircleManager.onPlayerCancelledEvent += onPlayerCancelled;
								
// Fired when a whispersync revert fails
GameCircleManager.onRevertFailureEvent += onRevertFailure;
								
// Fired when a whispersync revert succeeds. By default it will be unpacked automatically for you.
GameCircleManager.onRevertedGameDataEvent += onRevertedGameData;

Best Practices

  • The best customer experience is to enable your customers to sync consumables. If you worry that some customers will use in-game currency to make multiple offline purchases, add code to determine if a device is offline and then block offline purchases.
  • Don’t store personally identifiable information by using Whispersync for Games. Amazon may revoke your access to GameCircle if you use Whispersync to store any data other than game metadata.
  • Calling WhispersyncClient.flush() forces game data to be written to the device’s file system. You don’t need to call flush() each time you change your game data, because changes are automatically persisted to local storage via a background thread. However, if you know your app is about to close, calling flush() will save your game data by performing a blocking write to the file system.
  • Store binary data (byte array) to a String by using Base64, and then use the SyncableString data type to store the data in Whispersync. Do not use device-specific formatting for your data, as Whispersync can synchronize across different Android devices.

Return to the GameCircle Unity Plug-In overview

Unavailable During Maintenance