Get started with the Google Play Games plugin for Unity

This topic describes how to set up your Unity project to use the Google Play Games plugin for Unity. The tasks include setting up the project, running it, choosing a social plstform, and handling player sign-in.

Before you begin

Plugin Installation

  1. Get the plugin using one of these options:

  2. Find the unitypackage file in the current-build directory. This file is the plugin. For example, it should look similar to the following:

      current-build/GooglePlayGamesPluginForUnity-X.YY.ZZ.unitypackage
    
  3. Open your game project in Unity.

  4. Import the unitypackage file into your project's assets by clicking the Assets > Import Package > Custom Package menu item.

  5. Ensure that your current build platform is set to Android.

    1. In the main menu, click File > Build Settings….

    2. Select Android and click Switch Platform.

    3. There should be a new menu item under Window > Google Play Games. If there isn't, refresh the assets by clicking Assets > Refresh and then try setting the build platform again.

Get Android resources from Play Console

Each achievement, leaderboard, and event you create in Play Console includes an Android resouce that you use when you set up your Unity project.

  1. Get the Android resources for your game.

    1. In Play Console, open the Play Games Services project for your game.

    2. Click the Achievements tab, and then click Get resources.

    3. In the Export resources window, click the Android tab.

    4. Select and copy the XML content.

Set up your Unity project

  1. Add the Android resources to your Unity project.

    1. In Unity, click ** Window > Google Play Games > Setup... > Android Setup **.

    2. Complete the these items in the setup windows:

    3. Directory to save constants: The folder for the constants file.

    4. Constants class name: The name of the C# class to create, including the namespace.

    5. Resources Definition: Paste the Android resources data from Play Console here.

    6. Web client ID: The client ID of the linked web app. This is only needed if you have a web-based backend for your game and need a server auth code to exchange for an access token by the backend server, or if you need an ID token for the player to make other non-game API calls.

    7. Click Setup. This configures your game with the client ID and generates a C# class that contains constants for each of your Android resources.

Android Setup

Set up the path to your Android SDK installation in Unity. This is located in the preferences menu, under the External Tools section.

To configure your Unity game to run with Google Play Games on Android, first open the Android SDK manager and verify that you have downloaded the following packages. Depending on if you are using the SDK manager from Android Studio, or using the standalone SDK manager, the name of the components may be different. - Google Play Services - Android Support Library - Local Maven repository for Support Libraries (Also known as Android Support Repository) - Google Repository - Android 6.0 (API 23) (this does not affect the min SDK version).

Next, configure your game's package name. To do this, click File > Build Settings, select the Android platform and click Player Settings to show Unity's Player Settings window. In that window, look for the Bundle Identifier setting under Other Settings. Enter your package name there (for example com.example.my.awesome.game).

In order to sign in to Play Game Services, you need to sign your APK file, make sure that you are signing it with the correct certificate, that is, the one that corresponds to the SHA1 certificate fingerprint you entered in the Developer Console during the setup.

Next, click the Window |Google Play Games|Setup - Android setup menu item. This will display the Android setup screen.

Enter the Constants class name. This is the name of the fully qualified class that will be updated (or created) which contains the IDs of the game resources. The format of the name is <namespace>.<classname>. For example, AwesomeGame.GPGSIds

Paste the resource definition data. This is the XML data from the Google Play Developer Console which contains the resource IDs as well as the Application ID for Android.

This data is found in the Google Play Developer Console by clicking "Get resources" on any of the resource pages (e.g. Achievements or Leaderboards), then clicking Android.

After pasting the data into the text area, click the Setup button.

Note: If you are using a web application or backend server with your game, you can link the web application to the game to enable getting the player's id token and/or email address. To do this, link a web application to the game in the Google Play Developer Console, and enter the client id for the web application into the setup dialog.

Additional instructions on building for Android on Windows

If you are using Windows, you must make sure that your Java SDK installation can be accessed by Unity. To do this:

  1. Set the JAVA_HOME environment variable to your Java SDK installation path (for example, C:\Program Files\Java\jdk1.7.0_45).
  2. Add the Java SDK's bin folder to your PATH environment variable (for example, C:\Program Files\Java\jdk1.7.0_45\bin)
  3. Reboot.

