在游戏中集成 PGS Recall API

本页介绍了如何在游戏中实现 Recall API。其中首先介绍如何设置游戏服务器和客户端以支持该 API，然后介绍如何存储和检索令牌。

游戏服务器设置

设置您的游戏服务器，以便对 Google 服务器进行 Recall API 调用。

1. 设置您的 Play 游戏服务项目

（如果尚未完成）请按照设置 Google Play 游戏服务中的说明进行操作。

注意：Recall 令牌和角色是按 PGS 项目提供的。这意味着令牌和角色是按 PGS 项目存储的，对于单独的 PGS 项目，PGS 玩家资料和角色之间存在单独的链接集合。我们建议您在确定如何设置 PGS 项目时查看此文档。

2. 为游戏设置服务账号

按照创建服务账号中的说明操作。最后，您应该得到一个包含服务账号凭据的 JSON 文件。

注意：Recall API 是一种纯服务器到服务器 API。因此，Recall API 使用服务账号对游戏服务器进行身份验证，而不是使用其他 Games API 用于对游戏服务器和最终用户进行身份验证的常规三方模式 OAuth。

3. 下载适用于 PlayGamesServices 的服务器端 Java 库

下载最新的 google-api-services-games 库，并将其上传到您的服务器。

4. 准备用于 Recall API 调用的凭据

如需了解更多背景信息，请参阅准备进行已获授权的 API 调用。

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();

游戏客户端设置

设置游戏客户端，以检索您的服务器用于与 Google 服务器进行通信的 Recall 会话 ID。

Java SDK

在客户端中设置 Java SDK，并确保在 Gradle 文件中包含 com.google.android.gms:play-services-games-v2:19.0.0 和 com.google.android.gms:play-services-tasks:18.0.2 或更高版本。

若要使用正确的信息与 Google 的服务器进行通信，您需向客户端 SDK 请求 Recall 会话 ID，并将该 ID 发送到游戏服务器。

Kotlin

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

Java

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

Unity SDK

如果尚未完成，请在客户端中设置 Unity SDK。

若要使用正确的信息与 Google 的服务器进行通信，您需向客户端 SDK 请求 Recall 会话 ID，并将该 ID 发送到游戏服务器。

PlayGamesPlatform.Instance.RequestRecallAccess(
    recallAccess => {
        string recallSessionId = recallAccess.sessionId;
        // Send the recallSessionId to your game server
    });

在游戏服务器中使用 Recall API

配置服务器和客户端后，您可以将 recallSessionID 从游戏客户端发送到游戏服务器，并按照以下指南开始使用 Java API 来存储、检索或删除 Recall 令牌服务器端。

存储令牌

您可以使用 LinkPersonaRequest 对象存储用户的角色和游戏令牌。您需要使用 GoogleCredential 来调用 Google API（如需了解上下文，请参阅调用 Google API）。请注意，根据 1:1 基数限制，您一次只能将一个角色与一个 PGS 玩家资料相关联（反之亦然）。您应设置解决政策，以防此 PGS 玩家资料已与其他角色关联。

（可选）您可以选择设置令牌的 TTL，使用 Durations 对象来声明令牌的有效时长。您可以选择使用 SetTtl()（如下所示）或 setExpireTime() 进行设置，前者会根据方法中指定的时间量设置失效日期，后者允许您设置确切的令牌到期时间。

您必须对角色和游戏令牌进行加密，且它们不能包含个人身份信息。角色和令牌字符串不得超过 256 个字符，并且每个游戏最多可以为每位玩家存储 20 个令牌或角色。

在给定的时间只能为每位玩家的每个角色存储一个令牌。尝试存储具有相同角色的其他令牌会覆盖原始令牌。

注意：每个应用用于加密令牌的加密密钥应该是唯一的。如果将游戏转移给其他开发者，则必须将加密密钥也传递给新所有者。Recall 令牌无法解密，除非 原始加密密钥。

注意 ：为无配置文件用户创建的令牌 默认的 TTL 为 30 天。否则，对于拥有 PGS 玩家资料的用户，令牌不会 具有默认 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
}

检索令牌

有三种方法可以检索代币，具体取决于游戏的需求。您可以 请求以下内容：

• 与当前游戏关联的令牌，包括游戏范围的 Recall 令牌。
• 在开发者账号拥有的所有游戏中存储的最后一个令牌。
• 根据某个开发者账号拥有的游戏列表，所有 Recall 令牌 与每款游戏相关的数据

。

注意： 当您请求 Recall 令牌时，API 不会返回 代表职能角色。

游戏范围的 Recall 令牌

要从当前游戏中检索 Recall 令牌，请获取 recallSessionId 并将其传递到 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
}

开发者账号拥有的所有游戏的最新 Recall 令牌

检索在开发者拥有的所有游戏中存储的最新令牌 账号，则需要获取recallSessionId 并将其传递到 lastTokenFromAllDeveloperGames API，如下所示： 如以下代码段所示。作为响应的一部分，您可以检查 关联的应用 ID 这个词元。

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.
}

开发者账号拥有的指定游戏列表中的所有 Recall 令牌

为了检索与以下游戏拥有的游戏列表关联的所有代币： 在 Google Play 管理中心内登录您的开发者账号，请获取 recallSessionId 并将其传递到 gamesPlayerTokens API。提供一个 应用 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.
}

删除 Recall 令牌

如果需要，您还可以通过以下调用删除 Recall 令牌：

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();

启用无配置文件模式

您可以启用有限的 Recall API 功能 对于没有 PGS 玩家资料的用户，请按以下步骤操作：

1. 在 Play 开发者中为 PGS 游戏项目启用无资料找回功能 控制台。
2. 请参阅本部分后面部分所述的附加条款。
3. 将以下元数据标记添加到您的应用程序中 manifest：

<meta-data
  android:name="com.google.android.gms.games.PROFILELESS_RECALL_ENABLED"
  android:value="true" />

附加条款

除了遵守《Play 游戏服务服务条款》 服务，即表示您同意： 您可以为没有 PGS 玩家资料的用户使用 Recall API，从而实现分享 最终用户在没有 Play 游戏服务玩家资料的情况下与 Google 分享的数据； 在与 Google 分享此类数据之前，您必须向最终用户 适当的通知，说明 1) 您与 Google 分享数据以实现 Play 游戏账号关联功能；2) 是否提供用于管理各种设置 例如通过 Play 游戏设置分享的数据；以及 3) 对 此类数据的 Google 隐私权政策 政策，并获取合适的最终用户 同意在符合所有适用法律要求的情况下进行此类共享。