Create a GameCircle Configuration

Introduction

This page provides help with using the Amazon Apps & Services Developer Console for GameCircle. Game developers use the Developer Console to set up a GameCircle game configuration (including generating API keys) and create/manage leaderboards and achievements for their games.**

Before your game can interact with GameCircle–to submit a player’s game progress, show leaderboards and achievements, or sync between devices–you need to set up a GameCircle configuration. This configuration is how GameCircle recognizes your game and serves up the right data and components to players. Game configurations are created and managed in the Amazon Apps and Services Developer Console. Once you create a game configuration, this is where you’ll manage your game’s achievements and leaderboards throughout the life of the game. It’s also how you’ll monitor GameCircle-specific analytics, such as achievement reports and leaderboard high scores.

Overview of Workflow Steps

The first step is to create a new configuration for your game. Once you’ve done this, you can work through the configuration workflow as needed. As you’ll see, after the first step, the workflow does not need to be completed right away or in sequence; you can save your progress at any time and return to it later.

Configuration Workflow
Configuration Workflow

To create a new configuration

  1. Create or sign into the Amazon Apps and Services Developer Console with your developer account. (If you don’t have one you can create one.)
  2. Under Apps & Services, go to the GameCircle tab. If you’ve already created configurations, you’ll see them listed here.
  3. Click the button Add a configuration.
  4. On the Game Details page, describe your game.
  5. Either save and continue through the configuration workflow, or save and exit. The Game Details page is the only part of the workflow that’s required to create a new configuration. Once that page is saved, click on any step in the workflow map to jump to it.

Note: You can have more than one game share a configuration. Games with the same configuration share achievement and leaderboard data, which is useful when you have multiple versions of the same game. Read more about shared configurations.

Add Game Details

The Game Details page contains some basic information about your configuration.

To describe your game:

  1. Is the game you’re configuring already registered in Amazon Appstore? This question is not displayed if you haven’t registered any apps under the developer account you’re using.

    • Choose Yes to view a dropdown list of registered apps associated with your developer account. Select your app from the list. The game name and description is populated from data in Amazon Appstore.
    • Choose No to configure a new game app.
  2. Provide descriptive information about your game.
    • Game / Security Profile Name — If not populated from the Appstore, enter a title for your game. This title may be displayed to customers, but you’ll have an opportunity to specify a display name when you register it with the Appstore. (The game name is also the name of the security profile for this configuration. See the note below on security profiles.)
    • Category — Select from a list of game categories the one that best matches your game type. The category you select will be used to help catalog your game in the Amazon AppStore.
    • Description — If not populated from the Appstore, enter a brief description of your game.
  3. (Optional) Specify an alternate security profile. In most cases you won’t need to do anything with this field; see the note about security profiles below.

    Click to view a list of all existing security profiles not yet associated with a GameCircle configuration. If you select different security profile, the Game / Security Profile Name and Description fields will change to match the security profile you chose.

  4. Click Save and Continue to go to the next step in the workflow or Save and Exit to leave the workflow.

About security profiles

In most cases, GameCircle automatically handles security profiles for you, and you won’t need to do anything with them while you’re working on your GameCircle configuration. Just keep in mind one fact: the game name and description in your GameCircle configuration will stay in sync with its security profile name and description; so f you change these values in your game configuration, they’ll automatically change in the security profile.

For those who need a bit more guidance, here’s a breakdown of how security profiles are handled in some common GameCircle-specific situations:

  • You’re creating a GameCircle configuration for a brand new game that hasn’t been registered in Appstore: GameCircle automatically creates a security profile and description that is identical to the GameCircle game name and description. You don’t need to specify an alternate profile. If you edit these fields in GameCircle, the security profile will also change to stay in sync.
  • You’re creating a configuration for a game that’s already registered in Appstore: In this scenario, let GameCircle decide what to do. GameCircle will check to see if the registered app you selected already has a security profile associated with it. If so, that security profile will be used. If the app has no security profile, GameCircle will create a new one and associate it with the registered app. If you change the security profile name (in or out of GameCircle), the association between registered app, security profile, and GameCircle configuration remain in sync.
  • You’re creating a configuration for a game that hasn’t been registered in Appstore, but you already have a security profile you want to use: This scenario is rare, but it does happen. In this case, specify that the game is not already registered, leave the Game / Security Profile Name and Description fields empty, and use the alternate Security Profile field to select your desired security profile.

