Setting Up Unity and Integrating GameCircle Features in Your Games

Introduction

Amazon offers Unity plug-ins that enable you to quickly set up and deploy key Amazon services:

  • GameCircle API enables leaderboards, achievements, and Whispersync for Games 2.x.
  • In-App Purchasing (IAP) API 2.0 enables entitlements, consumables, and subscriptions for games.

The Unity plug-ins are free as part of the Amazon Mobile App SDK.

What is Unity?

Unity is a cross-platform game development engine from Unity Technologies. It enables you to create rich, interactive 3D experiences by providing ways to assemble your art and assets into scenes and environments, add physics, and simultaneously play-test and edit games. When you’re finished building and testing, the Unity engine creates a binary for your chosen platform, such as an Android APK that you can publish on Amazon Appstore.

Where can I get Unity?

Download Unity from the Unity website. The base version is free, which makes it easy to give it and the Amazon plug-ins a spin and get your next game to market in record time.

Using the GameCircle Unity Plug-In

Using the IAP Unity Plug-In

Setting Up Unity

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:

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");
    }

Step 5. Add your API key

Adding an API key is necessary only for local testing.

  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.

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) {

    }

Additional Resources