Integrate the PGS Recall API within your game

This page explains how to implement the Recall API within your game. It first covers setting up your game server and client to support the API, and then goes through how to store and retrieve tokens.

Game server setup

Set up your game server to make Recall API calls to Google servers.

1. Set up your Play Games Services project

(If not already completed) Follow the instructions in Set up Google Play Games Services.

2. Set up a service account for the game

Follow the instructions on creating a service account. At the end you should have a JSON file with service account credentials.

3. Download server-side Java library for PlayGamesServices

Download the latest google-api-services-games library and upload this to your server.

4. Prepare credentials for Recall API calls

See Preparing to make an authorized API call for more context.

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.services.games.Games;
import com.google.api.services.games.GamesScopes;

// ...

GoogleCredential credential =
  GoogleCredential.fromStream(new FileInputStream("<credentials>.json"))
    .createScoped(Collections.singleton(GamesScopes.ANDROIDPUBLISHER));

Games gamesApi =
    new Games.Builder(httpTransport, JSON_FACTORY, credential).build();

Game client setup

Set up your game client to retrieve the recall session IDs used by your server to communicate with Google servers.

Java SDK

Set up the Java SDK within your client, and make sure to include com.google.android.gms:play-services-games-v2:19.0.0 and com.google.android.gms:play-services-tasks:18.0.2 or above in your gradle file.

To communicate with Google's servers with the correct information, you need to request a Recall session ID from the client SDK, which you send to your game's server.

Kotlin

PlayGames.getRecallClient(getActivity())
                .requestRecallAccess()
                .addOnSuccessListener { recallAccess -> val recallSessionId: String = recallAccess.getSessionId() }
                // Send the recallSessionId to your game server

Java

PlayGames.getRecallClient(getActivity())
  .requestRecallAccess()
  .addOnSuccessListener(
    recallAccess -> {
      String recallSessionId = recallAccess.getSessionId();
      // Send the recallSessionId to your game server
    });

Unity SDK

If not already completed, set up the Unity SDK within your client.

To communicate with Google's servers with the correct information, you need to request a Recall session ID from the client SDK, and send it to your game's server.

PlayGamesPlatform.Instance.RequestRecallAccess(
    recallAccess => {
        string recallSessionId = recallAccess.sessionId;
        // Send the recallSessionId to your game server
    });

Use the Recall API within your game server

After configuring your server and client, you can send the recallSessionID from your game client to your game server and follow the guidance below to start using the Java API to store, retrieve or delete the Recall tokens server-side.

Store tokens

Users' persona and game token can be stored by using the LinkPersonaRequest object. You need to use the GoogleCredential to call Google APIs (See Calling Google APIs for context). Note that, per the 1:1 cardinality constraint, you can only link one persona to one PGS profile at a time (and vice-versa).You should set the resolution policy in case this PGS profile already has been linked with another persona.

Optionally, you may choose to set a TTL on the token, which declares how long the token is valid using a Durations object. You may choose to set this using SetTtl() (as shown below), which sets the expiry date from the amount of time specified in the method, or setExpireTime(), which lets you set an exact time for when the tokens expire.

You must encrypt the persona and game token, and they cannot contain personally identifiable information. Persona and token strings can be at most 256 characters long, and there can be at most 20 tokens or personas stored per player per game.

Only one token can be stored per persona per player at a given time. Trying to store another token with the same persona overwrites the original token.

import com.google.api.services.games.Games.Recall.LinkPersona;
import com.google.api.services.games.model.LinkPersonaRequest;
import com.google.api.services.games.model.LinkPersonaResponse;
import com.google.protobuf.util.Durations;

// ...

Games gamesApi =
    new Games.Builder(httpTransport, JSON_FACTORY, credential).build();

String recallSessionId = ... // recallSessionID from game client
String persona = ... // encrypted opaque string, stable for in-game account
String token = ... // encrypted opaque string encoding the progress line

LinkPersonaRequest linkPersonaRequest =
  LinkPersonaRequest.newBuilder()
    .setSessionId(recallSessionId)
    .setPersona(persona)
    .setToken(token)
    .setCardinalityConstraint(ONE_PERSONA_TO_ONE_PLAYER)
    .setConflictingLinksResolutionPolicy(CREATE_NEW_LINK)
    .setTtl(Durations.fromDays(7)) // Optionally set TTL for token
    .build();

LinkPersonaResponse linkPersonaResponse =
  gamesApi.recall().linkPersona(linkPersonaRequest).execute();

if (linkPersonaResponse.getState() == LINK_CREATED) {
  // success
}

Retrieve tokens

There are three options to retrieve a token, based on your games' needs. You can request the following:

  • The tokens associated with the current game, including game-scoped recall tokens.
  • The last token stored across all games owned by the developer account.
  • Given a list of games owned by the developer account, all the recall tokens associated with each game.

Game-scoped recall tokens