If you do decide to manage your own security profiles, consider the following: (a) in GameCircle, a configuration can have only one security profile, (b) a security profile can be associated with only one GameCircle configuration, and (c) once a configuration is saved, you can’t change which security profile it uses.

Generate API Keys

The API Keys page is used to generate API keys for your game. An API key is an alphanumeric string that acts as both a unique identifier and a secret token for GameCircle authentication. Devices and distribution sites use the API key to verify that your game is the version you published and has not been tampered with by a third party.

Here’s how it works. This step requires some information from the project files of the game. Once an API key has been generated, it needs to be downloaded as a text file and added to the game project.

To generate an API key:

  1. In the GameCircle workflow, go to step 2: API Keys. If you haven’t yet create an API key for this configuration, click Generate now for the platform of your game version. If you have created API keys for this configuration, you’ll see the existing ones listed. To create a new key, click Generate a new key and choose your platform.

  2. Enter the following information:

    • API key name. This value is autogenerated based on the configuration game name. You don’t need to change this field.

    • Package name. This is the name of the package that contains the code and resource files of your game. Keep in mind that package names in GameCircle configurations cannot be duplicated. If you enter a package name that’s already been used by you or another developer, you’ll get an error. This limitation ensures that GameCircle can deliver unambiguous data with shared configurations.

    • MD5 Signature. This is the MD5 fingerprint of the certificate you’re using to sign your Fire/Android app. For an overview of Android application signing, including how to create an MD5 signature, see Signing Your Applications on the Android developer website.

      To locate the MD5 signature for your game, use keytool. Run one of the following commands, depending on whether you’re getting an API key for a debug or production version, in the folder containing your keystore files. This is typically the .android folder in your home directory.

      • Debug version:

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

      • Production version (First line gets a list of aliases in your keystore, second line gets the signature for a specific alias):

        keytool -list -keystore <full_path_to_your_keystore_file> keytool -list -v -keystore <full_path_to_your_keystore_file> -alias <alias_name>

    • SHA-256 Signature. This is the SHA-256 Signature for your game (similar to the MD5 signature).

  3. Click Generate the key now. This generates a very long alphanumeric string.

  4. Click Download to file. A text file named api_key.txt will be downloaded to your computer.

  5. Add the API key to your project. For Android projects, save the api_key.txt file in the project’s assets folder.

Add Achievements

If your game awards achievements, you’ll define them in the GameCircle configuration workflow. If your game does not use achievements, you can skip this part of the configuration workflow.

In the Achievements step of the workflow, you can add new achievements and keep them in draft status as you work on them. Once they’re ready, you’ll publish them, which enables players to see and earn them. You can have up to 100 published achievements for your game. For testing purposes, you can allow selected players to view unpublished achievements by whitelisting them in step 5, Test Accounts.

Amazon GameCircle provides a localization tool that lets you publish an achievement in multiple languages for region-specific versions. These versions can contain localized text and images. For more information, see “Localize Achievements” in Manage Your GameCircle Configuration.

To add an achievement:

  1. In the GameCircle configuration workflow, go to step 3: Achievements. On this page you’ll see a list of all achievements created for this configuration, including title and descriptions, languages information, and published status.

  2. Click Add an achievement. This window allows you to define a single achievement and save it.

    As an alternative, you can also use the dropdown button to select the bulk add tools for achievements and icons. With the bulk uploading, you can define multiple achievements (and optionally multiple language versions for each achievement) in a CSV file and upload the file to GameCircle. Icon bulk uploading lets you drag and drop multiple image files to your configuration’s image gallery. For more info, see “Bulk Upload or Bulk Edit Achievements” in Manage Your GameCircle Configuration.

  3. Add the following information for your new achievement:
    • Achievement ID — Identifier for the achievement. This ID is used by your game when calling the GameCircle service to to request achievement info or award an achievement to a player. The identifier can contain alphanumeric characters (A-Z, a-z, 0-9) and underscores. This identifier is not displayed to players.
    • Title — Title for the achievement, limited to 50 characters. This value is displayed to players. You can’t change this value once the achievement is published.
    • Hide until earned — Flag indicating whether players can see this achievement before they’ve earned it.
    • Achievement XP — Maximum experience points (XP) awarded to a player when they earn the achievement. GameCircle rewards players with XP for their GameCircle profile when they earn achievements. Use this field to specify how much XP your achievement is worth. Value can be 0 to 100; the total XP for all published achievements in a game can’t exceed 1500. We recommend rewarding 1000 XP with the achievements in your launch title and reserving 500 XP for future additions. Once an achievement has been published, you can’t change the amount of XP it rewards.
    • Locked icon — Achievement image displayed to players who have not earned the achievement. This image is not displayed if Hide until earned is set to Yes. Click Change to select an image from your configuration’s image gallery or upload a new image file. Icon image file names cannot have spaces or certain special characters, such as parentheses. For information about designing this image, see “Create Achievement Assets” in Get Set Up for GameCircle.

    • Locked description — Tagline displayed to players who have not yet earned the achievement. This should be written as an imperative, for example: “Reach the oasis.” The description is not displayed if Hide until earned is set to **Yes.

    • Unlocked icon — Achievement image displayed to players who have earned the achievement. Click Change to select an image from your configuration’s image gallery or upload a new image file. Icon image file names cannot have spaces or certain special characters, such as parentheses. For information about how to design this image, see “Create Achievement Assets” in Get Set Up for GameCircle.

    • Unlocked description — Tagline displayed to players who have earned the achievement. This should be written in simple past tense, for example: “Reached the oasis.”
  4. Click Save if you have only one achievement to add. Click Save and add another to save the current achievement and create another achievement.

