Using the GameCenter Adobe AIR native extension for iOS

With the GameCenter iOS AIR native extension from Milkman Games, you can rapidly add support for great social gaming features via Game Center on iOS devices. The GameCenter iOS extension API makes it easy to integrate leaderboards, achievements, and user authentication into your Adobe AIR app via a simple and familiar ActionScript 3 interface.

With the GameCenter iOS extension, you can:

• Submit scores and achievements to Game Center via ActionScript 3
• Show the native iOS Leaderboards and Achievements panels in your game
• Log users into Game Center and retrieve their name, ID, and other details
• Jumpstart development by exploring a complete sample application, ActionScript 3 documentation, and a getting started guide
• Use the iOS Game Center sandbox system for testing
• Deploy to all iPad, iPhone, and iPod Touch devices running iOS 4.1 or greater—and check if the device supports Game Center with one function call
• This tutorial provides details on getting started with the GameCenter extension. If you want to follow all the steps below, you'll need to purchase and download the GameCenter extension.

Before you can use Game Center in your game, you'll need to register the game in iTunes Connect. Follow these steps:

1. Log into the Apple Developer center at http://developer.apple.com and go to the iOS Developer area.
2. Click iTunes Connect on the right.
3. Click Manage Your Applications, and then click Add New App.

4. Select a default language and then type a Name and SKU Number for your application (see Figure 1). Under Bundle ID, click You Can Register A New Bundle ID Here, which will bring you to the Provisioning Portal.
5. In the Provisioning Portal, click New App ID (see Figure 2).

6. Type a description for your new app. For Bundle Identifier, type a unique name in the recommended scheme (like com.yourcompany.YourGameName).

Note: Take note of what you choose here, as you'll need to match it exactly later for Game Center to work.

7. Click Submit and close the Provisioning Portal. Back on the App Information page, select the Bundle ID you just created. If you don't see your new Bundle ID listed, refresh the page or cancel the operation and click New App again.
8. Click Continue.
9. Continue through the next couple of steps, entering the release date, pricing tier, version information, rating information, metadata, icons, screenshots, and other required data for your application. If you're just creating a test app, you can set the release date far in the future. At least one screenshot and icon are required to register an application. If you need some dummy images to test with, you can find them in the /tutorialimages folder included with the GameCenter extension package.
10. Click Save.
11. Click Manage Game Center (see Figure 3).

12. On the next screen, click Enable.
13. Under Leaderboard, click Set Up, and then click Add Leaderboard.
14. On the Add Leaderboard screen, select Choose under Single Leaderboard (see Figure 4).

15. Type a reference name for your leaderboard and a Leaderboard ID. The Leaderboard ID is the internal name for accessing the leaderboard from code. I typed airleaderboard for my ID, and it's what I'll use in this example. Whatever ID you choose, take note of it because you'll need it later to access Game Center from your app. Choose a score format and sort order that makes sense for your scoring system.

16. Under Leaderboard Localization, click Add Language (see Figure 5).

You can add as many localized languages as you'd like, but you only need one to start.

17. Type a Name for your leaderboard and select Integer for the score format (simple whole numbers.) The suffix singular is the descriptive term that follows a single value, and the suffix plural is for more than one (for example, I typed point and points respectively).
18. Click Save.

19. Click Save again, and then click Go Back to return to the management screen.
20. Under Achievements click Set Up.
21. Click Add New Achievement.
22. Enter a reference name, achievement ID, and point value for your achievement. Take note of the achievement ID, as you'll need it later to submit the achievement from ActionScript. I typed airachievement01, which I will use in the rest of this tutorial.
23. Click No next to Hidden to indicate that this is not a hidden achievement.
24. Click Add Language (see Figure 6).
25. Select a language and type a title, pre-earned description, and earned description for your achievement. For details on what these descriptions are for, click the question mark next to each field. You'll need to upload a 512 x 512 icon as well; if you need a test icon, you can reuse the one in the /tutorialimages folder.
26. Click Save to add the language.
27. Click Save again to add the achievement.
28. Click Go Back and then click Done.
29. Click View Details under Versions. Scroll down to the Game Center area, and click Enable For This Version (see Figure 7).

You're now all set up in iTunes Connect!

The next step is to add the com.milkmangames.nativeexetnsions.GameCenter.ane library to your project. (If you're not using Flash Builder 4.6 and later or Flash Professional CS6 and later, you'll need to add the GameCenterAPI.swc library instead.)

In Flash Professional CS6:

1. Create a new project of the type AIR for iOS.
2. Choose File > Publish Settings.
3. Click the wrench icon next to Script for ActionScript Settings.
4. Select the Library Path tab
5. Click Browse For Native Extension (ANE) File and select the com.milkmangames.nativeextensions.GameCenter.ane file

In Flash Builder 4.6:

1. Go to Project Properties (right-click your project in Package Explorer and select Properties).
2. Select ActionScript Build Path and click the Native Extensions tab.
3. Click Add ANE and navigate to the com.milkmangames.nativeextensions.GameCenter.ane file.

