Recall API

借助 Recall API，您可以将 Google Play 游戏服务用户与其游戏内 账号无缝关联，从而实现自动恢复进度。您可以在游戏服务器中存储 Recall 令牌 ，并将这些令牌与用户的 Google Play 游戏服务 玩家资料相关联。使用 Recall API 是可选操作，如果您没有自己的 强大身份后端，建议您使用此方法来实现 无缝恢复。

术语

本文档使用以下术语：

Recall 令牌：存储在游戏服务器上的安全密钥，充当 玩家的 Play 游戏服务账号与其 游戏内账号之间的关联。

会话 ID：由 Play 游戏服务 SDK 在玩家的设备上生成的临时唯一标识符。它表示 后端服务器发出的请求源自玩家设备上的合法有效 游戏会话。

示例场景

以下是说明可以如何使用 Recall API 的示例场景：

  1. 用户正在玩一款游戏，其开发者可以通过身份系统跟踪 用户进度，并同时使用 PGS 和其他身份验证方法让 用户登录其游戏。在此示例中，用户登录了其 PGS 账号 Laura，然后使用开发者的身份系统（名为 Racer94）创建了一个游戏内账号。当用户玩游戏时，开发者的游戏服务器会同步其进度。

    用户使用 PGS 和游戏内账号登录

  2. 此外，开发者还在 Google 上保存一个 Recall 令牌，该令牌与用户的游戏内账号相对应。Google 会根据用户的 PGS 玩家资料自动存储该 Recall 令牌。

    游戏服务器将 Recall 令牌存储在 Google 服务器中

  3. 现在，用户第一次决定在 Google Play 游戏电脑版 平台上玩游戏。系统会自动使用用户的 PGS 账号进行身份验证，而游戏客户端会检查是否有可为该 PGS 用户恢复的进度。然后，游戏服务器会 向 Google 查询，以确认是否有可供此 PGS 账号使用的令牌。由于存在，Google 会发回 Recall 令牌，游戏服务器使用该 令牌查找用户的关联账号 Racer94，并恢复其 游戏进度。由于使用 PGS 进行身份验证是一次顺畅无碍的体验，因此无需用户输入 用户名或密码，应用即会恢复 用户的进度。此外，开发者可将 PGS 身份验证机制与自己现有的身份系统搭配使用，并依赖于 Google 来存储玩家进度与其 PGS 账号之间的关联。

    游戏服务器使用 Recall 令牌恢复进度

如前面的示例所示，Recall API 主要执行以下两项操作：

  • 当用户使用其中一个游戏内 账号登录时，将 令牌存储 在 Google 中。

  • 检索 用户的令牌，以便恢复其游戏内 账号。

除 Recall 令牌外，Recall API 还需要与游戏内账号对应的稳定标识符 （称为角色）。您可以将 角色视为在 开发者身份系统中代表用户的游戏内账号的标签，而将 Recall 令牌视为用于将用户的游戏内账号恢复至游戏的密钥。角色和令牌值不得在不同 PGS 项目中重复使用。此外，虽然 Recall 令牌可能会 随时间而变化，但角色应根据用户的游戏内 账号保持稳定。

用于存储和检索 Recall 令牌的技术流程

本部分介绍了在使用 Google 服务器存储和检索 Recall 令牌时游戏客户端与服务器之间的技术流程。

第 1 步：对 PGS 用户进行身份验证并检索会话 ID

游戏会初始化 PGS SDK 并尝试让用户使用 PGS 进行身份验证。

使用 PGS 进行用户身份验证

假设用户已通过身份验证，在游戏客户端上从游戏 SDK 请求会话 ID，并从 Google 的 OAuth 后端请求 OAuth 2.0 令牌。会话 ID 和 OAuth 2.0 令牌用于与 Google 游戏后端进行通信。

开发者请求会话 ID

第 2 步：检索任何可用的 Recall 令牌

请求与 PGS 用户账号关联的任何 Recall 令牌。如果存在令牌，请继续执行第 3a 步并恢复进度。否则，如果这是新用户且没有令牌，请继续执行第 3b 步并存储新令牌。

开发者检索 Recall 令牌

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

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

开发者从 Recall 令牌恢复数据

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

由于不存在令牌，因此不会恢复任何进度。用户继续使用开发者的身份系统进行平台身份验证 ，或创建新账号（如果不存在此类账号 ）。注意：这不是使用 PGS 进行身份验证（该过程已完成），而是 使用 PGS 之外的开发者身份系统进行身份验证。

用户使用其游戏内账号进行身份验证

创建一个加密的 Recall 令牌（该令牌会对用户的游戏内账号进行编码），并 将该令牌连同会话 ID 和 OAuth 2.0 令牌一起发送给 Google。此时，Google 会在发送的 Recall 令牌与玩家的 PGS 账号之间建立关联。

开发者存储 Recall 令牌

没有 PGS 玩家资料的用户的流程

您可以使用无玩家资料模式为尚未创建 PGS 玩家资料的用户存储 Recall 令牌，方法是 使用无玩家资料模式。不过，请注意以下两点重要事项：

  • 您无法为没有 PGS 玩家资料的用户检索令牌。当用户尝试在另一部设备上使用 Play 游戏服务登录您的游戏时，系统会自动提示用户创建玩家资料。
  • 您必须遵循其他准则 以确保您提供适当的通知来描述以下各项内容并 获得适当的最终用户同意：
    • 您与 Google 共享数据以启用 Play 游戏账号 关联功能。
    • 用于管理此共享的设置（例如 Play 游戏 设置）的可用性。
    • 根据《Google Privacy Policy》处理此类数据。

存储令牌和角色对

没有 PGS 玩家资料的用户打开游戏

  1. 没有 PGS 玩家资料的用户打开已启用无玩家资料 Recall 的游戏。
  2. 游戏 SDK 会触发自动平台身份验证，但由于用户没有 PGS 玩家资料，因此身份验证失败 。
  3. 游戏 SDK 会显示一个 snackbar，告知用户游戏已与 Google 集成。此 snackbar 是可操作的，用户可以停用 Recall，直到创建玩家资料。
  4. 游戏请求 Recall 访问权限。请注意，当设备上有 PGS 玩家资料或设备上没有 Google 账号时，PGS 会拒绝 Recall 访问权限请求 。在这种情况下，游戏应在不使用 PGS 的情况下继续运行。
  5. 用户使用游戏内账号登录后，游戏会为用户创建与其游戏内账号对应的令牌和 角色对。游戏会将此对存储在 Google 中。如果 用户登录其他游戏内账号，游戏稍后可能会存储更多令牌。

在新设备上启动游戏

  1. 没有 PGS 玩家资料的用户在设备上打开已启用无玩家资料 Recall 的游戏 在设备上。
  2. 游戏会记录无玩家资料 Recall 令牌，如存储令牌 和角色对中所述。
  3. 用户在设置了相同账号的其他设备上打开同一款游戏 。
  4. 游戏 SDK 会触发玩家资料创建。用户可以查看并拒绝 之前存储的 Recall 令牌。用户此时会创建 PGS 玩家资料。
  5. 自动平台身份验证到 PGS 完成，游戏 会收到已通过身份验证的状态。
  6. 游戏会照常检索用户的 Recall 令牌。

后续步骤

如需将 Recall API 与您的客户端和游戏服务器集成，请遵循本指南。