Add Leaderboards

If your game ranks players with leaderboards, define them here and upload the art assets Amazon GameCircle displays to present the leaderboards to players. You can define up to 50 leaderboards per game. If your game does not use leaderboards, skip this step and go to Step 5: Add Test Accounts.

If you have many leaderboards to add to a game, consider using bulk upload. With bulk upload you define your leaderboards in a CSV file that you upload to Amazon GameCircle.

You can add leaderboards for your game one at a time, or add multiple leaderboards using bulk upload.

To add a leaderboard:

  1. In the GameCircle configuration workflow, go to step 4: Leaderboards. On this page you’ll see a list of all leaderboards created for this configuration, including title and descriptions, languages information, and published status.

  2. Click Add a leaderboard. This window allows you to define a single leaderboard and save it.

    As an alternative, you can also use the dropdown button to select the bulk add tools for leaderboards and icons. With the bulk uploading, you can define multiple leaderboards (and optionally multiple language versions for each) in a CSV file and upload the file to GameCircle. Icon bulk uploading lets you drag and drop multiple image files to your configuration’s image gallery. For more info, see “Bulk Upload or Bulk Edit Leaderboards” in Manage Your GameCircle Configuration.

  3. Enter the following:

    • Leaderboard ID — Identifier for the leaderboard. your game uses the leaderboard identifier when it calls into the Amazon GameCircle service to submit player scores. The identifier can contain the characters: A-Z, a-z, 0-9, and underscores. This identifier is not displayed to players.

    • Title — Title for the leaderboard. This value is displayed to players. The title can be up to 25 characters long.

    • Leaderboard icon — Icon displayed to players to represent the leaderboard. Click Upload Hi-res Image to upload an image file. If you previously uploaded an icon, click Change to replace the existing icon with a new file. Icon image file names cannot have spaces or certain special characters, such as parentheses. For information about how to design this image, see “Create Leaderboard Assets” in Get Set Up for GameCircle.

    • Score units — Unit of measurement for the score. This value is displayed to players. The score unit should be plural nouns (such as coins, zombies, or points) or a combination of an adjective with a plural noun (such as golden coins or blue zombies). Round scores to whole numbers.

    • Score threshold — Maximum score allowed. Players who earn a score better than this value may be cheating and will not appear on the leaderboard.

    • Sort order — Order in which scores are to be displayed, ascending or descending. Select Highest scores first if the highest score is the best score for this leaderboard. Select Lowest scores first if the lowest score is the best score for this leaderboard.

  4. Click Save if you have only one achievement to add. Click Save and add another to save the current achievement and create another achievement.

Add Test Accounts

You can specify an Amazon GameCircle player as a test account for your game. When you do, Amazon GameCircle displays achievements and leaderboards that are in draft status to that player. This makes it possible to test new achievements and leaderboards before you publish them.

To find your GameCircle nickname on the Fire tablet, do this:

  1. On the device home screen, click Games.
  2. Click Menu.
  3. Click Profile. Your nickname will be displayed on this screen.

To add a test account

  1. If you are continuing on from Step 4: Add Leaderboards, go to the next step.

    If you are resuming work on a previously saved Amazon GameCircle configuration, do the following:

  2. Click Add a Player Account.

  3. Enter the Amazon GameCircle nickname of the player to specify as a test account and click add.

  4. Click Finish.