在游戏中集成 PGS 回忆 API

本页面介绍了如何在游戏中实现回忆 API。它首先介绍了如何设置游戏服务器和客户端以支持 API，然后详细说明了如何存储和检索令牌。

游戏服务器设置

设置您的游戏服务器，以便向 Google 服务器发出回忆 API 调用。

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

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

2. 为游戏设置服务帐号

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

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

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

4. 准备回忆 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 服务器通信的回忆会话 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 请求一个回忆会话 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 请求一个回忆会话 ID，并将其发送到您游戏的服务端。

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

在游戏服务器中使用回忆 API

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

存储令牌

用户的角色和游戏令牌可以通过 LinkPersonaRequest 对象进行存储。您需要使用 GoogleCredential 来调用 Google API（如需了解背景信息，请参阅调用 Google API）。请注意，根据一对一基数约束，您一次只能将一个角色关联到一个 PGS 资料（反之亦然）。如果此 PGS 资料已关联到其他角色，您应设置解析政策。

（可选）您可以选择为令牌设置 TTL（生存时间），使用 Durations 对象声明令牌的有效期。您可以选择使用 SetTtl()（如下所示）来设置，该方法根据指定的时间量设置过期日期，或者使用 setExpireTime()，该方法允许您设置令牌的确切过期时间。

您必须加密角色和游戏令牌，它们不能包含个人身份信息。角色和令牌字符串的长度最多为 256 个字符，每个玩家每款游戏最多可以存储 20 个令牌或角色。

每个玩家每个角色在给定时间只能存储一个令牌。尝试使用相同的角色存储另一个令牌会覆盖原始令牌。

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
}

检索令牌

根据您游戏的需求，有三种选项可用于检索令牌。您可以请求以下内容：

与当前游戏关联的令牌，包括游戏范围的回忆令牌。
开发者帐号拥有的所有游戏中存储的最后一个令牌。
给定开发者帐号拥有的游戏列表，与每个游戏关联的所有回忆令牌。

游戏范围的回忆令牌

要从当前游戏检索回忆令牌，请从客户端获取 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
}

开发者帐号拥有的所有游戏的最新回忆令牌

如以下代码段所示，要检索 Google Play 管理中心内开发者帐号拥有的所有游戏中存储的最新令牌，您需要从客户端获取 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.
}

开发者帐号拥有的给定游戏列表中的所有回忆令牌

如要检索 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.
}

删除回忆令牌

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

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

启用无资料模式

您可以按照以下步骤为没有 PGS 资料的用户启用有限的回忆 API 功能：

在 Play 管理中心中为您的 PGS 游戏项目启用无资料回忆功能。
查看本节后面描述的附加条款。
将以下元数据标记添加到您的应用清单中

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

附加条款

除遵守 Play 游戏服务服务条款之外，您还同意，如果您将回忆 API 用于没有 PGS 资料的用户（这使得可以在用户没有 Play 游戏服务资料的情况下与 Google 共享最终用户数据），则在与 Google 共享此类数据之前，您必须向最终用户提供适当的通知，说明以下内容：

您与 Google 共享数据以启用 Play 游戏帐号关联功能。
可用的用于管理此类共享的设置，例如通过 Play 游戏设置提供的设置。
根据 Google 隐私权政策处理此类数据，并获得符合所有适用法律要求的此类共享的最终用户同意。