To retrieve the recall tokens from the current game, get the recallSessionId from the client and pass it into the retrieveTokens API:

import com.google.api.services.games.Games;
import com.google.api.services.games.model.RetrievePlayerTokensResponse;
import com.google.api.services.games.model.RecallToken;

// ...

String recallSessionId = ... // recallSessionID from game client

RetrievePlayerTokensResponse retrievePlayerTokensResponse =
  gamesApi.recall().retrieveTokens(recallSessionId).execute();

for (RecallToken recallToken : retrievePlayerTokensResponse.getTokens()) {
  String token recallToken.getToken();
  // Same string as was written in LinkPersona call
  // decrypt and recover in-game account
}

Latest recall token across all games owned by developer account

To retrieve the most recent token stored across all games owned by the developer account in the Google Play Console, you need to get the recallSessionId from the client and pass it into the lastTokenFromAllDeveloperGames API, as shown in the following code snippet. As part of the response, you can inspect the Application ID associated with this token.

import com.google.api.services.games.Games;
import com.google.api.services.games.model.RetrieveDeveloperGamesLastPlayerTokenResponse;
import com.google.api.services.games.model.GamePlayerToken;
import com.google.api.services.games.model.RecallToken;

// ...

String recallSessionId = ... // recallSessionID from game client

RetrieveDeveloperGamesLastPlayerTokenResponse response =
        gamesApi.recall().lastTokenFromAllDeveloperGames(recallSessionId)
        .execute();

if (response.hasGamePlayerToken()) {
    GamePlayerToken gamePlayerToken = response.getGamePlayerToken();

    // The ID of the application that the token is associated with.
    String applicationId = gamePlayerToken.getApplicationId();

    // Same string as was written in LinkPersona call.
    RecallToken recallToken = gamePlayerToken.getRecallToken();

    // Decrypt and recover in-game account.
}

All recall tokens across a given list of games owned by the developer account

To retrieve all the tokens associated with a list of games which are owned by your developer account in the Google Play Console, get the recallSessionId from the client and pass it into the gamesPlayerTokens API. Supply a list of Application IDs.

import com.google.api.services.games.Games;
import com.google.api.services.games.model.RetrieveGamesPlayerTokensResponse;
import com.google.api.services.games.model.GamePlayerToken;
import com.google.api.services.games.model.RecallToken;

// ...

String recallSessionId = ... // recallSessionID from game client

// Application IDs for which you would like to retrieve the recall tokens.
List<String> applicationIds = ...

RetrieveGamesPlayerTokensResponse response =
gamesApiClient
        .recall()
        .gamesPlayerTokens(recallSessionId)
        .setApplicationIds(applicationIds)
        .execute();

for (GamePlayerToken gamePlayerToken : response.getGamePlayerTokens()) {
    // The ID of the application that the token is associated with.
    String applicationId  = gamePlayerToken.getApplicationId();


    // Same string as was written in LinkPersona call.
    RecallToken recallToken = gamePlayerToken.getRecallToken();

    // Decrypt and recover in-game account.
}

Delete recall token

If needed, you can also delete the recall token with the following call:

import com.google.api.services.games.Games;
import com.google.api.services.games.model.UnlinkPersonaRequest;
import com.google.api.services.games.model.UnlinkPersonaResponse;

// ...

String recallSessionId = ...
String persona = ...
String token = ...

Games gamesApi =
    new Games.Builder(httpTransport, JSON_FACTORY, credential).build();

UnlinkPersonaRequest unlinkPersonaRequest =
  UnlinkPersonaRequest.newBuilder()
    .setSessionId(recallSessionId)
    .setPersona(persona)
    // .setToken(token) - alternatively set token, but not both
    .build();

UnlinkPersonaResponse unlinkPersonaResponse =
  gamesApi.recall().unlinkPersona(unlinkPersonaRequest).execute();

boolean unlinked = unlinkPersonaResponse.isUnlinked();

Enable profileless mode

You can enable limited Recall API functionality for users that don't have PGS profiles by following these steps:

  1. Enable profileless recall for your PGS game project in the Play Developer Console. Select the option labeled "Turn on storage".
  2. Review the additional terms described later in this section.
  3. Add the following metadata tag into your app manifest:
<meta-data
  android:name="com.google.android.gms.games.PROFILELESS_RECALL_ENABLED"
  android:value="true" />

Additional terms

In addition to being subject to the Play Games Services Terms of Service, you agree that if you use the Recall API for users without a PGS profile, which enables sharing end user's data with Google without them having a Play Games Services profile, you must, prior to sharing such data with Google, provide the end user with appropriate notice describing the following:

  1. Your sharing of the data with Google to enable Play Games account linking feature.
  2. The availability of settings to manage such sharing such as those through Play Games settings.
  3. The processing of such data under the Google Privacy Policy, and obtain appropriate end user consent for such sharing that meets all applicable legal requirements.