Hide

Get Started with Play Games Services for iOS

Welcome to iOS game development with Google Play games services!

The Play Games SDK provides cross-platform Google Play games services that lets you easily integrate popular gaming features such as achievements, leaderboards, and multiplayer to your tablet and mobile games.

This document describes the basic steps to make an iOS game using the Play Games SDK. Please note that these instructions supersede the Google+ Sign-In for iOS documentation.

Before you begin

Creating applications using the Google Games SDK requires:

  • Xcode version 5.0 or higher
  • A mobile device running iOS 7.0 or higher

Step 1: Explore the sample games

If you haven't already done so, you might find it helpful to download and review the sample games, which demonstrate proper use of all of the Google Play games services features on iOS. All sample games for iOS can be found on the samples downloads page. Follow the instructions in the README file within each sample to learn how to initialize and run them.

Step 2: Create (or open) your Xcode project

Create a new project in Xcode, or open an existing project. Take note of your Bundle Identifier, since you'll need this value in the next step. This is usually something like com.*your_company*.*your_project*.

If you're creating a new project, you are encouraged to select the single-view application option. This takes care of setting up the view controller for your game.

Step 3: Add your game to the Google Play Developer Console

Create an entry for your game in the Google Play Developer Console. This enables Google Play games services for your application, and creates an OAuth 2.0 client ID, if you don't already have one.

  1. Add an entry for your iOS game by following the steps described in Setting Up Google Play Games Services.
  2. Take note of your game's OAuth 2.0 client ID; you will need this later.
  3. (Optional) Add achievements and leaderboards to your game by following the steps described in Configuring Achievements and Leaderboards.
  4. Add accounts for other members of your team to test your game by following the steps described in Publishing Your Game Changes.

Step 4: Install the SDKs

Before using the Google Play games services APIs, you must install the required libraries using one of these approaches.

Option 1: Using CocoaPods

CocoaPods is a dependency manager for installing Objective-C libraries. If you have CocoaPods installed, you can use it to install the Play Games SDK for iOS by following these steps:

  1. Create a Podfile and make sure that it specifies a platform of ios 7.0 or later
  2. Add the GooglePlayGames pod to your Podfile. A typical podfile might look like this:

    platform :ios, '7.0'
    pod 'GooglePlayGames'
    // Other pods might go here
    
  3. Run pod install from the command line.

  4. Open the generated .xcworkspace file for your app.
  5. Open your project in XCode, and continue from the Add a sign-in and sign-out button section below.

Option 2: Manual installation

To install the Play Games SDK for iOS manually without using CocoaPods, follow these steps:

  1. Download and extract the latest Google+ iOS SDK from the Google+ Downloads page.
  2. Copy the following items from the Google+ SDK into your project:
    • GoogleOpenSource.framework
      • Alternately, you can use the full source files of the Google Open Source library with your project. This can be useful if you want to step into the code while debugging. To do so, add the OpenSource folder to your project in Xcode.
    • GooglePlus.bundle
    • GooglePlus.framework
  3. Download and extract the Play Games SDK for iOS. The latest version is available on the SDKs download page.
  4. Add the following items to your Xcode project:
    • GooglePlayGames.bundle
    • GooglePlayGames.framework
  5. Open your project settings and in the Build Phases tab, Link Binary With Libraries section, click the + sign and add the following frameworks:
    • AddressBook.framework
    • AssetsLibrary.framework
    • CoreData.framework
    • CoreLocation.framework
    • CoreMotion.framework
    • CoreTelephony.framework
    • CoreText.framework
    • Foundation.framework
    • MediaPlayer.framework
    • QuartzCore.framework
    • Security.framework
    • SystemConfiguration.framework
    • libc++.dylib
    • libz.dylib
  6. Add the ObjC linker flag to the app target's build settings. In your target settings, select Build Settings > Linking > Other Linker Flags, then add -ObjC as a flag.

    Other Linker Flags: -ObjC
    

Step 5: Add a sign-in and sign-out button

