Accessing the Play Games Services APIs in Your iOS Game

The Google Play games services SDK for iOS simplifies how you implement communication with the Google Play games services by providing these features:

  • Authentication and authorization. Once authorized, the SDK takes care of adding OAuth 2.0 headers to all network requests, detecting OAuth 2.0 errors, and automatically refreshing the user's OAuth 2.0 bearer token when their current token has expired.
  • Leaderboard and achievement widgets. The SDK has built-in controllers for displaying achievements and leaderboards. The leaderboards controller can display a single leaderboard, or a 'leaderboard picker' that lets the user select what leaderboard they would like to view. The achievements controller displays achievement information, including the player's progress towards unlocking incremental achievements.
  • Caching. The SDK improves the performance of your application by intelligently caching data that is front-loaded from the Games service.
  • Network management. If the user is offline, the SDK automatically queues up certain non-blocking network requests and re-sends them once the user is online again.

Library compatibility

The Google Play games services SDK for iOS supports applications that target iOS version 6.0 and higher.

Network connectivity

If the user is in an area with poor network connectivity, has airplane mode turned on, or does not otherwise have a network connection, the library will intelligently queue up certain network connections. Specifically, the library will queue up calls to:

  • submitScoreWithCompletionHandler: in the GPGScore class
  • unlockAchievementWithCompletionHandler: in the GPGAchievement class
  • revealAchievementWithCompletionhandler: in the GPGAchievement class
  • incrementAchievementNumSteps:completionHandler in the GPGAchievement class

These requests will remain in the queue until the user is reconnected to the network. This could take a few minutes later or several hours, depending on the situation, so be cautious about blocking your application while waiting for a response from any of these calls.

This queue of networked calls is stored locally on the device. If your application is forced to quit due to low memory conditions or is terminated by the user, any pending network calls will be stored and retried the next time the user starts the game. The only time these calls will be permanently lost is if your player is playing the game offline, and then uninstalls your application.

For other calls (such as loading the user's Saved Games data), the method's completion handler will be called right away with an NSError object if user is not connected to the network. You can compare the error codes in GPGError.h with what you receive from the NSError object. In the case that the network is unavailable, the error code will most likely correspond to the GPGNetworkUnavailableError value.

The GPGManager class

The GPGManager class is used to handle any application-wide settings that you want to specify for the Games service. Here are some common calls you might make using the GPGManager.

  • To access the GPGManager class, use the shared singleton instance.

    GPGManager *gameManager = [GPGManager sharedInstance];
  • To sign the user in, call the GPGManager's signInWithClientID:silently method.

    [[GPGManager sharedInstance] signInWithClientID:kMyAppClientId silently:NO];
  • To sign the user out, call the GPGManager's signout method:

    [[GPGManager sharedInstance] signOut];
  • To detect if the user has signed in to Google, use the GPGManager's signedIn method.

        if ([GPGManager sharedInstance].isSignedIn) {
            // Download the saved game
        } else {
            // Display "Sign in with Google to use SavedGames!" message
  • To respond to sign-in and sign-out events, use the GPGManager's statusDelegate protocol. You can then listen for these events by calling methods like didFinishGamesSignInWithError and didFinishGamesSignOutWithError.

    [GPGManager sharedInstance].statusDelegate = self;

For more information on the sign-in process, see the Sign-in documentation, or review the Getting started guide for iOS.

  • To adjust the location of the "Welcome Back" notification, first specify the anchor point of the graphic (top, center, or bottom), and then specify the offset in points. For example, the following code places the notification 30 points from the bottom of the screen.

    [GPGManager sharedInstance].welcomeBackToastPlacement = kGPGToastPlacementBottom;
    [GPGManager sharedInstance].welcomeBackOffset = 30;
  • If you would like to specify the orientation(s) your game supports, call the GPGManager's setValidOrientationFlags method. This will affect how the "Welcome Back" notification is displayed. For example, the following code will ensure that this notification is only displayed in landscape mode:

    NSUInteger flags = 0;
    flags |= (1 << UIDeviceOrientationLandscapeLeft)
    flags |= (1 << UIDeviceOrientationLandscapeRight)
    [[GPGManager sharedInstance] setValidOrientationFlags:flags];
  • In addition, you can use the GPGManager to sign in the user, detect if the user has signed in, and sign out the user by using the signIn:reauthorizeHandler, hasAuthorizer, and signout methods, as described in the "Authentication and sign-in" section above.

For more detailed information and sample code, review the GPGManager reference documentation.

The GPGPlayer class

The GPGPlayer class represents a Play Games player, and contains useful information such as the player's display name and avatar image. The following code shows how you can retrieve this object.

// Are they signed in?
if ([GPGManager sharedInstance].isSignedIn) {

    // Request information about the local player
    [GPGPlayer localPlayerWithCompletionHandler:^(GPGPlayer *player, NSError *error) {
        if (!error) {
            GPGPlayer *localPlayer = player;
            NSLog(@"Welcome, %@", localPlayer.displayName );

Send feedback about...

Play Games Services for iOS
Play Games Services for iOS