The Recall API lets games use Play Games Services (PGS) as a companion to their
existing sign-in mechanisms, for example Google sign-in, and seamlessly sync
players' sign-in information across their devices to decrease onboarding churn
and increase D1 retention.
The API manage links between a user's Play Games Services (PGS) account 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
Google Play Games 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.
- 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.
Cardinality rules
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 among the game client, the game server,
and Google's 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.
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.
Flows for users without a PGS profile
You can store recall tokens for a user who hasn't created a PGS profile yet by
using profileless mode. However, there are two important caveats:
- You can't retrieve tokens for a user who doesn't have a PGS profile. Profile
creation is automatically prompted when the user tries to log into your game
with Play Games Services on a second device.
- You must follow
additional guidelines
to ensure you have an appropriate notice describing the following items and
obtaining the appropriate end-user consent:
- Your sharing of the data with Google to enable the Play Games account
linking feature.
- The availability of settings to manage this sharing, such as Play Games
settings.
- The processing of such data under the
Google Privacy
Policy
.
Store a token and persona pair
- A user without a PGS profile opens a game that has profileless recall
enabled.
- The Games SDK triggers an automatic sign-in, which fails because the user has
no PGS profile.
- The Games SDK shows a snackbar that informs the user that the game has
integration with Google. This snackbar is actionable?the user can disable
recall until a profile is created.
- The game requests recall access. Note that PGS rejects recall access requests
when there are PGS profiles on the device or when there are no Google
Accounts on the device. In that case, the game should proceed without using
PGS.
- After the user logs in with an in-game account, the game creates a token and
persona pair for the user that corresponds to their in-game account. The game
stores this pair with Google. The game might store more tokens later if the
user logs into other in-game accounts.
Launch a game on a new device
- A user without a PGS profile opens a game that has profileless recall enabled
on a device.
- The game records a profileless recall token as described in
Store a token
and persona pair
.
- The user opens the same game on a different device that has the same account
setup.
- The Games SDK triggers profile creation. The user can review and reject
previously stored recall tokens. The user creates a PGS profile at this time.
- The automatic sign-in into PGS completes, and the game receives the
authenticated status.
- The game retrieves recall tokens for the user as usual.
Next steps
In order to integrate the Recall API with your client and game server, follow
this
implementation guide
.