The Recall API lets games manage links between PGS users and their in-game accounts by storing recall tokens with Google servers. Here's a sample scenario of how the Recall API might be used.
A user is playing a game where the developer has an identity system to track user progress, and uses PGS in parallel with other authentication methods to log users into their game. In this example, a user is logged into their PGS account Laura, and creates an in-game account with the developer's identity system called Racer94. As the user plays the game, the developer's game server syncs their progress.
Separately, the developer saves a recall token with Google, which corresponds with the user's in-game account. Google automatically stores that recall token against the user's PGS profile.
The user now decides to play the game on GPG on PC for the first time. The user is automatically signed in with their PGS account, and the game client checks to see if there is any progress available for this PGS user. The game server then queries Google to see if there are any tokens for this PGS account. Since there are, Google sends back the recall token, and the game server uses that token to find the user's associated account Racer94, and restore their progress. Since signing in with PGS is a frictionless experience, the user's progress is restored by the app without the user needing to enter a username or password. Furthermore, the developer can use PGS sign-in with their existing identity system, and rely on Google to store the link between player progress and their PGS account.
As seen in the example above, there are two main actions which are performed by the Recall API: storing the token with Google when a user logs in with one of the in-game accounts, and retrieving the token for a user in order to restore their in-game accounts.
In addition to recall tokens, the Recall API also requires a stable identifier corresponding to the in-game account, known as persona, to enforce cardinality constraints. You might think of a persona as the label which represents the user's in-game account within the developer's identity system, and the recall token as a key which is used to restore the user's in-game account to the game. Persona and token values must not be reused across different PGS projects. Also, while recall tokens may be changed over time, a persona should be stable according to the user's in-game account.
The Recall API enforces a 1:1 relationship between PGS profiles and in-game accounts (referred to as cardinality rules), where one persona can only be linked to one PGS profile, and one PGS profile can only be linked to one persona. The persona is used as a stable identifier for an in-game account, since recall tokens may change over time.
The persona linked to a PGS profile may also be changed over time (as different in-game accounts are linked to the PGS profile).
Detailed technical flows for storing & retrieving the recall tokens
This section covers the technical flow between the game client and servers with Google servers when storing and retrieving recall tokens.
Step 1: Sign in the PGS User and retrieve the session ID
The game initializes the PGS SDK and attempts to sign the user in with PGS.
Assuming the user is signed in, request a session ID from the Games SDK on the game client, and request an OAuth 2.0 token from Google's OAuth backend. The session ID and OAuth 2.0 tokens are used to communicate with the Google Games backend.
Step 2: Retrieve any available recall token
Request for any associated recall token with the PGS user's account. If a token is present, proceed to Step 3a and restore progress. Otherwise, if this is a new user and they have no token present, proceed to Step 3b and store a new token.
Step 3a: If token is present, restore progress
If a token is present, retrieve and decrypt the token, and restore user data.
Step 3b: If no token is present, store a token
Since no token is present, no progress is restored. The user proceeds to sign in with the developer's identity system, or creates a new account if one does not exist. Note - this isn't signing in with PGS (which has been done already), but with a developer's identity system outside of PGS.
Create an encrypted recall token which encodes the user's in-game account, and send it to Google along with the session ID and OAuth 2.0 token. At this point, Google creates an association between the recall token which was sent, and the player's PGS account.
In order to integrate the Recall API with your client and game server, follow this guidance.