本页介绍了如何在游戏中实现 Recall API。其中首先介绍如何设置游戏服务器和客户端以支持该 API,然后介绍如何存储和检索令牌。
游戏服务器设置
设置您的游戏服务器,以便对 Google 服务器进行 Recall API 调用。
1. 设置您的 Play 游戏服务项目
(如果尚未完成)请按照设置 Google Play 游戏服务中的说明进行操作。
2. 为游戏设置服务账号
按照创建服务账号中的说明操作。最后,您应该得到一个包含服务账号凭据的 JSON 文件。
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 });
在游戏服务器中使用 Recall API
配置服务器和客户端后,您可以将 recallSessionID
从游戏客户端发送到游戏服务器,并按照以下指南开始使用 Java API 来存储、检索或删除 Recall 令牌服务器端。
存储令牌
您可以使用 LinkPersonaRequest
对象存储用户的角色和游戏令牌。您需要使用 GoogleCredential
来调用 Google API(如需了解上下文,请参阅调用 Google API)。请注意,根据 1:1 基数限制,您一次只能将一个角色与一个 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
}
检索令牌
您可以根据自己游戏的需求,通过以下三种方式获取代币。您可以请求以下内容:
- 与当前游戏关联的令牌,包括游戏级范围的 Recall 令牌。
- 开发者账号所拥有的所有游戏中存储的最后一个令牌。
- 给定开发者账号拥有的游戏列表,以及与每个游戏关联的所有 Recall 令牌。
游戏级范围的 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 令牌
如需检索 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.
}
开发者账号拥有的指定游戏列表中的所有 Recall 令牌
如需检索与 Google Play 管理中心中您的开发者账号拥有的游戏列表相关联的所有令牌,请从客户端获取 recallSessionId
并将其传递给 gamesPlayerTokens
API。提供 Application 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();
启用无配置文件模式
您可以按照以下步骤为没有 PGS 玩家资料的用户启用受限的 Recall API 功能:
<meta-data
android:name="com.google.android.gms.games.PROFILELESS_RECALL_ENABLED"
android:value="true" />
附加条款
除了遵守 Play 游戏服务条款外,您还同意,如果您针对没有 PGS 玩家资料的用户使用 Recall API(这会使您能够在用户没有 Play 游戏服务玩家资料的情况下与 Google 共享其数据),则必须先向最终用户提供适当的通知,说明以下事项:
- 您与 Google 分享这些数据以启用 Play 游戏账号关联功能。
- 是否提供用于管理此类共享的设置,例如通过 Play 游戏设置进行管理。
- 按照 Google 隐私权政策处理此类数据,并就此类共享征得最终用户的同意,以符合所有适用的法律要求。