Set Up Play Games Services for Web on the Server

If you are developing a game that has a strong server-side component and you wish to verify the user or make game services calls from the server, follow these steps.

The main difference from the client side flow is that, instead of using an OAuth 2.0 access token directly on the client, you receive a special single-use code that the client passes down to your server. Your server then exchanges this single-use code for an OAuth 2.0 token that it can use to make calls to the Google Play games services APIs, including making a players.get call to verify the user's identity.

To build a game that communicates with Google Play games services from the server:

Step 1. Set up your game in the Google Play Developer Console

Remember to use the Google Play Developer Console to enable Google Play games services for your game, not the Google API Console.

  1. Enable Google Play games services for your web game by following all of the steps described in Setting Up Game Services.
  2. Record the following credential information for later.
  3. (Optional) Add achievements and leaderboads to your game by following the steps described in Configuring Achievements and Leaderboards.
  4. Add test accounts for your game by following the steps described in Publishing Your Game Changes.

Step 2. Add page-level configurations to your page

Page-level configuration options allow you to define the parameters of your sign-in button or JavaScript call from <meta> tags in your page. These parameters can be shared by your sign-in and interactive posts methods, which can simplify your code.

A typical set of meta tags for a game using Play Games services might look like this:

<meta name="google-signin-client_id" content="xxxxxxxxxxxxxx.apps.googleusercontent.com" />
<meta name="google-signin-cookiepolicy" content="single_host_origin" />
<meta name="google-signin-callback" content="signinCallback" />
<meta name="google-signin-scope" content="https://www.googleapis.com/auth/games" />

The value you supply in the "google-signin-client_id" should be your game's OAuth 2.0 client ID mentioned in the previous step.

Please refer to the Google Sign-In client reference for a more complete description of page-level configuration options.

Step 3. Load the client.js library

Load the Google APIs Client Libarary for JavaScript. This library makes it easy for you to communicate with and receive responses from the Games service.

To load the client library, add the following script tag to your page:

<script src="https://apis.google.com/js/client.js"></script>

This loads a script that creates several helpful functions and puts them into a global gapi (short for Google API) object that you can use later.

Alternately, you can load this script asynchronously for better performance.

Step 4. Consider using the Google Sign-In button

The simplest way to add a sign-in button to your page is to implement the HTML-based sign-in button. For implementation details, see Google Sign-In for server-side apps on the Google Sign-In documentation.

For many games, however, rendering a button inside its own <div> on top of your game engine can be problematic. In a Flash game, for instance, you probably want to render the sign-in button inside Flash, and then make an externalInterface call to the JavaScript loaded with your page, so that you can sign the user in using Google's JavaScript library.

The remaining instructions on this page show you how to sign in your user and make calls to Google Play games services without relying on the Google Sign-In button.

Step 5. Sign the user in

The gapi client uses OAuth 2.0 to authorize the library to make API calls on behalf of the user.

Once the gapi library has loaded, it first attempts to sign the user in "silently". This call succeeds if the user has already authorized your game in the past and you haven't added any additional scopes.

If this call succeeds, the callback method defined in your google-signin-callback is invoked and an auth object is passed in as the parameter. At this point, you're ready to use the library to make calls against Google's RESTful APIs.

If this call fails, the callback method is invoked and passed an auth object containing an error value of immediate_failed. At this point, your callback method should display a button or link (or object inside your Flash or Unity application) that prompts the user to sign in.

Clicking that button or link should then call gapi.auth.signin(), which will ask the user to sign in to your game in a separate window. The results of this dialog will then be passed to the callback method defined in your google-signin-callback meta-tag.

You might ask why you should go through the trouble of displaying a sign-in link instead of calling gapi.auth.signin() directly. The reason is that the resulting dialog appears in a pop-up window, and if that doesn't happen in response to a user click, it will be blocked by the browser's pop-up blocker.

A typical google-signin-callback method might look like this:

