This page explains how to implement the [Recall API](https://developer.android.com/games/pgs/recall) 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](https://developer.android.com/games/pgs/console/setup).
| **Note:** Recall tokens and personas are available on a per-PGS project basis. This means that tokens and personas are stored per-PGS project, and for separate PGS projects, there are separate collections of links between PGS profiles and personas. We recommend reviewing [this documentation when determining how to set
| up your PGS projects.](https://developer.android.com/games/pgs/console/setup#add_your_game_to_the)

### 2. Set up a service account for the game

Follow the instructions on [creating a service
account](https://developers.google.com/identity/protocols/oauth2/service-account#creatinganaccount).
At the end you should have a JSON file with service account credentials.
| **Note:** The Recall API is a server-to-server API. Because of this, the Recall API uses service accounts to authenticate the game server, not regular 3-legged OAuth, which is used by other Games APIs to authenticate both game servers and end users.

### 3. Download server-side Java library for PlayGamesServices

Download the latest [google-api-services-games
library](https://github.com/googleapis/google-api-java-client-services/tree/main/clients/google-api-services-games)
and upload this to your server.

### 4. Prepare credentials for Recall API calls

See [Preparing to make an authorized API
call](https://developers.google.com/identity/protocols/oauth2/service-account#authorizingrequests)
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](https://developer.android.com/games/pgs/android/android-start), 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

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

### Java

```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](https://developer.android.com/games/pgs/unity/unity-start).

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](https://developers.google.com/identity/protocols/oauth2/service-account#callinganapi)
for context). Note that, per the [1:1 cardinality
constraint](https://developer.android.com/games/pgs/recall#cardinality-rules), 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](https://developers.google.com/protocol-buffers/docs/reference/java/com/google/protobuf/util/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.
| **Note:** The encryption key used for encrypting tokens should be unique for each application. If the game is transferred to another developer, the encryption key must be passed to the new owner. The recall tokens can't be decrypted without the original encryption key.
**Note:** Tokens created for [profileless users](https://developer.android.com/games/pgs/recall#profileless) have a default TTL of 30 days. Otherwise, for users with PGS profiles, tokens don't have a default TTL.  

    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.

| **Note:** When you request recall tokens, the API doesn't return strings that represent the persona.

#### 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](https://developer.android.com/build/configure-app-module#set-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](https://developer.android.com/build/configure-app-module#set-application-id).  

    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](https://developer.android.com/games/pgs/recall#profileless)
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".](https://developer.android.com/static/images/games/pgs/play-console-recall.png)
2. Review the [additional terms](https://developer.android.com/games/pgs/recall/recall-setup#terms) described later in this section.
3. Add the following metadata tag into your [app
   manifest](https://developer.android.com/guide/topics/manifest/manifest-intro):

    <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](https://developers.google.com/games/services/terms), 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](https://policies.google.com/privacy), and obtain appropriate end user consent for such sharing that meets all applicable legal requirements.