PGS Recall API をゲームに統合する

このページでは、ゲーム内に Recall API を実装する方法について説明します。まず、ゲームサーバーとクライアントを API をサポートするように設定してから、トークンの保存と取得の方法について説明します。

ゲームサーバーのセットアップ

Google サーバーに対して Recall API 呼び出しを行うようにゲームサーバーをセットアップします。

1. Play Games サービス プロジェクトをセットアップする

（まだ実施していない場合）Google Play Games サービスをセットアップする手順に沿って操作します。

注: リコール トークンとペルソナは PGS プロジェクトごとに利用できます。つまり、トークンとペルソナは PGS プロジェクトごとに保存されます。個別の PGS プロジェクトでは、PGS プロファイルとペルソナの間にリンクの個別のコレクションが存在します。PGS プロジェクトの設定方法を決定する際には、こちらのドキュメントを確認することをおすすめします。

2. ゲームのサービス アカウントをセットアップする

サービス アカウントの作成の手順に沿って操作します。最後に、サービス アカウントの認証情報を含む JSON ファイルを作成する必要があります。

注: Recall API はサーバー間 API です。そのため、Recall API は、他の Games API がゲームサーバーとエンドユーザーの両方を認証するために使用する通常の 3-legged OAuth ではなく、サービス アカウントを使用してゲームサーバーの認証を行います。

3. PlayGamesService 用のサーバーサイド 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 サーバーと通信するために使用するリコール セッション 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
    });

ゲームサーバー内で Recall API を使用する

サーバーとクライアントを構成すると、recallSessionID をゲーム クライアントからゲームサーバーに送信し、以下のガイダンスに沿って Java API を使用して、サーバーサイドでリコール トークンを保存、取得、削除できます。

トークンを保存する

ユーザーのペルソナとゲームトークンは、LinkPersonaRequest オブジェクトを使用して保存できます。Google API を呼び出すには、GoogleCredential を使用する必要があります（コンテキストについては、Google API の呼び出しをご覧ください）。1 対 1 のカーディナリティ制約により、一度に 1 つのペルソナを 1 つの PGS プロファイルにしかリンクできないことに注意してください（その逆も同様です）。この PGS プロファイルがすでに別のペルソナとリンクされている場合は、解決ポリシーを設定する必要があります。

必要に応じて、トークンに TTL を設定することもできます。これは、Durations オブジェクトを使用してトークンの有効期間を宣言するものです。メソッドに指定された期間から有効期限を設定する SetTtl()（以下を参照）を使用して、この値を設定することもできます。または、setExpireTime() を使用すると、トークンの有効期限が切れる正確な時間を設定できます。

ペルソナとゲームトークンは暗号化する必要があります。個人を特定できる情報を含めることはできません。ペルソナとトークンの文字列は最大 256 文字で、各ゲームのプレーヤーごとに最大 20 個のトークンまたはペルソナを保存できます。

各プレーヤーのペルソナごとに、所定の時間に 1 つのトークンのみを保存できます。同じペルソナを持つ別のトークンを保存しようとすると、元のトークンは上書きされます。

注: トークンの暗号化に使用する暗号鍵は、アプリケーションごとに一意である必要があります。ゲームを別のデベロッパーに移行した場合は、暗号鍵を新しいオーナーに渡す必要があります。元の暗号鍵がないとリコール トークンは復号できません。

注: プロフィールのないユーザー用に作成されたトークンのデフォルトの TTL は 30 日間です。それ以外の場合、PGS プロファイルを持つユーザーのトークンにはデフォルトの TTL がありません。

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
}

トークンを取得する

トークンを取得するには、ゲームのニーズに応じて次の 3 つの方法があります。次のリクエストを行うことができます。

• 現在のゲームに関連付けられているトークン（ゲーム スコープのリコール トークンを含む）。
• デベロッパー アカウントが所有するすべてのゲームで最後に保存されたトークン。
• デベロッパー アカウントが所有するゲームのリストと、各ゲームに関連付けられているすべてのリコール トークン。

注: リコール トークンをリクエストしても、API からペルソナを表す文字列は返されません。

ゲーム スコープの再現トークン

現在のゲームからリコール トークンを取得するには、クライアントから 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 Console でデベロッパー アカウントが所有するすべてのゲームに保存されている最新のトークンを取得するには、次のコード スニペットに示すように、クライアントから 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 Console でデベロッパー アカウントが所有するゲームのリストに関連付けられているすべてのトークンを取得するには、クライアントから 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 プロファイルのないユーザーに対して制限付きの Recall API 機能を有効にする手順は次のとおりです。

1. Google Play Console で、PGS ゲーム プロジェクトのプロファイルレス リコールを有効にします。
2. このセクションの後半で説明する追加の用語を確認します。
3. 次のメタデータ タグをアプリ マニフェストに追加します。

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

追加規約

Google Play Games サービス利用規約に加えて、PGS プロファイルのないユーザーに対して Recall API を使用する場合、エンドユーザーが Google Play Games サービス プロファイルを持たずにエンドユーザーのデータを Google と共有できるようにする場合、そのようなデータを Google と共有する前に、エンドユーザーに以下の内容を記載した適切な通知を提供することに同意するものとします。

1. Google とデータを共有して Play Games アカウントのリンク機能を有効にすること。
2. このような共有を管理するための設定（Google Play Games の設定など）が利用可能かどうか。
3. Google プライバシー ポリシーに基づいてそのようなデータを処理し、適用されるすべての法的要件を満たすように、そのような共有について適切なエンドユーザーの同意を得る。