Initializing GameCircle in Your Android or Fire OS Game

Introduction

These instructions are for developers who develop their Android applications by using the Eclipse IDE. If you don’t already have Eclipse, download and install the Android Developer Tools (ADT) Bundle. Otherwise, you can follow the instructions for setting up an existing IDE.

To use the GameCircle SDK you will need to have the Android 2.3.3 (API 10) platform installed. Follow the instructions for Adding Platforms and Packages.

Initialize GameCircle by following Steps 1-4 below. After initializing the GameCircle client in your code, you can add Whispersync for Games, Achievements, and Leaderboards to your game.

Step 1. Get the GameCircle Library and Include it in Your Workspace

After you Download the Amazon Apps & Games Services SDK and extract the GameCircle distribution package to disk, import the Eclipse project it contains:

  1. Click File, click Import, and then click Android.
  2. Click Existing Android Code Into Workspace, and then click Next.

    Select import source window
    Select import source window
  3. Inside the unpacked SDK, browse to the directory that includes the GameCircle SDK, and then click Finish.

A new project will appear in your workspace called GameCircleSDK. Eclipse automatically determines the name of the project based on the name in the .project file. Once imported, the project shows up in your workspace under the same name, as shown here:

Project Explorer
Project Explorer

This project name may be different if you add the library to your workspace through some other process. Adjust these instructions as necessary, but note that the manifest changes won’t be affected, because manifest changes are independent of the library’s project name.

Step 2. Add a Reference in Your Project to the GameCircle Library

After importing the GameCircle SDK into your workspace, add it as a dependency of the application project in which you will use it. This step enables you to compile your project against the GameCircle library, and ensures that the GameCircle jars are packaged with your APK.

  1. Go to your project properties.
  2. Click Android, and in the Library section near the bottom of the screen, click Add.
  3. Select GameCircleSDK.

    Properties window
    Properties window
  4. Click OK.

Step 3. Update your AndroidManifest.xml File

Open your AndroidManifest.xml file and add the following lines:

  • The Before section code enables your game to connect to the GameCircle web service endpoint.
  • The Inside section code implements the GameCircle user interface display in your game (for achievements and leaderboard UI), and implements the Login with Amazon service, which enables more than 200 million active Amazon customers to securely and simply login to your game.

Before

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Inside

Choose the sample code below corresponding to the Android API level that you are targeting. The samples are different because, beginning with Android 3.0 (API level 11), the Android 2D rendering pipeline supports hardware acceleration. For more information about support for hardware acceleration at different API levels, see Hardware Acceleration. For more information about the Android API levels required for GameCircle games, see “What are the system requirements for GameCircle games?” in Frequently Asked Questions.

When targeting Android API 11 and above:

<activity android:name="com.amazon.ags.html5.overlay.GameCircleUserInterface"
android:theme="@style/GCOverlay" android:hardwareAccelerated="false"></activity>
<activity
  android:name="com.amazon.identity.auth.device.authorization.AuthorizationActivity"
  android:theme="@android:style/Theme.NoDisplay"
  android:allowTaskReparenting="true"
  android:launchMode="singleTask">
  <intent-filter>
	 <action android:name="android.intent.action.VIEW" />
	 <category android:name="android.intent.category.DEFAULT" />
	 <category android:name="android.intent.category.BROWSABLE" />
	 <data android:host="YOUR_PACKAGE_NAME_HERE" android:scheme="amzn" />
  </intent-filter>
</activity>
<activity android:name="com.amazon.ags.html5.overlay.GameCircleAlertUserInterface"
android:theme="@style/GCAlert" android:hardwareAccelerated="false"></activity>
<receiver
  android:name="com.amazon.identity.auth.device.authorization.PackageIntentReceiver"
  android:enabled="true">
  <intent-filter>
	 <action android:name="android.intent.action.PACKAGE_INSTALL" />
	 <action android:name="android.intent.action.PACKAGE_ADDED" />
	 <data android:scheme="package" />
  </intent-filter>
</receiver>

When targeting Android API 10 and below:

<activity android:name="com.amazon.ags.html5.overlay.GameCircleUserInterface"
android:theme="@style/GCOverlay"></activity>
<activity
  android:name="com.amazon.identity.auth.device.authorization.AuthorizationActivity"
  android:theme="@android:style/Theme.NoDisplay"
  android:allowTaskReparenting="true"
  android:launchMode="singleTask">
  <intent-filter>
	 <action android:name="android.intent.action.VIEW" />
	 <category android:name="android.intent.category.DEFAULT" />
	 <category android:name="android.intent.category.BROWSABLE" />
	 <data android:host="YOUR_PACKAGE_NAME_HERE" android:scheme="amzn" />
  </intent-filter>