In your view controller, add a sign-in button and a sign-out button. Make sure your sign-in button conforms to the Google+ branding guidelines. To reduce your development effort, many of the built-in user-interfaces provided by Google Play games services already include a sign-out option so you don't need to add this manually.

To add the sign-in and sign-out buttons:

  1. Control-drag these two buttons into your view controller .m file's private category (the section contained by the @interface). This creates IBOutlet objects for these buttons.

    @interface ViewController ()
    @property (weak, nonatomic) IBOutlet UIButton *signInButton;
    @property (weak, nonatomic) IBOutlet UIButton *signOutButton;
    @end
    
  2. Next, control-drag these two buttons into the @implementation section of your view controller's .m file. This creates the following methods for handling the player's button presses.

    - (IBAction)signInButtonWasPressed:(id)sender {
      // handle the sign-in button press
    }
    
    - (IBAction)signOutButtonWasPressed:(id)sender {
      // handle the sign-out button press
    }
    

Step 6: Import the Play Games SDK and enable sign-in

  1. Import the GooglePlayGames header file. Tip: The easiest way to do this is to open up your application's .pch file and add the following line:

    #import <GooglePlayGames/GooglePlayGames.h>
    

    By putting this import statement in your application's precompiled header file, you don't have to import this header in all your other files.

  2. In your view controller's .m file, or in a separate constants file, set your client ID. This is the string you previously recorded in the 'Add your game to the Google Play Developer Console' section.

    static NSString * const kClientID = @"123456789012.apps.googleusercontent.com";
    
  3. Add the following code to the two buttonWasPressed methods you previously created in the 'Add a sign-in and sign-out button' section.

    - (IBAction)signInButtonWasPressed:(id)sender {
      [[GPGManager sharedInstance] signInWithClientID:kClientID silently:NO];
    }
    
    - (IBAction)signOutButtonWasPressed:(id)sender {
      [[GPGManager sharedInstance] signOut];
    }
    
  4. When a player signs in to Google, the sign-in process sends them to the Google+ app, Chrome for iOS, or Mobile Safari (in that sequence). After the player signs in, the app opens a URL that points back to your game and contains the information necessary to complete the sign-in process. Make sure your application can handle the URL that redirects back to your game

    1. In your target settings Info tab, scroll down to the URL Types section, and click the + icon to add a new URL type. In the Identifier and URL Schemes fields, enter your bundle ID.

      Graphic that shows the identifier and URL schemes fields.

    2. In your app delegate .m file, import the Google+ framework.

      #import <GooglePlus/GooglePlus.h>
      
    3. Call the GPPURLHandler URL handler from your app delegate's URL handler. This method handles the URL that your application receives at the end of the authentication process.

      - (BOOL)application:(UIApplication *)application
            openURL:(NSURL *)url
            sourceApplication:(NSString *)sourceApplication
            annotation:(id)annotation {
        return [GPPURLHandler handleURL:url sourceApplication:sourceApplication annotation:annotation];
      }
      

You can now test your application and be able to sign in and out. When testers sign in, they will be redirected to G+, Chrome, or Safari to complete the sign-in process, and then redirected back to your application.

Step 7: Add a GPGStatusDelegate

