本頁面由 Cloud Translation API 翻譯而成。

在遊戲中整合 PGS Recall API

本頁面說明如何在遊戲中實作 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 基數限制條件，您可以一次只能將一個人物角色連結至一個 Play 遊戲服務設定檔，反之亦然。將解決政策，以免這個 Play 遊戲服務設定檔已連結至其他設定檔人物角色。

或者，您可以選擇為權杖設定存留時間，宣告權杖的保留時間是否有效 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 遊戲專案啟用無設定檔召回功能控制台。
詳閱本節稍後所述的附加條款。
將下列中繼資料標記新增至您的應用程式資訊清單：

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

其他條款

除了遵守《Play 遊戲服務條款》「服務」，您同意如果針對 Recall API 使用 Recall API，您同意沒有 Play 遊戲服務設定檔的使用者，因而可與他人分享內容使用者的資料，而沒有 Play 遊戲服務設定檔。資料提供給 Google 前，您必須先適當聲明：1) 如果您與 Google 分享資料以啟用 Play 遊戲帳戶連結功能, 2) 管理設定是否可用例如透過 Play 遊戲設定分享項目，以及 3) 處理 Google 隱私權政策政策及取得合適的使用者符合所有適用法律要求的共用權限。