</activity>
<activity android:name="com.amazon.ags.html5.overlay.GameCircleAlertUserInterface"
android:theme="@style/GCAlert"></activity>
<receiver
  android:name="com.amazon.identity.auth.device.authorization.PackageIntentReceiver"
  android:enabled="true">
  <intent-filter>
	 <action android:name="android.intent.action.PACKAGE_INSTALL" />
	 <action android:name="android.intent.action.PACKAGE_ADDED" />
	 <data android:scheme="package" />
  </intent-filter>
</receiver>

Step 4. Initialize and Release the GameCircle Client

The GameCircle client integrates with your activity’s _onResume()_ and _onPause()_ lifecycle events. We recommend that you follow these practices to ensure accurate time-played information and proper resource management.

Initialize the GameCircle Client

The client should be initialized during _onResume()_. Specify the following parameters in the initialize method:

  • A callback function to handle initialization result codes GameCircle initialization happens asynchronously. This code manages events that may occur when you call _initialize()_.
  • The GameCircle features in your game Your customers see a list of GameCircle features in the welcome message when your game starts and in your game’s sign in page. To avoid confusion, show only the features you actually support.
//reference to the agsClient
AmazonGamesClient agsClient;

AmazonGamesCallback callback = new AmazonGamesCallback() {
        @Override
        public void onServiceNotReady(AmazonGamesStatus status) {
            //unable to use service
        }
        @Override
        public void onServiceReady(AmazonGamesClient amazonGamesClient) {
            agsClient = amazonGamesClient;
            //ready to use GameCircle
        }
};

//list of features your game uses (in this example, achievements and leaderboards)
EnumSet<AmazonGamesFeature> myGameFeatures = EnumSet.of(
        AmazonGamesFeature.Achievements, AmazonGamesFeature.Leaderboards);

@Override
public void onResume() {
    super.onResume();
    AmazonGamesClient.initialize(this, callback, myGameFeatures);
}

When testing your GameCircle integration, if CANNOT_INITIALIZE _AmazonGamesStatus_ is returned to your callback function by _initialize()_, you may not have correctly registered the package name and signature of the game build. Review the steps in Setting Up Your GameCircle Configuration, and then try again.

Enumerate Only the GameCircle Features Your Game Uses

When initializing the GameCircle client, the enumeration of GameCircle features in your game must match one of the following examples:

//achievements only
EnumSet<AmazonGamesFeature> myGameFeatures = EnumSet.of(
       AmazonGamesFeature.Achievements);

//leaderboards only
EnumSet<AmazonGamesFeature> myGameFeatures = EnumSet.of(
       AmazonGamesFeature.Leaderboards);

//Whispersync only
EnumSet<AmazonGamesFeature> myGameFeatures = EnumSet.of(
       AmazonGamesFeature.Whispersync);

//achievements and leaderboards
EnumSet<AmazonGamesFeature> myGameFeatures = EnumSet.of(
       AmazonGamesFeature.Achievements, AmazonGamesFeature.Leaderboards);

//achievements and Whispersync
EnumSet<AmazonGamesFeature> myGameFeatures = EnumSet.of(
       AmazonGamesFeature.Achievements, AmazonGamesFeature.Whispersync);

//leaderboards and Whispersync
EnumSet<AmazonGamesFeature> myGameFeatures = EnumSet.of(
       AmazonGamesFeature.Leaderboards, AmazonGamesFeature.Whispersync);

//achievements, leaderboards, and Whispersync
EnumSet<AmazonGamesFeature> myGameFeatures = EnumSet.of(
       AmazonGamesFeature.Achievements, AmazonGamesFeature.Leaderboards, AmazonGamesFeature.Whispersync);</pre>

Release the GameCircle Client

When an activity goes into a pause state, developers must release the GameCircle client. Releasing the client stops GameCircle background threads from continuing to run and pauses the measuring of the customer’s time played.

@Override
public void onPause() {
    super.onPause();
    if (agsClient != null) {
        agsClient.release();
    }
}

Shut Down the GameCircle Client

Call the shutdown() method when you’re done interacting with the GameCircle SDK. Any subsequent interactions with the SDK will require a new call to agsClient.initialize().

Take the Next Step: Add GameCircle Features to Your Game

Now that you’ve initialized GameCircle, you can add Whispersync for Games, Achievements, and Leaderboards to your game.