本页介绍了如何在游戏中实现 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 });
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 个令牌或角色。
在给定的时间只能为每位玩家的每个角色存储一个令牌。尝试存储具有相同角色的其他令牌会覆盖原始令牌。
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 令牌
检索在开发者拥有的所有游戏中存储的最新令牌
账号,则需要获取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 玩家资料的用户,请按以下步骤操作:
- 在 Play 开发者中为 PGS 游戏项目启用无资料找回功能 控制台。
- 请参阅本部分后面部分所述的附加条款。
- 将以下元数据标记添加到您的应用程序中 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 隐私权政策 政策,并获取合适的最终用户 同意在符合所有适用法律要求的情况下进行此类共享。