Migrating from OpenFeint to Amazon GameCircle

This article was re-printed with permission from Amazon Digital Services, Inc.

Overview

OpenFeint is familiar to many mobile game developers for enabling social networking within applications on iOS and Android. If you used OpenFeint in your own products and find yourself seeking an alternative now that it has been discontinued, Amazon GameCircle offers a comparable service on Kindle. GameCircle supports achievements, leaderboards, and cross-device game synchronization (via Whispersync for Games).

Updating an existing game to use GameCircle instead of OpenFeint involves registration on the Amazon Mobile App Distribution Portal and some relatively straightforward changes to the game code.

Registration

Like OpenFeint, GameCircle requires that you register your application in order to set up achievements and leaderboards, enable storage for your users’ data, and allow secure communication between your game and the GameCircle service. See Setting Up Amazon GameCircle for more information on how to complete this registration process.

Once your game has been registered with Amazon, you can import the GameCircle API into your application and begin the transition from OpenFeint calls to their GameCircle counterparts.

Initialization

To initialize OpenFeint, an OpenFeintSettings object is passed to OpenFeint.initialize(), along with an application context and delegate to handle callbacks:

1
2
3
4
5
6
7
8
9

// Set up the settings object.
OpenFeintSettings settings = new OpenFeintSettings(
“App Name”, “Product Key”, “Product Secret”, “App ID”,
options); // a HashMap of named objects

// Initialize OpenFeint.
OpenFeint.initialize(ctx, // a Context
settings,
delegate); // an OFDelegate for callbacks

GameCircle initialization is similar, though authentication/authorization is handled through regular Android app signing. As a result, there’s no need to pass a product key or secret:

1
2
3
4
5
6
7
8
9
10
11

// Include the GameCircle features your game will use.
EnumSet<AmazonGamesFeature> agsGameFeatures = EnumSet.of(
AmazonGamesFeature.Achievements,
AmazonGamesFeature.Leaderboards,
AmazonGamesFeature.Whispersync);

// Initialize GameCircle.
AmazonGames agsGameClient = AmazonGamesClient.initialize(
getApplication(), // typically the same as ctx, above
agsGameCallback, // an AmazonGamesCallback object
agsGameFeatures);

The AmazonGamesCallback parameter is similar to the OFDelegate used by OpenFeint, providing your application an opportunity to handle the success or failure of the initialization call. If null, you’ll receive no notification of either. Here’s an example of how to create the callback object:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

// Create a callback to handle initialization result codes.
AmazonGamesCallback agsGameCallback = new AmazonGamesCallback() {
@Override
public void onServiceReady() {}

@Override
public void onServiceNotReady(AmazonGamesStatus reason) {
    switch (reason) {
    case CANNOT_AUTHORIZE:
      /**
      * The service could not authorize the client. This should only
      * occur if the network is not available the first time the game
      * attempts to connect.
      */
    case CANNOT_BIND:
      /**
      * The service could not authorize the client. This
      * should only occur if the network is not available the
      * first time the game attempts to connect.
      */
    case NOT_AUTHENTICATED:
      /**
      * The device is not registered with an account.
      */
    case NOT_AUTHORIZED:
      /**
      * The game in not authorized to use the service. Check your
      * package name and signature registered in the Developer’s
      * Portal.
      */
    case SERVICE_NOT_OPTED_IN:
      /**
      * The device is not opted-in to use the service.
      */
      break;

…

    default:
      break;
    }
}
};

Achievements

GameCircle achievements are set up using Amazon’s Developer Portal (see Implementing Achievements). After they have been defined there, your game code can refer to them by the Achievement IDs you specified. Using OpenFeint, this might look like:

1 2	Achievement achievement = new Achievement(“Achievement ID”); achievement.updateProgression( percentComplete, null );

With GameCircle, the process is very similar:

1 2	AchievementsClient acClient = agsGameClient.getAchievementsClient(); acClient.updateProgress(“Achievement ID”, percentComplete, userData);

Like OpenFeint, GameCircle expects completion percentages to be floats 0.0f – 100.0f. Values outside this range will be clamped to the nearest endpoint. Although OpenFeint generated an error if the values submitted didn’t increase monotonically, GameCircle simply ignores percentages less than the user’s current completion amount.

Retrieving metadata about achievements is also similar between OpenFeint and GameCircle. Both use callbacks to retrieve the information asynchronously. Using OpenFeint:

1
2
3
4
5
6
7

final Achievement achievement = new Achievement(“Achievement ID”);
achievement.load(new Achievement.LoadCB() {
@Override
public void onSuccess() {
// Achievement data fields now accessible
}
});

GameCircle attaches the callback to a response handle object in a similar fashion:

1
2
3
4
5
6
7
8
9

AGResponseHandle<GetAchievementResponse> handle =
                              acClient.getAchievement(“Achievement ID”);
handle.setCallback(new AGResponseCallback<GetAchievementResponse>() {
@Override
public void onComplete(GetAchievementResponse result) {
    Achievement achievement = result.getAchievement();
    // Achievement data fields now accessible
}
});

Leaderboards

Like achievements, GameCircle leaderboards are initially configured using Amazon’s Developer Portal (see Implementing Leaderboards). Migrating your game’s leaderboards from OpenFeint to GameCircle is very similar to migrating its achievements. To submit a player’s score using OpenFeint:

1 2	Leaderboard lboard = new Leaderboard(“Leaderboard ID”); new Score(scoreValue).submitTo(lboard, null);

Likewise, the GameCircle version resembles the corresponding GameCircle achievement code:

1 2	LeaderboardsClient lbClient = agsGameClient.getLeaderboardsClient(); lbClient.submitScore(“Leaderboard ID”, scoreValue, userData);

Both OpenFeint and GameCircle provide a mechanism to retrieve metadata about the leaderboards associated with your game. Again, this data is obtained asynchronously, so callbacks are used to notify you when it becomes available. Using OpenFeint:

1
2
3
4
5
6

Leaderboard.list(new Leaderboard.ListCB() {
@Override
public void onSuccess(List<Leaderboard> leaderboards) {
// Leaderboard list now accessible
}
});

The GameCircle implementation is consistent with the way it handles other responses:

1
2
3
4
5
6
7
8

AGResponseHandle<GetLeaderboardsResponse> handle = lbClient.getLeaderboards();
handle.setCallback(new AGResponseCallback<GetLeaderboardsResponse>() {
@Override
public void onComplete(GetLeaderboardsResponse result) {
List<Leaderboard> lboards = result.getLeaderboards();
// Leaderboard list now accessible
}
});

Invitations

Invitations were not a supported feature of OpenFeint on Android, so there is no migration path to other platforms.

Whispersync for Games

Whispersync for Games is a feature of Amazon GameCircle and has never been available in OpenFeint. It provides a mechanism to persist arbitrary game data—not just achievements and scores—and synchronize it across multiple devices. This greatly improves the customer experience when replacing a lost or stolen device or if they simply have more than one. For more information on incorporating Whispersync for Games into your application, see Implementing Whispersync.

This article was re-printed with permission from Amazon Digital Services, Inc.
This site does business with Amazon Digital Services, Inc.

Migrating from OpenFeint to Amazon GameCircle

Latest Posts

Best Collaboration Tools for Database Developers

Nutcache versus Airtable | Developer.com

Java versus PHP

Advantages and Disadvantages of OOP in Java

Tips for Managing Developers

Related Stories

Advertisers

Menu

Our Brands