handleAuthResult = function(auth) {
  if (auth && auth.error == null) {
    // Hooray! The user is logged int!
    // If we got here from a sign-in button, we should probably hide it
    hideMyGamesSignInButton();
    loadLeaderboardsAndAchievements();
  } else {
    // Common reasons are immediate_failed and user_signed_out
    if (auth && auth.hasOwnProperty('error')) {
      console.log('Sign in failed because: ', auth.error);
    }
    showMyGamesSignInButton();
  }
};

Note that this callback method is called by the library whether the user signed in silently, or through a pop-up dialog, so this callback should be your single point of entry to start using Google Play games services, no matter how the user signed in.

Step 6. Exchange the code for an access token on the server

The auth object that is returned to your google-signin-callback method contains a one-time use code that you can send to your server in exchange for an OAuth 2.0 access token.

How you accomplish this step depends a bit on the language you're using, but the general strategy is:

  1. Make an AJAX call from the client to your server that sends down the single-use token.
  2. On the server, load up your favorite Google API client library.
  3. When you initialize your client library, pass it your OAuth 2.0 client ID and client secret, and specify a redirectURI of 'postmessage' where appropriate.
  4. Make a call on the server-side to exchange the OAuth 2.0 single-use code for an access token. How you do this depends on the library you're using.
  5. When you have an access token, make a call to Players.get with 'me' as the user you're retrieving. This will give you the user's userId, verified on the server.
  6. Securely store the player's userId and access token in a database to use later.
  7. Come up with some system (session variables, your own randomly-generated string, etc.) to identify your user with their corresponding row in the database, and return this identifier to the client.

Step 7. Make calls from the server

To make calls to the Google Play games services APIs from the server, follow this general strategy. Again, how you accomplish these steps depends on the language and library you're using, but the strategy should be similar.

  1. Make a call from your web client to the server. Make sure you identify your user using whatever system you devised in the previous step.
  2. On the server, look up the player's auth token from your database.
  3. Authorize your server-side API client library using that auth token.
  4. Make calls!
  5. Return the results of those calls back to the browser.

Step 8. Refresh the user's token every 45 minutes

Every 60 minutes, your access token will expire. You can create a new one on the server by performing steps 5 and 6 above. Because calling gapi.auth.signIn should always succeed once the user is signed in, this process won't discrupt your user's experience. To be safe, we recommend refreshing the user's token every 45 minutes while they're playing your game.

Step 9. Protect yourself against cross-site forgery attacks

It's always a good idea to defend yourself against cross-site forgery attacks. It's particulary important to do this if you store any kind of "remember this user later" information in a cookie.

Here are some resources to learn more about cross-site forgery:

The general strategies for defending against these attacks are:

  1. When the user first requests your web page, generate a random string.
  2. Pass this string to the user as both a session cookie and a JavaScript variable embedded in the page.
  3. For any request you make to your server, make sure you pass this JavaScript variable along with the request.
  4. For any request that you receive on the server, first ensure that the random string passed along with the request matches the string received as a session cookie. If they don't match up, don't process the rest of the request.

We recommend adding cross-site forgery defences both during the intial login process (when you pass the single-use code to your server) as well as any future calls to your server (as described in Step 7 above).

For more information, be sure to view the Google Sign-In for server-side apps documentation, which includes other examples of defending against cross-site request forgeries.

Making server and client-side calls

The auth object passed to your google-signin-callback not only contains a single-use code that gets passed to your server, but also an access token that the gapi library uses to authorize itself for making any client-side calls.

This means you can use the same process as above to make calls from both the server and the client. For example, you might want to verify the user's identity on the server, but you could make an Achievements.list call directly from the client, which removes one additional step from the network call.

To make both client and server calls:

  1. Perform steps 1 through 6 as described above.
  2. Make calls on the client using gapi.client.request as described in the client-only documentation.
  3. Make calls on the server using the strategy described in Step 7.

Q: If the auth object in my google-signin-callback already has an access token, can I send that to the server instead of performing this additional code-exchange step?

A: No. You should avoid sending access tokens to your server if at all possible. The "exchange a single-use code for an access token" strategy is much more secure and we highly recommend using that approach in your applications.

Enviar comentarios sobre…

Play Games Services for Web
Play Games Services for Web