Setting Up Your GameCircle Configuration

Before continuing, confirm that you have an account on the Amazon Mobile App Distribution portal and have set up your development environment.

Overview

Your GameCircle configuration is a set of leaderboards, achievements, testing nicknames, and other GameCircle features. You create the configuration by linking your game to a security profile.

A security profile is a shared group that enables an application's variants (such as a paid and free version) to identify themselves to Amazon. Other mobile developer SDKs at Amazon, including Amazon Device Messaging, use the game's security profile for the same purpose.

After completing your GameCircle configuration, you can move on to Initializing GameCircle in Your Game, and then begin adding GameCircle leaderboards, achievements, and Whispersync for Games to your game.

Follow these steps to set up your GameCircle configuration:

  1. Create a Security Profile and Link it to Your Game Configuration
  2. Look Up the MD5 Signature for Your Release Keystore
  3. Create an API Key and Add it to Your Project

Step 1. Create a Security Profile and Link it to Your Game Configuration

A security profile is a shared group that enables each unique binary of a single application (for example, the HD, SD, free, and paid versions of a game) to have a unique API key that will identify the binary to Amazon.

The steps required to create a security profile and link it to your game configuration depend on your prior activity, if any, in the Amazon Mobile App Distribution portal. Follow the steps for the case below that describes your situation.

Case 1: I’ve got one or more games in the Mobile App Distribution portal

On the Mobile App Distribution portal, sign in and click the Apps & Services tab, and then click the GameCircle tab to open your Dashboard. If you already have GameCircle-enabled games, the Dashboard displays your games as security profiles.

Note: You must be signed in to the portal in order to use the Apps & Services tab.

Case 2: I’ve never created a security profile

  1. On the Mobile App Distribution portal, sign in and click the Apps & Services tab, and then click the GameCircle tab. Finally, click Create a Security Profile.

    Note: You must be signed in to the portal in order to use the Apps & Services tab.

    Landing Page

  2. On the Security Profile Management page, enter a Security Profile Name and Security Profile Description. For Security Profile Name, enter the common title of your game (for example, enter Star Game rather than Star Game HD or Star Game Free). The purpose of the Security Profile Description field is to help you organize your security profiles. The description field is optional and may be left blank if you wish.

  3. Click Save.
  4. Click the GameCircle tab, which now displays a GameCircle configuration management page:

    Game Config 

Management

  5. In the Game Configuration area, in the Select a Security Profile list, select the security profile that you just created and then click Confirm. This will create a new GameCircle configuration linked to this security profile.

Case 3: I’ve got a security profile for a game, but no GameCircle configuration

  1. On the Mobile App Distribution portal, sign in and click the Apps & Services tab, and then click the GameCircle tab to open your Dashboard.

    Note: You must be signed in to the portal in order to use the Apps & Services tab.

  2. Your existing security profile will appear in the Select a Security Profile list.
  3. Select the existing security profile to create a GameCircle configuration based on it.
  4. Note: If you wish to create a new security profile, select Create New in the list to open the security profile management page and create a new security profile.


Step 2. Look Up the MD5 Signature for Your Keystore

To obtain an API key for GameCircle, you will need to provide the MD5 fingerprint from the certificate used to sign your applications. You can get the MD5 fingerprint by using keytool.

For an overview of Android application signing, including how to create an MD5 signature, see Signing Your Applications.

The following command can be used to look up the MD5 fingerprint for the debug certificate. Keystore files are commonly found in the .android folder in your home directory.

$ keytool -list -v -alias androiddebugkey -keystore ./debug.keystore

The command produces output similar to this:

Enter keystore password:  android
Alias name: androiddebugkey
Creation date: Jun 6, 2013
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Android Debug, O=Android, C=US
Issuer: CN=Android Debug, O=Android, C=US
Serial number: 50c0e275
Valid from: Thu Dec 06 10:22:45 PST 2012 until: Sat Nov 29 10:22:45 PST 2042
Certificate fingerprints:
         MD5:  F4:81:0C:AA:3E:45:DE:45:57:F2:BE:DE:95:A8:E1:63
         SHA1: A1:DF:DD:0D:89:77:81:24:E1:AF:47:AA:B6:56:B4:14:58:7D:4C:E4
         Signature algorithm name: SHA1withRSA
         Version: 3

To obtain the certificate MD5 fingerprint for your production keystore, do the following:

  1. Run this command to display aliases in your keystore:
    keytool -list -keystore full_path_to_your_keystore_file
    
  2. Run this command to obtain the MD5 fingerprint:
    keytool -list -v -keystore full_path_to_your_keystore_file  -alias alias_name
    

Step 3. Create an API Key and Add it to Your Project

To create the API key for your game, you must have at least one security profile and an MD5 signature.

  1. In the Amazon Mobile App Distribution portal, sign in and click the Apps & Services tab.
  2. On the Security Profile Management page, select the security profile for which you want to create an API key.
  3. Select the API Keys link and then select the Kindle/Android tab.
  4. Click Create a New API Key.
  5. Enter an API Key Name, your Package Name and and your Signature, and then click Generate. Generate.

    IMPORTANT: Do not use the same Package Name across multiple security profiles. Doing so will cause multiple data errors in your games or apps.

  6. The page will display your API key. Copy the full API key into a new file named api_key.txt, and then save the file in your project’s /assets folder.

If your API key is missing or incorrect, at runtime you’ll see a java.lang.IllegalArgumentException:InvalidAPIKey error in your game’s logcat.


Take the Next Step: Initializing GameCircle in Your Game

Now that you've configured GameCircle, continue to Initializing GameCircle in Your Game.

After initializing GameCircle, you can start adding GameCircle leaderboards, achievements, and Whispersync for Games to your game.


Graphical Representation of Configuration

Here’s a graphical representation of how your GameCircle configuration, security profile and API key work together:

GameCircle 

Configuration Flow

Share a GameCircle configuration across multiple binaries

You can create multiple API keys within a single security profile, which enables you to share a GameCircle configuration and the leaderboards and achievements associated with the security profile across multiple versions of your game.

For example, we have a game named Star Game to which we want to add achievements and leaderboards. The game has two versions, Star Game HD and Star Game Free, and we want them to share the same leaderboards and achievements. We create a security profile called Star Game and then create two API Keys, one for Star Game HD and one for Star Game Free, and embed them in the respective binaries. Finally, we link a game configuration to the Star Game security profile, and can now create leaderboards and achievements that will span both games.


Return to the API overview

Unavailable During Maintenance