召回 API

召回 API 允许游戏通过在 Google 服务器上存储召回令牌来管理 Google Play 游戏服务 (PGS) 用户及其游戏内帐户之间的链接。以下是召回 API 使用方式的一个示例场景。

  1. 用户正在玩一款游戏，开发者使用身份系统来跟踪用户进度，并使用 PGS 与其他身份验证方法并行登录用户到他们的游戏。在这个例子中，用户登录到他们的 PGS 帐户Laura，并使用开发者的身份系统创建一个名为Racer94的游戏内帐户。当用户玩游戏时，开发者的游戏服务器会同步他们的进度。

    User is logged in with PGS and an in-game account

  2. 另外，开发者会将召回令牌与 Google 一起保存，该令牌与用户的游戏内帐户相对应。Google 会自动将该召回令牌存储在用户的 PGS 个人资料中。

    Game server stores recall token with Google servers

  3. 用户现在决定首次在GPG 电脑版上玩游戏。用户会自动使用其 PGS 帐户登录，游戏客户端会检查此 PGS 用户是否有任何可用的进度。然后，游戏服务器查询 Google 以查看此 PGS 帐户是否有任何令牌。如果有，Google 会发回召回令牌，游戏服务器使用该令牌查找用户的关联帐户 Racer94 并恢复其进度。由于使用 PGS 登录是一种无摩擦的体验，因此应用程序会在无需用户输入用户名或密码的情况下恢复用户的进度。此外，开发者可以使用 PGS 登录与其现有的身份系统一起使用，并依赖 Google 来存储玩家进度与其 PGS 帐户之间的链接。

    Game server restores progress with recall token

如前面的示例所示，召回 API 执行两个主要操作

  • 存储用户使用其中一个游戏内帐户登录时与 Google 一起使用的令牌。

  • 检索用户的令牌以恢复其游戏内帐户。

除了召回令牌外，召回 API 还需要一个与游戏内帐户相对应的稳定标识符（称为角色），以强制执行基数约束。您可以将角色视为代表用户在开发者身份系统中的游戏内帐户的标签，并将召回令牌视为用于将用户的游戏内帐户恢复到游戏的密钥。角色和令牌值不得在不同的PGS 项目中重复使用。此外，虽然召回令牌可能会随着时间的推移而更改，但角色应根据用户的游戏内帐户保持稳定。

基数规则

召回 API 强制执行 PGS 个人资料和游戏内帐户之间的 1:1 关系（称为基数规则），其中一个角色只能链接到一个 PGS 个人资料，一个 PGS 个人资料只能链接到一个角色。角色用作游戏内帐户的稳定标识符，因为召回令牌可能会随着时间的推移而更改。

与 PGS 个人资料关联的角色也可能随着时间的推移而更改（因为不同的游戏内帐户链接到 PGS 个人资料）。

存储和检索召回令牌的技术流程

本节介绍在存储和检索召回令牌时，游戏客户端和服务器与 Google 服务器之间的技术流程。

步骤 1：登录 PGS 用户并检索会话 ID

游戏初始化 PGS SDK 并尝试使用 PGS 登录用户。

User signs in with PGS

假设用户已登录，请从游戏客户端上的游戏 SDK 请求会话 ID，并从 Google 的 OAuth 后端请求 OAuth 2.0 令牌。会话 ID 和 OAuth 2.0 令牌用于与 Google 游戏后端通信。

Developer requests a session ID

步骤 2：检索任何可用的召回令牌

请求与 PGS 用户帐户关联的任何召回令牌。如果存在令牌，转到步骤 3a 并恢复进度。否则，如果这是一个新用户并且他们没有令牌，转到步骤 3b 并存储新令牌。

Developer retrieves recall token

步骤 3a：如果存在令牌，则恢复进度

如果存在令牌，请检索并解密令牌，然后恢复用户数据。

Developer restores data from recall token

步骤 3b：如果不存在令牌，则存储令牌

由于不存在令牌，因此不会恢复进度。用户继续使用开发者的身份系统登录，或者如果不存在帐户则创建新帐户。注意 - 这不是使用 PGS 登录（这已经完成），而是使用 PGS 之外的开发者的身份系统登录。

User signs in with their in-game account

创建一个加密的召回令牌，该令牌对用户的游戏内帐户进行编码，并将其与会话 ID 和 OAuth 2.0 令牌一起发送到 Google。此时，Google 会在发送的召回令牌和玩家的 PGS 帐户之间创建一个关联。

Developer stores recall token

没有 PGS 个人资料的用户的流程

您可以通过使用无个人资料模式来存储尚未创建 PGS 个人资料的用户的召回令牌。但是，有两个重要的注意事项

  • 您无法检索没有 PGS 个人资料的用户的令牌。当用户尝试在第二个设备上使用 Play 游戏服务登录您的游戏时，会自动提示创建个人资料。
  • 您必须遵循其他指南以确保您有适当的通知来描述以下项目并获得适当的最终用户同意
    • 您与 Google 共享数据以启用 Play 游戏帐户链接功能。
    • 管理此共享的设置的可用性，例如 Play 游戏设置。
    • 根据Google 隐私权政策处理此类数据。

存储令牌和角色对

User without PGS profile opens a game

  1. 没有 PGS 个人资料的用户打开启用了无个人资料召回的游戏。
  2. 游戏 SDK 会触发自动登录，但由于用户没有 PGS 个人资料，因此登录失败。
  3. 游戏 SDK 会显示一个信息栏，通知用户该游戏已与 Google 集成。此信息栏是可操作的——用户可以在创建个人资料之前禁用召回。
  4. 游戏请求召回访问权限。请注意，当设备上有 PGS 个人资料或设备上没有 Google 帐户时，PGS 会拒绝召回访问权限请求。在这种情况下，游戏应在不使用 PGS 的情况下继续进行。
  5. 用户使用游戏内账号登录后，游戏会为用户创建一个与游戏内账号对应的令牌和角色对。游戏会将这对信息存储在 Google 中。如果用户登录其他游戏内账号，游戏可能会稍后存储更多令牌。

在新设备上启动游戏

  1. 在启用了无资料恢复功能的设备上，一位没有 PGS 个人资料的用户打开游戏。
  2. 游戏会记录一个无资料恢复令牌，详见 存储令牌和角色对。
  3. 用户在具有相同帐户设置的不同设备上打开同一游戏。
  4. 游戏 SDK 触发个人资料创建。用户可以查看和拒绝之前存储的恢复令牌。用户此时创建 PGS 个人资料。
  5. 自动登录 PGS 完成，游戏收到身份验证状态。
  6. 游戏照常检索用户的恢复令牌。

后续步骤

为了将恢复 API 集成到您的客户端和游戏服务器，请遵循此指南。