Next, add the code to let your app know that when sign-in process is completed.

  1. In your viewDidLoad private category, declare that your view controller is a GPGStatusDelegate

    @interface ViewController () <GPGStatusDelegate>
    
  2. Next, tell the GPGManager that this class will be its status delegate. You can do this in many places throughout your application (such as in your AppDelegate). The following snippet shows how you can do this from the viewDidLoad method for your initial view controller:

    - (void)viewDidLoad {
      [super viewDidLoad];
      [GPGManager sharedInstance].statusDelegate = self;
    }
    
  3. Implement these GPGStatusDelegate methods: didFinishGamesSignInWithError (to handle completion of player sign-in) and didFinishGamesSignOutWithError (to handle completion of player sign-out).

    - (void)didFinishGamesSignInWithError:(NSError *)error {
      if (error) {
          NSLog(@"Received an error while signing in %@", [error localizedDescription]);
      } else {
          NSLog(@"Signed in!");
      }
      [self refreshInterfaceBasedOnSignIn];
    }
    
    - (void)didFinishGamesSignOutWithError:(NSError *)error {
      if (error) {
          NSLog(@"Received an error while signing out %@", [error localizedDescription]);
      } else {
          NSLog(@"Signed out!");
      }
      [self refreshInterfaceBasedOnSignIn];
    }
    
  4. Create an empty method for the refreshInterfaceBasedOnSignIn call.

    - (void)refreshInterfaceBasedOnSignIn {
      // We'll be filling this out shortly.
    }
    

    Now when testers sign in or out, they should see the appropriate message reported in the console log.

  5. Fill out the implementation for the refreshInterfaceBasedOnSignIn method. Use the GPGManager's isSignedIn property to determine what button to show.

    - (void)refreshInterfaceBasedOnSignIn {
      BOOL signedInToGameServices = [GPGManager sharedInstance].isSignedIn;
      self.signInButton.hidden = signedInToGameServices;
      self.signOutButton.hidden = !signedInToGameServices;
    }
    

Now, when testers finish signing in, the sign-in button will be hidden. When they sign out, the sign-out button will be hidden and the sign-in button should re-appear.

Step 8: Automatically sign in returning players

You can also sign players in automatically, to avoid having them sign in every time they launch your game. The GPGManager will automatically sign the player in when you specify silently:YES in the signInWithClientID method. This call succeeds if all the following conditions are met:

  • The player has authorized your application in the past;
  • The player has not revoked access to your application; and
  • The app is not requesting new scopes since the player last signed in.

Using this behavior, you can sign the player in automatically to your game by adding the signInWithClientID:silently: call to the end of your viewDidLoad method, with silently set to YES.

[[GPGManager sharedInstance] signInWithClientID:kClientID silently:YES];

Run your application and notice that, unless you signed out when you last used your application, you are now signed in automatically.

Step 9: Add some interface refinements

When the application starts player sign-in automatically, there is a small delay between the time sign-in starts and completes. Your game should disable the UI during this time. To do this, use the fact that the signInWithClientID:silently method returns YES if it is attempting to sign the player in automatically.

  1. First, add an instance variable to your view controller class to keep track of whether or not you are signing the player in silently:

    @implementation ViewController {
        BOOL _silentlySigningIn;
    }
    
  2. Next, use that variable to record what gets returned from the signInWithClientID:silently: method, and then immediately call refreshInterfaceBasedOnSignIn.

    - (void)viewDidLoad {
      [super viewDidLoad];
      [GPGManager sharedInstance].statusDelegate = self;
      _silentlySigningIn = [[GPGManager sharedInstance]
              signInWithClientID:kClientID silently:YES];
      [self refreshInterfaceBasedOnSignIn];
    }
    
  3. Add the following lines to your refreshInterfaceBasedOnSignIn method to disable the sign-in and sign-out buttons if the player is silently signing in:

    self.signInButton.enabled = !_silentlySigningIn;
    self.signOutButton.enabled = !_silentlySigningIn;
    
  4. Finally, set _silentlySigningIn to NO right before you call refreshInterfaceBasedOnSignIn in the two GPGEventDelegate methods:

    - (void)didFinishGamesSignInWithError:(NSError *)error {
      // Other code goes here...
      _silentlySigningIn = NO;
      [self refreshInterfaceBasedOnSignIn];
    
    }
    
    - (void)didFinishGamesSignOutWithError:(NSError *)error {
      // Other code goes here...
      _silentlySigningIn = NO;
      [self refreshInterfaceBasedOnSignIn];
    }
    

Now, when testers start your application, they should see your sign-in button, but it will be hidden during the automatic sign-in. Once initial player sign-in is completed, the sign-in button is hidden and a sign-out button appears.

Congratulations! At this point, you are now ready to start adding achievements, leaderboards, quests, and other Google Play games services features to your game.

Send feedback about...

Play Games Services for iOS