In FlashDevelop:

1. Copy the GameCenterAPI.swc file to your project folder.
2. In the explorer panel, right-click the SWC and select Add To Library.
3. Right-click the SWC file in the explorer panel again, select Options, and then select External Library.

You can start using the GameCenter extension with a few simple calls. See example/GameCenterExample.as for a full example that shows how to log in, check authentication, show leaderboards, submit scores and achievements, capture errors, and more.

Follow these steps to get started:

1. Import the API Classes:

2. Next, initialize the API and create an instance of the GameCenter object, with your stage:

3. Check if the device supports Game Center. Although AIR apps will run on iOS 4.0 and higher, Game Center is only available in iOS 4.1 and higher.

4. Log in to Game Center, and listen for the events that will tell you if the authentication was successful or not. Be sure to listen for the AUTH_FAILED event to avoid an uncaught error:

5. Once you're logged in, you can show the leaderboard for your game. Note that the leaderboard ID being passed in (in this case its "airleaderboard" ) must match the ID you created for the leaderboard in iTunes Connect. Also, you can listen for events to tell you when the leaderboard is shown, and when the user has closed the leaderboard window:

6. You can show the achievements for your game in much the same way:

7. When you want to report a new high score, you can use the code below. Be sure to listen for the success and fail events (you will have an uncaught error if you don't handle a failed submission):

8. You can submit achievement progress by calling reportAchievement() . Again, listen for the success and fail events. The first parameter is the achievement ID, which must exactly match an achievement you created earlier in iTunes Connect. The second parameter is the percent of the achievement completed—a value from 0.0 to 100.0.

9. You can reset the user's achievements like this:

For complete examples of all the available methods, see the GameCenterExample.as file in the /example folder.

In your application descriptor XML file, you need to specify a link to the extension and specify that you are using the AIR 3.1 SDK. For a working example, see example/app.xml.

1. If it is not already set, make sure your descriptor file references AIR SDK 3.1:

2. Include a link to the extension in the descriptor:

If you're using Flash Builder 4.6 or later, or Flash Professional CS6 or later, and have added the GameCenter extension library as described above, then you can compile as you usually do directly from your IDE. If not and you are building your app with the extension from the command line, then you'll need to specify the directory containing the com.milkmangames.nativeextensions.GameCenter.ane file.

Here is an example build command line:

Important: Your app will not be able to interact with Game Center before it is available in the App Store unless you are running in Sandbox mode.

To start in Sandbox mode:

1. Be sure the .mobileprovision file that you used to build your IPA file was the development version of this file. (You can and should use the distribution version of the .mobileprovision file when building your final app to upload to the App Store.)
2. Log out of Game Center completely before starting your test app for the first time.
3. Start your app. When prompted to log in to Game Center, select Create New Account. Do not try to login with your real Game Center account.
4. Enter any information you want for this new account. It will be a test account in the iOS sandbox, so you just need to remember the email address and password (the email address can be made up.)

If you've done it correctly, the Welcome Back window that iOS shows you when you login should say Sandbox on it (see Figure 8).

Use the tips below to troubleshoot any problems you may be having with the GameCenter extension:

• If you're having trouble authenticating the user, ensure you have followed the instructions above for using Sandbox mode.
• If iOS says your app is not recognized by Game Center, verify that the bundle id in iTunes Connect exactly matches the application id in your AIR manifest XML file.

• If achievements are being reported, but you don't see a banner reporting that the achievement was won, you'll need to add one yourself in the GameCenterEvent.ACHIEVEMENT_REPORT_SUCCEEDED handler. iOS 4 does not have a built-in won achievement banner.

• If you're stuck in Sandbox mode and want to go back to your regular Game Center account, log out of Game Center, close and uninstall your AIR app, force close the Game Center application, restart Game Center, and log in with your actual personal account. When you run your test app (built with the development version of your .mobileprovision file), you will re-enter Sandbox mode.
• If your app is halting after making a call, run in debug mode to see if there are any errors. Make sure you are capturing all GameCenter extension events for the calls you are making. You can check the GameCenterEvent.message property to see what went wrong.

• If you're submitting scores successfully, but don't see them in the leaderboard:
  • Make sure the leaderboardID you're using exactly matches the one you typed in iTunes Connect.
  • Switch to the This Week view and then back to All Time.
  • Logout and log back in with a new Game Center sandbox account, and then submit a new score. Occasionally the sandbox fails to show the scores when there is only one user-submitted score. This does not happen in production. If this is the problem, the preceding steps will resolve it.
• If Game Center stops trying to login after awhile, uninstall your app, log out of Game Center, and force close the Game Center app. iOS only allows you to ask the user to login three times unsuccessfully before it stops asking. The preceding steps reset this behavior.

Now that you have the GameCenter extension up and running, you may want to explore the ActionScript 3 documentation or check out the other tools from available from Milkman Games.