本頁面說明如何在遊戲中實作 Recall API。首先說明如何設定遊戲伺服器和用戶端來支援這個 API,接著逐步解說如何儲存及擷取符記。
遊戲伺服器設定
設定遊戲伺服器,向 Google 伺服器發出 Recall API 呼叫。
設定 Play 遊戲服務專案
(如果尚未完成設定) 按照「設定 Google Play 遊戲服務」的指示操作。
為遊戲設定服務帳戶
按照「建立服務帳戶」的指示操作。最後,您應該會取得含有服務帳戶憑證的 JSON 檔案。
下載 Play 遊戲服務的伺服器端 Java 程式庫
下載最新版 google-api-services-games
程式庫
並上傳至你的伺服器
為 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 伺服器連線的喚回工作階段 ID。
Java SDK
在用戶端中設定 Java SDK,
請務必加上
com.google.android.gms:play-services-games-v2:19.0.0
和
Gradle 中的 com.google.android.gms:play-services-tasks:18.0.2
以上版本
檔案。
如要使用正確資訊與 Google 伺服器連線,請提出 從用戶端 SDK 擷取工作階段 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 儲存、擷取或刪除喚回符記。
儲存符記
使用 LinkPersonaRequest
物件儲存使用者的人物角色和遊戲符記。
使用 GoogleCredential
呼叫 Google
API
為了遵守 1:1 基數限制,您只能將一個人物角色連結至一個 PGS 設定檔 (反之亦然)。建議您設定這項解決政策,避免該 PGS 設定檔已連結至另一個人物角色。
或者,您可以選擇為符記設定存留時間,使用 Durations
物件宣告符記的有效時間長度。您可以選擇使用 SetTtl()
(如下所示),依方法中指定的時間長度設定有效期限;或使用 setExpireTime()
來設定符記確切的到期時間。
您必須對人物角色和遊戲符記加密,且不得包含個人識別資訊。人物角色和符記的字串長度上限為 256 個字元,且每名玩家在每個遊戲中最多可儲存 20 個符記或人物角色。
系統在特定時間內只能為每名玩家的每個人物角色儲存一個符記。如果您嘗試儲存相同人物角色的其他符記,系統會覆寫原始符記。
import com.google.api.services.games.Games.Recall.LinkPersona;
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.Recall.RetrieveTokens;
// ...
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
}
刪除喚回符記
必要時,您也可以透過以下呼叫刪除喚回符記:
import com.google.api.services.games.Games.Recall.UnlinkPersona;
// ...
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();
// Confirm that the unlinking process completed successfully.
boolean unlinked = unlinkPersonaResponse.isUnlinked();
啟用無設定檔模式
您可以啟用有限的 Recall API 功能 適用於沒有 Play 遊戲服務設定檔的使用者,步驟如下:
- 在 Play 開發人員控制台中為 PGS 遊戲專案啟用無設定檔召回功能。
- 請參閱本節後續所述的其他條款。
- 將下列中繼資料標記新增至您的應用程式 manifest:
<meta-data
android:name="com.google.android.gms.games.PROFILELESS_RECALL_ENABLED"
android:value="true" />
其他條款
除了遵守《Google Play 遊戲服務條款》外,您也同意,如果您為沒有 PGS 設定檔的使用者使用 Recall API,也就是在使用者沒有 Play 遊戲服務設定檔的情況下,與 Google 分享使用者資料,則必須在與 Google 分享這類資料前,向使用者提供適當的通知,說明 1) 您與 Google 分享資料的目的,以啟用 Play 遊戲帳戶連結功能;2) 可用來管理這類分享行為的設定 (例如透過 Play 遊戲設定);以及 3) 根據《Google 隱私權政策》處理這類資料,並取得符合所有適用法律規定的使用者同意,以便進行這類分享。