How to edit environment variables: In Windows 2000/XP/Vista/7, right-click My Computer, then Properties, then go to Advanced System Properties (or System Properties and then click the Advanced tab), then click Environment Variables. On Windows 8, press Windows Key + W and search for environment variables For more information, consult the documentation for your version of Windows.

Run the Project

If you are working with the Smoketest sample, you should be able to build and run the project at this point. You will see the automatic sign-in attempt, when Smoketest starts.

To build and run on Android, click File > Build Settings, select the Android platform, then Switch to Platform, then Build and Run.

Choose a social platform

The Google Play Games plugin implements Unity's social interface, for compatibility with games that already use that interface when integrating with other platforms. However, some features are unique to Play Games and are offered as extensions to the standard social interface provided by Unity.

The standard API calls can be accessed through the Social.Active object, which is a reference to an ISocialPlatform interface. The non-standard Google Play Games extensions can be accessed by casting the Social.Active object to the PlayGamesPlatform class, where the additional methods are available.

Use the plugin without overriding the default social platform

When you call PlayGamesPlatform.Activate, Google Play Games becomes your default social platform implementation, which means that static calls to methods in Social and Social.Active will be carried out by the Google Play Games plugin. This is the desired behavior for most games using the plugin.

However, if for some reason you wish to keep the default implementation accessible (for example, to use it to submit achievements and leaderboards to a different social platform), you can use the Google Play Games plugin without overriding the default one. To do this:

  1. Do not call PlayGamesPlatform.Activate
  2. If Xyz is the name of a method you wish to call on the Social class, do not call Social.Xyz. Instead, call PlayGamesPlatform.Instance.Xyz
  3. Do not use Social.Active when interacting with Google Play Games. Instead, use PlayGamesPlatform.Instance.

That way, you can even submit scores and achievements simultaneously to two or more social platforms:

    // Submit achievement to original default social platform
    Social.ReportProgress("MyAchievementIdHere", 100.0f, callback);

    // Submit achievement to Google Play
    PlayGamesPlatform.Instance.ReportProgress("MyGooglePlayAchievementIdHere", 100.0f, callback);

Verify the sign-in service

A connection to Game services will be automatically formed when your game is opened. Once the connection is successful the player will be welcomed with a pop-up and your game is ready to begin using the Games Unity Plugin.

In the Start method of your script, listen to the result of the automatic sign- in attempt, fetch the authentication status and disable Play Games Services features if the user is not signed in.

    using GooglePlayGames;

    public void Start() {
      PlayGamesPlatform.Instance.Authenticate(ProcessAuthentication);
    }

    internal void ProcessAuthentication(SignInStatus status) {
      if (status == SignInStatus.Success) {
        // Continue with Play Games Services
      } else {
        // Disable your integration with Play Games Services or show a login button
        // to ask users to sign-in. Clicking it should call
        // PlayGamesPlatform.Instance.ManuallyAuthenticate(ProcessAuthentication).
      }
    }
}

The result code is an enum, which gives you different failure reasons that will help you understand sign-in failures better.

If you prefer using Unity’s Social platform, then you can alternatively use the code block below.

  using GooglePlayGames;

  public void Start() {
    PlayGamesPlatform.Activate();
    Social.localUser.Authenticate(ProcessAuthentication);
  }

You cannot make any games API calls (unlock achievements, post scores, etc) until you get a successful return value from Authenticate, so it is good practice to put up a standby screen until the callback is called, to make sure the user can't start playing the game until the authentication process completes.

Retrieve server authentication codes

In order to access Google APIs on a backend web server on behalf of the current player, you need to get an authentication code from the client application and pass this to your web server application. The code can then be exchanged for an access token to make calls to the various APIs. For information about the workflow, see Google Sign-In for Websites.

To get the server side access code:

  1. Configure the web client id of the web application linked to your game in the Play Game Console.

  2. Call PlayGamesPlatform.Instance.RequestServerSideAccess once the player is authenticated to get the server side access code.

  3. Pass this code to your server application.

  PlayGamesPlatform.Instance.RequestServerSideAccess(
    /* forceRefreshToken= */ false,
    code -> {
      // send code to server
    });

Set up and add features