Using Game Center with PhoneGap

Leaderboards

I’ve been writing a game with every spare moment I have (using Cordova / PhoneGap) and really wanted to use the iOS Game Center leaderboard functionality.

Game Center provides a familiar environment for users to compare scores and achievements and challenge friends. Given that most iOS users already have an account and in iOS7 and they’ve improved it quite a bit, it seems silly implementing my own leaderboard server at this stage.

Adding Game Center support requires more than just simple code changes. To create a Game Center aware game, you need to understand these basics.

PhoneGap iOS Game Center

My Game Center plugin

A game center plugin didn’t exist for Cordova >= 3.0 or that supported the iOS7 API, so I wrote one, open source.

Install via the CLI

The below command will install all required code and dependencies (including the GameKit framework), do not reference any JavaScript in the HTML, it will be added as part of the cordova platform preparation.

1
$ cordova plugin add https://github.com/leecrossley/cordova-plugin-game-center.git

Basic usage

Auth

It’s recommended that authentication takes place as soon as the deviceready event has been fired (don’t ever attempt to use any plugin code before this, it won’t work). The plugin will then handle the various authentication scenarios (auto-login, signup via a native view controller etc).

1
gamecenter.auth(onSuccess, onError);

If there’s an issue, an error message object is passed back to the onError(message) function.

WARN: At the time of writing this, rejecting the gamecenter.auth() view controller 3 times in a row (during sign in), will block the app from ever using Game Center on that device. I learned this the hard way and had to reset my phone settings. Sad times.

Leaderboard

Submitting a score

Ensure the user has been (successfully) authenticated and the leaderboard(s) have been configured in iTunes connect (use the leaderboard identifier assigned there as the leaderboardId).

1
2
3
4
5
var scoreData = {
score: 100,
leaderboardId: "YOUR_ID"
};
gamecenter.submitScore(onSuccess, onError, scoreData);

Showing the native leaderboard

This is a “quick win” and launches the native Game Center leaderboard view controller for a given period and leaderboard. In other words, there’s no need to do any additional coding or user interface development to display a leaderboard.

The period options are “today”, “week” or “all”.

1
2
3
4
5
var criteria = {
period: "today",
leaderboardId: "YOUR_ID"
};
gamecenter.showLeaderboard(onSuccess, onError, criteria);

Note: the onSuccess() (and onError()) are called as the leaderboard is shown, not closed, so you can know if there’s an issue and handle it.

iOS version support

I’ve written the plugin to support both iOS 6 and iOS 7 (there are differences in the native implementation, yuck).

Source code

The plugin is open source (MIT Licence) and the full source code is available on github. Please log issues (ideally with pull requests ☺) on there.

The plugin has had a huge uptake already with 11 repo stars within 8 hours of pushing the code!