2011 • 41:39
iOS games can take advantage of Game Center, Apple's social gaming network. Learn the approach for adding Game Center to your games and understand the process of authenticating a player, updating leaderboards, and earning achievements.
Speaker: Allan Schaffer
Unlisted on Apple Developer site
Transcript
This transcript was generated using Whisper, it has known transcription errors. We are working on an improved version.
Hello, I'm Allan Schaffehr, the game technologies evangelist at Apple. Last year with iOS 4.1, we introduced Game Center, Apple's new social gaming network. Game Center enables the players in your games to track their best scores on a leaderboard, to compare their achievements, invite friends to play the game, and to start a multiplayer game through auto-matching. So in this presentation, I'll cover just the essentials of Game Center: authentication, leaderboards, and achievements, and the approach that you can use to integrate these features into your game. So let's get started.
So as I said, Game Center lets your game take part in an online social network provided with iOS 4.1 and above. It allows your players to post their scores and achievements to our online leaderboards, and you can integrate achievements to reward the player as they make progress through your game.
We also take your game and make it multiplayer so that your players can compete and communicate with each other online in real time. And there's a lot we do to help you with the promotion and discovery of your game. There's special badging on the App Store and a special area where we feature games using Game Center and their new releases.
Now, the functionality of Game Center is delivered in these three parts. The first is the Game Center app built into the OS. And this is the central starting point where your users will create an account and sign into Game Center and then can interact with other players. They can set a status message, invite other players to be their friends, and then see what games their friends have played recently, and compare their achievements and best scores with other players. They can also invite their friends to play a game and start a multiplayer game through auto-matching. The second piece is the Game Kit framework.
And this is what allows game developers to create apps that are going to work with Game Center. So this is where authentication is handled, new friend management, reporting and displaying scores, unlocking achievements, and multiplayer functionality, and so on. And then the third piece is the Game Center service. So this is an online service provided by Apple to perform player authentication, provide leaderboard and achievement data to your game, to carry out auto matching for multiplayer games and a lot of other services.
But so in this presentation, I'm really just going to focus on the essentials. I'm going to start with authentication. So we'll talk about player registration and how you perform the authentication within your game. Then we'll go on to talk about leaderboards, so how you submit scores and display your leaderboards to your users. The same then with achievements, how you define and submit achievement data and how you display those.
And then there's a few other pieces that I want to cover. I want to talk about how Game Center interacts with iTunes Connect, which is where you'll go to enable Game Center and it's where you define the metadata for your game. And then also talk about the Game Center Sandbox, which is a test environment that you can use before you release to make sure that everything is working right. But okay, so let's start with authentication.
So the concept here is pretty simple. Your players are going to sign into a Game Center account, either from the Game Center app or it can be done from within your game as well. And that account is what's going to identify that player, and that will be used later in leaderboards, in achievements, in friend requests, or if your game is multiplayer and if it uses voice chat.
So all Game Center games will start by authenticating the player, and we actually handle that whole process for you automatically. There's a couple of different scenarios that could come up. Normally, it may just be that this is a returning player who's signed into Game Center before, and in that case, when you authenticate, we just pop up a little welcome back dialogue, which goes away and then the player is straight into your game. Another possibility is that perhaps this is the first time they've ever signed into a Game Center game. Well, if that's the case, then we'll bring up this sign-in dialogue, where they can either sign in with an existing account or create a new account or cancel out.
Now, if they sign in with an existing account, then they'll be just straight into your game. But if they haven't created an account yet, then actually we will just bring up the entire creation process for you. All of this is handled totally automatically. You don't have to do any extra work for this. And then once they've created an account, they'll be straight on into your game again. And so the third possibility is... Perhaps when this dialogue came up, they may have chosen to cancel out.
And usually if they cancel, they'll just be straight into your game. But actually, if they cancel three times, then we will disable Game Center for them, so that they won't be asked to sign in anymore after that. They'll have considered to have been opted out. But then, once they've done that, they'll be straight into your game again. All right, so let's look at authentication from the development perspective. I want to cover the steps to perform authentication. I'll talk about how to handle errors and how authentication interacts with multitasking. And then I'll have a couple of recommended practices for you to follow.
So the steps are actually very, very simple. There's really three stages that we go through. First is that we'll check for Game Center support because there's some devices or some OS releases that of course don't support Game Center. So we'll want to check for that first. Then we'll request authentication using the GK local player object, which you see over here on the right.
All of authentication and all of Game Center really is centered around this object. This is where the player ID, the player's nickname, and their friends list comes from. And it's how you can tell if they're underage and if they've authenticated yet or not. So once we have requested the authentication, then we'll check the result. And based on that, either enable or disable the use of Game Center for the rest of this run of the app. So let's look at an example.
So here, first, what I'm going to do is check for the presence of some of the GK local player APIs. So I use NSClass from String and just see if it exists or not. Of course, if I were running on iOS 4.0, this would come back null. And so I would be able to know to disable the use of Game Center if that were the case.
Next, also here, I'm checking if the device is running iOS 4.1 or later. So checking the device version and comparing it to 4.1. Now the reason for this is actually because we released a version of Game Center, a preview version of Game Center to developers that ran on iOS 4.0.
And we have to make sure that that isn't the version that's being run here because it's no longer compatible with the online service. the device has to be running iOS 4.1 or above. But so, assuming both of those tests pass, now I can go on and actually request the authentication. So here I get a handle to the GKE local player object.
And here I'm calling local player authenticate with completion handler. And as an argument, I'm passing it a block. Now, I'll explain blocks in just a few moments, but the result that's going to come back from this is going to tell us whether the player is authenticated or not. And it will fill in the fields of the local player object.
So here I'm just checking if the local player is authenticated, then it's successful and I can go on into my game using Game Center features. Otherwise, I still want to go into the game, but I just don't want to use Game Center features. So I will disable posting scores to Game Center leaderboards. I won't try to query achievements and so on.
And just to continue with that thought, handling errors is really important for you with the authentication process because it just might not be successful. There's a couple of cases. There's three of them that I've listed here. One possibility is that perhaps you've made a mistake and that you haven't yet enabled Game Center in iTunes Connect.
Well, in that case, the authentication will give you back an error saying that the game is not recognized. Another possibility is that perhaps your device does not support Game Center, and specifically the iPhone 3G does not have Game Center support. So on that device, when you attempt to authenticate, you'll just get an error back saying GK error not supported.
And then third, as I said, perhaps the user has opted out. Well, if that's the case, then you'll just get an error back that they've canceled, and you should proceed accordingly. And really, in all three of these cases, the intention is that you should still provide a graceful fallback and proceed into the game, but just disable the Game Center features.
Allan Schaffer All right, so let's talk about how authentication interacts with multitasking. And the thing to keep in mind is that your authentication might not survive a trip of the app going into the background or being suspended and then coming back. So anytime that that happens, you actually have to re-authenticate.
And that's going to occur automatically in iOS 4.2 and above. But if you're running iOS 4.1, you have to start the authentication process over again. Allan Schaffer Now, another thing to keep in mind is that the player ID may have changed. Perhaps, actually, that might be the reason why your application was suspended. The player might have suspended your app, gone to the Game Center app, and signed in as a new player, and then come back to your game. Well, you have to handle that.
And if that occurs, really, you should just start a new game. But in either case, if you come back into the game after being suspended and you're unable to authenticate, well, just proceed with a graceful fallback. Just keep going with the game, but with your Game Center features disabled. Thank you.
Now, the last thing is just a tip. Something that we really think that you should avoid is using extra dialogues to customize the authentication process. Like I see a number of games that are doing something like this, where they're saying, "Hey, do you want to enable Game Center?" and they make the user say yes or no. Then if they say yes, then we go into the authentication process.
This is really something to avoid. We think that this creates a lot of confusion. And it's because this is either redundant or incorrect, depending on what the user has already done in the past. So they may have already authenticated. And if so, then you don't need to ask them whether or not to enable Game Center. The authentication process is just going to sign them in.
Or they may have already chosen to opt out, and you're just bothering them again with a new question. And what if they were to say yes? Well, Game Center has already been disabled system-wide. And so even if you say yes, it's not going to take them into it. They have to go into the Game Center app to re-enable it. So don't do this. Instead, just think of Game Center as a system-wide service that isn't intended to have all of this custom enable and disable behavior on a per-game basis.
Allan Schaffer But okay. Now, before we proceed into leaderboards and achievements, I want to talk about just a few fundamental concepts that are going to help you understand the use of the GameKit API. Allan Schaffer And the first of these is iTunes Connect and its interaction with the Game Center service. Allan Schaffer So a lot of game developers maybe only use iTunes Connect when they've finished with their game. They've done all of the coding, and now it's just time to upload the game to the App Store.
Allan Schaffer So that's not how it works with Game Center. You actually need to go into iTunes Connect up front to enable Game Center for the app and to set up all of the metadata for your leaderboards and for your achievements. Allan Schaffer And once you've released multiple versions to also specify the compatibility between different versions of your game if you support multiplayer. Allan Schaffer So that's one important fundamental to keep in mind.
So the second thing is that you should really program this API asynchronously. So all of the API is designed to send messages to the Game Center service and then receive back responses asynchronously. And all of that is implemented using blocks as callbacks, or we call these completion handlers in the API.
So here's an example. When your game starts out and it's going to send a message to the Game Center service asking it to authenticate the player, that message gets sent, and then the Game Center service is going to respond back, and the response will be received by your completion handler.
So this is something that we use all over in the GameKit API. So in this case here, I have some other object that's going to perform some action, send that request to the Game Center service, and then I'll receive a response back in my completion handler. So here I invoke object, do some action with completion handler, and here's the block that's going to be invoked. Now it's being passed back in NSAir, and this is in common with most of the Game Center APIs, that if we receive an error, then we'll go off and handle it.
Otherwise, if there's no error, then it generally means that that action was completed. And then the third fundamental that I just want to mention is the Game Center sandbox. So this is a pre-release test environment that you can use during your development to test your game's interaction with Game Center.
So this is going to duplicate the functionality of the live Game Center service. You'll have the same iTunes Connect metadata, meaning you'll have the same achievements and leaderboard set up, but it's a different Game Center server, so the data in those achievement lists or the data in that leaderboard will be independent.
And there's also separate accounts, so just accounts for you and your beta testers to use. So which environment are you using at any given time? Well, just the rule of thumb to understand is that any game that is in development is going to be using the sandbox. So that's your development builds, any builds that are done using the simulator, or any ad hoc builds that you distribute to your beta testers.
And once a game goes live and your users are downloading it from the App Store, well, then that version of the game is going to be using the production system. So that's the production server. Okay, so now let's talk about accounts. Just bear in mind that you have separate accounts between the sandbox environment and your production environment. Now, you could use the same login and password between both of these. I do that.
But a tip is if you are using the same login and password, it can sometimes get confusing as to which environment you're actually in. So choose different nicknames because that's what the Game Center app will display to you, and that's also what's displayed in the "Welcome Back" dialog. So just for example, if I was Apollo in production, maybe I should change my name to be Apollo Sandbox when I'm in the sandbox environment, just so I can keep them straight.
Now, a note about switching back and forth between sandbox and production. If you want to go to the sandbox, you're currently in production. All you have to do is run any game that's going to use the sandbox, run any game that's still in development. You'll be prompted to enter your sandbox login and password, and then you'll be straight into the game.
But if you're currently in the sandbox and you want to get out of it and go to production, then there's a process you have to go through. You need to go to the Game Center app and tap the account ribbon, and it'll bring up a dialog to let you sign out. And then after you've signed out, still within the Game Center app, enter your production login and password, and then sign back in again. And now you'll be back into the production environment. With that done, let's change gears and talk about... Leaderboards.
And the concepts of leaderboards are very simple. This is a list of all of your players' best scores. You define how scoring is done in your game. So it can be the most points, or the best time, or the highest level. It can be sorted up or down.
And what leaderboards really do is increase the player engagement and encourage more competition between players in your game. Everybody wants to look at the scores that they're scoring. So you can look at the scores that your friends have achieved and scores that are at the top of the leaderboard and see if they can beat those. So now let's look at a couple of features of our leaderboard API.
You can either use our standard built-in interface or present your own custom UI. We also provide filters either by time, today, this week, or all time, or by audience. So you can look at just the leaderboard entries from your friends, or you can see all the players in the game.
There's a variety of different score types and score formats that we support. So your scores can be ints or floats or times. They can have a number of decimal places and so on. And we support up to 25 different leaderboards in Game Center. So you can have at the same time a leaderboard for the best score, but also maybe another one that tracks the best time.
So let's look at leaderboards from the perspective of the developer. I'm going to talk about how you define leaderboards and report a score. Then we'll get into how to present the leaderboards, either with the built-in UI or querying the data yourself and presenting it in your own custom UI. And at the end, I'll have a couple of recommended practices.
So here's the data that you'll need to define your leaderboards in iTunes Connect. We'll start out, we'll give each leaderboard a name and an ID that we'll use in the code anytime we want to send data to this leaderboard or query its values. Then there's a number of different pieces of metadata. So here you set the score type. So here I've chosen integers. Also the sort order for the scores in this leaderboard, either ascending or descending. Here I've chosen descending.
And then a series of fields which are localizable for the language, the display name, the score format, and a suffix. So here I've just chosen English. When this is displayed, it's going to call this leaderboard top scores, and scores will be presented using the American standard for presenting large numbers. Then the suffix, singular, is going to be point, and plural will be points.
But these last few fields can also be localized. So here I have German, we support simplified Chinese, and so on. Now, all of this data gets defined in iTunes Connect and just lives up in the cloud, and your application then uses it when it's using Game Center by indexing it through that ID.
Now, a couple of tips as you define that data. The first has to do with the sort order. So we see a number of developers making this mistake from time to time. So a descending leaderboard is one that has the highest scores at the top, and then as you go down the ranks, the scores are decreasing. So that's appropriate for like a high scoreboard. An ascending leaderboard has the lowest scores at the top, and so that's appropriate for a leaderboard that wants to show, for example, the shortest amount of time, the lowest score.
And the other tip has to do with the suffix that's going to be displayed. Just note that we don't add any leading space between this, so that when it's presented to the user, if you want a space between the number and the suffix, you need to add it yourself.
Okay, so now let's talk about reporting a score. There's really three steps that we're gonna do here. The first is that we create a GK score object and initialize it and set the value. Then we'll report that score to Game Center and then we finally check for errors and handle those if necessary.
And all of this is gonna be centered around this GK score object that you see here on the right hand side. You set the category, that's gonna be the ID of the leaderboard that you wanna submit it to, and the value. And then once you've done that, you can report that score to Game Center. So here's an example of that. Here I'm creating a GK score object and initializing it with the ID of the leaderboard that I was just showing you a moment ago.
Here I set its value. The value is a 64-bit integer, so here I'm just setting it to some value, to some score. And I then report that score to Game Center and give it and pass along with it a completion handler that'll be called when I get a response back.
The completion handler will be called and passed in NSERR. And if there is one, then we'll save the score for later. I'll talk about that in just a moment. But otherwise, if there's no error, then we know that this score was submitted successfully and it should now show up on the leaderboard if it's the player's best score.
So now let's talk about that case where an error might happen. It's really vital that you handle any errors that occur during score submission. And it can happen for a variety of different reasons. There might be a networking failure so that the score wasn't received by Game Center.
Or maybe there's some kind of a mistake. The player hasn't been authenticated or the score wasn't set. Now, in all of those cases, you need to handle that error. But let's look a little more closely at the communications failure case. What you really should do then is to save the score and resubmit it later. Perhaps the next time your application starts up, you have a connection on that later attempt.
And something that makes this really easy is the fact that the GK score object conforms to the NSCoding protocol. So it's really simple for you to just take a score and archive it away and then bring that back the next time you run your app. But one thing to keep in mind with that is how to limit cheating.
So cheating could occur if somebody modifies your saved scores file. And then the next time you run your app, you unpack that and just submit it back to Game Center. So you should take some steps to try to limit that. A few options that you might explore are adding a checksum into the file or a hash to the score. Or also now, Game Center will limit score submissions to known valid amounts if you enter that data into iTunes Connect. You can say something like, "No score greater than 100,000 is valid." And any score submissions that you submit, score submissions higher than that will just be dropped.
Okay, so now let's move on to how to display leaderboards. And I'll start with displaying them using the standard UI. So this is actually really simple. We have a built-in class called the GK Leaderboard View Controller. You see it over here on the right-hand side. So all you have to do is create one of these objects and set its properties. You tell it which leaderboard you want to display. You tell it the time scope that you want to see, either today, this week, or all time. And you set a delegate for when it gets dismissed. And then you present this modally using your root view controller.
Okay, so here I'm creating a view controller object and initializing it. And I set the category to the same leaderboard that I showed you earlier. I set its time scope, in this case, to all time, and set the delegate to myself. Now I present that modal view controller.
And then it's going to come up and display the leaderboards to the user, and there'll be a button to dismiss it. And once the user presses that button, this delegate is going to fire of leaderboard view controller did finish, and that's where I can dismiss the view controller.
Okay, so that's all there is to it for displaying leaderboards using the standard UI. Now, if you want to display leaderboards using your own custom UI, then you need to query the data out of them yourself. And we provide you the functionality to do that. You can query data from Game Center programmatically. So some typical queries that you might do for this are, for example, the top 10 scores, or you might query, say, ranks N through N plus 20 on the current leaderboard. Or you might. As for the ranks for a certain list of player IDs.
Now, in each of those cases, you'll submit a query to Game Center, and the results are going to be returned to you asynchronously in a completion handler. There are a few expectations that we have about this. We expect that you're going to query a relatively small range and with relatively low frequency.
Something you should not try to do is query your entire leaderboard. For one thing, it could be huge, and that would be a very poor game. And that would be a very poor game. user experience.
[Transcript missing]
The second thing is to support archiving. So in case of any error, you really need to check for the error and then save the scores for later resubmission, perhaps when your application starts back up again.
[Transcript missing]
We also have the idea of partial progress for achievements from 0% to 100%. And this is really useful for achievements like the one where you've defeated 50 enemies or things along those lines, where you can show the player just the kind of progress that they have made towards earning that achievement.
We also have support for hidden achievements, so that you can have certain achievements that only reveal themselves when you decide to reveal them to the player. And this is something that you can either use for hidden secret rewards, or maybe you just have in-app purchases, for example, that unlock new levels in your game, and you have achievements associated with those levels.
You might only want those achievements to become visible if the user has made that particular purchase. And then finally, achievements in Game Center earn the player a number of points. And I'll get into that in just a little bit more detail here. So as I say, the player earns points for completing an achievement. They get from 1 to 100 points for each achievement. And of course, you control the design of this. So more difficult achievements in your game should generally earn the player more points.
You have a maximum budget of 1,000 points total for your entire game. So be sure to leave headroom for future expansion of your title, just in case at some point you want to add more achievements and have more points. You need to make sure that there's still some available for that. Or perhaps you might add new levels or, again, you might get feedback from your users with new ideas for new achievements and you want to be sure that you have the headroom available to still add those.
All right, so let's get into achievements now from the point of view of the development. So first I'll talk about how you define achievements in your game, then how you can report achievement progress and display that to the user, and then finally how you can programmatically query the achievement progress and present that in a custom display. And then finally at the end, some recommended practices.
So just like with leaderboards, there's some things you'll need to define in iTunes Connect. So here's an example of that here. You'll give each achievement a name and an ID. The ID is what you'll use in the API to reference this achievement. You tell us whether or not the achievement is hidden. Most of the time they're not. You give the achievement a point value, and then some localized fields per locale. So here I've given it the title Master Warrior, and you earn this achievement if you defeat 50 enemies.
And the description of it after you've earned that achievement is defeated 50 enemies. And you'll also see this image show up. Now you take all of that and enter it into iTunes Connect, just like with leaderboards, and that lives up in the cloud and is then accessed by your application.
[Transcript missing]
Now, to display achievements to the user, we either have the standard UI or you can query achievements programmatically. So let's look at the standard UI first. And this is going to be, again, exactly the same thing as you saw with leaderboards, but now using the achievement view controller.
So here it's very simple. You just create a GKEachievementViewController object, you set its delegate for dismissal, and then you'll present this modally on your root view controller. So here's the code for that. So the first thing I'm doing here, I'm creating that achievements view controller, I set that delegate, and then I present it modally. And then when the user presses done, this delegate method is going to fire of achievementsDidPressDismiss. And that's where I can dismiss that view controller.
So that's very, very, very simple. All right, next let's talk about how you can query achievement data from Game Center. There's really two common cases where you might want to do this. The first is that when your game starts up, you probably want to query Game Center to load all of that player's current achievement progress. They may have switched devices, or this might be a new player and you just haven't seen them before, where you should query that data from Game Center to see if they've already made any progress through your application.
The second case is if you just want to present a custom achievements display. You're going to need to get all of the achievement data out of Game Center so that you can present that to the user. And for both of those, there's two classes that are involved that are going to give you arrays of data back. And so the first is the GK achievement class, which is what you just saw for reporting an achievement.
You can also query Game Center for the list of all of the achievement progress that this player has made. And it's going to come back as an array of GK achievements. So you can see here, each achievement has an identifier, a percent complete. It'll tell you whether or not it's been completed, whether it's hidden. And then if this is a query, it'll also give you back the date that it was reported to Game Center.
But so that's all of the achievements for the current player. You also, if you're going to present a list of all of the achievements in your game, you can also use the GK achievement description array. And that's the objects on the right-hand side here, which is the GK achievement description array. So this is an array corresponding to all of the data that you've defined in iTunes Connect for all of your achievements.
So each of these now will have an identifier, a title, the description before and after the achievement is earned, the number of points that that achievement has value of, and whether it's hidden and its image. array of those, you can present a big list of all of the achievements in your game.
[Transcript missing]
Now, after startup, that's a great place for you to load all of the player's latest achievement progress in case they had previously played your game on another device. Also, it's a good time for you, if you had any achievements that previously had failed submissions, that's a good time now to resubmit them to Game Center.
And then during gameplay, there's some things you should do. Really only report achievement progress to Game Center if it changes. You don't need to go back and re-report the same achievements over and over again. And then just like with leaderboards, you should always check for errors when you're submitting the achievements. And if there is one, save it to be resubmitted later.
All right, so I've covered a lot of ground here. I've gone into detail about player authentication, submitting scores and displaying leaderboards, and how to define, submit, and display achievements. And I also discussed how the Game Center service interacts with iTunes Connect and the Sandbox. But really, that's just scratching the surface. I didn't cover multiplayer or voice chat, and Game Center also has some great features for interacting with friends.
So if you have questions about those things, or any of the content that I've presented here, here's my contact information. And we also have some great documentation available in the iOS Dev Center, and you can come talk to us in the developer forums as well. So I hope to see you in Game Center. Thanks for watching.