Home > APIs > Engage > GameCircle

Setting Up Unity and Integrating GameCircle Features in Your Games

Overview

Follow these steps to set up your Unity environment and then to integrate GameCircle features in your 2D or 3D game in the Unity IDE.

You can set up GameCircle in Unity for cross-platform deployment for Android and Amazon Fire devices. Choose the steps that match your deployment scenario:

To view the full GameCircle API documentation for Android configuration and initialization, follow these links:

Setting Up Unity

Step 1. Import the GameCircle Unity Package

When you import the GameCircle Unity package, Unity will override existing files in your project with those in the package. Before importing the GameCircle Unity package, review the list of included files and compare this list with your current project to check for overlap. If a file exists in both your project and the package, verify that any changes you have made locally are backed up somewhere outside of your project. After you import the GameCircle package, use your favorite file merging software to compare and merge the differences between the file in the package and the file you had backed up locally.

  1. In Unity, click Assets, click Import Package, and then click Custom Package…
  2. Select the GameCircle Unity plugin package.
  3. Import the GameCircle Unity Package.

Step 2. Add the GameCircleManager to Your Scene

GameCircleManager is a Unity GameObject with an attached script that sets it to be persistent between level loads. GameCircle requires this object to be in your scene so that the libraries for GameCircle can communicate with Unity. GameCircleManager receives messages from the GameCircle SDK and forwards them to the appropriate GameCircle Plugin functions.

  1. In Unity, click Assets, click Plugins, and then select GameCircleAndroid/prefabs/.
  2. Add the GameCircleManager game object to your scene.

Step 3. Check if the Amazon GameCircle Service is Ready

This code checks IsServiceReady before accessing Gamecircle features and functionality. This will return False on unsupported platforms.

bool isServiceReady = AGSClient.IsServiceReady();

Step 4. Initialize GameCircle

In one of your initialization scripts for your game, initialize GameCircle:

    ...
        AGSClient.ServiceReadyEvent += serviceReadyHandler;
        AGSClient.ServiceNotReadyEvent += serviceNotReadyHandler;
        bool usesLeaderboards = true;
        bool usesAchievements = true;
        bool usesWhispersync = true;

        AGSClient.Init (usesLeaderboards, usesAchievements, usesWhispersync);
    ...

    private void serviceNotReadyHandler (string error)    {
        Debug.Log("Service is not ready");
    }

    private void serviceReadyHandler ()    {
        Debug.Log("Service is ready");
    }

Note: 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, in AGSClient.Init initialize only the features that you actually support.

Step 5. Add your API key

  1. In Unity, click Assets, click Plugins, click Android, and then select assets.
  2. Open api_key.txt and replace the text with your API key.

    For additional help, see the instructions for generating an API key in Create a GameCircle Configuration.

Step 6. Add your package name to the game manifest

If you are using the manifest provided by GameCircle, update the AuthorizationActivity and add your package name to the data element, as shown here:

<activity
    android:name="com.amazon.identity.auth.device.authorization.AuthorizationActivity"
    android:allowTaskReparenting="true"
    android:launchMode="singleTask"
    android:theme="@android:style/Theme.NoDisplay" >
    <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="<put your packagename here>"
          android:scheme="amzn" />
    </intent-filter>
</activity>

Step 7: Set the minimum API level for your build

  1. In Unity, click File > Build Settings.
  2. Ensure that Android is the current platform, and click the Player Settings button. Player Settings is displayed in the Inspector. 
    (If Android isn't the current platform, select it in the list and click the Switch Platforms button.)
  3. In Player Settings, expand the Other Settings section.
  4. Under Identification, set the field Minimum API Level to the following: "Android 2.3.3 “Gingerbread” (API level10)".

 

Integrating GameCircle Features in Your Game

The following sections demonstrate how to implement Whispersync for Games, leaderboards, and achievements in your game.

Note: To view the full GameCircle API feature documentation for each feature, follow these links:

The GameCircle Unity plugin is provided with sample logic to help guide you in implementing GameCircle features. These samples are in the folder Assets/Plugins/AmazonGameCirclePlugin/Example. Run the included AmazonGameCircleExample.unity scene to try out GameCircle features.

Implement Whispersync for Games

High Value Example

After initializing Amazon GameCircle in your Unity game, you can set a high number in Whispersync for Games.

If(AGSClient.IsServiceReady()) {
    using(AGSGameDataMap dataMap = AGSWhispersyncClient.GetGameData()){
        using(AGSSyncableNumber myHighNumber = dataMap.GetHighestNumber("myHighNumber")){
            myHighNumber.Set(1000);
        }
    }
}

Implement Leaderboards

Submit a Score Example

After initializing Amazon GameCircle in your Unity game, you can submit a score to a leaderboard.

    ...
If(AGSClient.IsServiceReady()) {

    AGSLeaderboardsClient.SubmitScoreSucceededEvent += submitScoreSucceeded;
    AGSLeaderboardsClient.SubmitScoreFailedEvent += submitScoreFailed;
    AGSLeaderboardsClient.SubmitScore("MY_LEADERBOARD_ID",1000);
}
    ...

    private void submitScoreSucceeded(string leaderboardId){

    }

    private void submitScoreFailed(string leaderboardId, string error){

    }

Implement Achievements

Update Example

After initializing Amazon GameCircle in your Unity game, you can update an achievement.

    ...
If(AGSClient.IsServiceReady()) {

        AGSAchievementsClient.UpdateAchievementSucceededEvent += updateAchievementSucceeded;
        AGSAchievementsClient.UpdateAchievementFailedEvent += updateAchievementFailed;
        AGSAchievementsClient.UpdateAchievementProgress("MY_ACHIEVEMENT_ID",50.0f);
}
    ...

    private void updateAchievementSucceeded(string achievementId) {

    }

    private void updateAchievementFailed(string achievementId, string error) {

    }