Recall API を使用すると、ゲームは Google サーバーにリコール トークンを保存することにより、Google Play Games サービス（PGS）ユーザーとゲーム内アカウント間のリンクを管理できます。Recall API の使用例を次に示します。
ユーザーがプレイするゲームで、デベロッパーがユーザーの進捗状況を追跡する ID システムを用意し、ユーザーがゲームにログインする際には PGS を他の認証方法と同時に使用します。この例では、ユーザーが PGS アカウント Laura にログインし、Racer94 というデベロッパーの ID システムを使ってゲーム内アカウントを作成します。ユーザーがゲームをプレイすると、デベロッパーのゲームサーバーが進行状況を同期します。
これとは別に、デベロッパーはユーザーのゲーム内アカウントに対応するリコール トークンを Google に保存します。Google は、そのリコール トークンをユーザーの PGS プロファイルに自動的に保存します。
ユーザーは、PC 版 GPG で初めてゲームをプレイすることにしました。ユーザーは PGS アカウントで自動的に認証され、ゲーム クライアントは、この PGS ユーザーに利用可能な進行状況があるかどうかを確認します。ゲームサーバーは Google に対してクエリを実行し、この PGS アカウント用のトークンがあるかどうかを調べます。Google がリコール トークンを送り返すと、ゲームサーバーがそのトークンを使用してユーザーに関連付けられているアカウント Racer94 を見つけ、進行状況を復元します。PGS による認証はスムーズに処理され、ユーザーがユーザー名やパスワードを入力しなくても、アプリによって進行状況が復元されます。さらに、デベロッパーは既存の ID システムで PGS 認証を使用し、プレーヤーの進行状況と PGS アカウント間のリンクの保存を Google に任せることができます。
上記の例に示すように、Recall API で実行される主なアクションは 2 つあります。
ユーザーがゲーム内アカウントのいずれかでログインしたときに、Google にトークンを保存します。
ゲーム内アカウントを復元するためにユーザーのトークンを取得します。
Recall API では、リコール トークンに加えて、ゲーム内アカウントに対応する安定した識別子（ペルソナ）も必要です。ペルソナは、デベロッパーの ID システム内でユーザーのゲーム内アカウントを表すラベルと考えることができます。また、リコール トークンは、ユーザーのゲーム内アカウントをゲームに復元するために使用されるキーと考えることができます。ペルソナとトークンの値は、異なる PGS プロジェクトで再利用できません。また、リコール トークンは時間の経過とともに変更される可能性がありますが、ペルソナはユーザーのゲーム内アカウントに応じて安定している必要があります。
リコール トークンの保存と取得の技術的フロー
このセクションでは、リコール トークンを保存および取得する際の、ゲーム クライアントおよびサーバーと Google サーバー間の技術的フローについて説明します。
ステップ 1: PGS ユーザーを認証してセッション ID を取得する
ゲームは PGS SDK を初期化し、PGS でのユーザー認証を試みます。
ユーザーが認証されていることを前提として、ゲーム クライアントの Games SDK にセッション ID をリクエストし、Google の OAuth バックエンドに OAuth 2.0 トークンをリクエストします。セッション ID と OAuth 2.0 トークンは、Google ゲームのバックエンドとの通信に使用されます。
ステップ 2: 利用可能なリコール トークンを取得する
PGS ユーザーのアカウントに関連付けられているリコール トークンをリクエストします。トークンがある場合は、ステップ 3a に進み、進行状況を復元します。新規ユーザーでトークンがない場合は、ステップ 3b に進み、新しいトークンを保存します。
ステップ 3a: トークンが存在する場合は、進行状況を復元する
トークンがある場合は、トークンを取得して復号し、ユーザーデータを復元します。
ステップ 3b: トークンが存在しない場合はトークンを保存する
トークンが存在しないため、進行状況は復元されません。ユーザーはデベロッパーの ID システムでプラットフォーム認証を行うか、アカウントが存在しない場合は新しいアカウントを作成します。注: （すでに実行済みの）PGS で認証するのではなく、PGS の外部にあるデベロッパーの ID システムで認証します。
ユーザーのゲーム内アカウントをエンコードした、暗号化されたリコール トークンを作成し、セッション ID と OAuth 2.0 トークンとともに Google に送信します。この時点で、Google は送信されたリコール トークンとプレーヤーの PGS アカウントの関連付けを作成します。
PGS プロファイルのないユーザーのフロー
プロファイルなしモードを使用すると、まだ PGS プロファイルを作成していないユーザーのリコール トークンを保存できます。ただし、次の 2 つの重要な注意点があります。
- PGS プロファイルがないユーザーのトークンを取得することはできません。ユーザーが 2 台目のデバイスで Play ゲームサービスを使用してゲームにログインしようとすると、プロフィール作成が自動的に促されます。
- 次の項目を説明し、適切なエンドユーザーの同意を得るための適切な通知を確実に表示するには、追加のガイドラインに沿う必要があります。
- Play ゲーム アカウントのリンク機能を有効にするために、データを Google と共有すること。
- この共有を管理するための設定（Play ゲームの設定など）の利用可否。
- Google プライバシー ポリシーに基づくデータの処理。
トークンとペルソナのペアを保存する
- PGS プロファイルのないユーザーが、プロファイルなしのリコールが有効になっているゲームを開きます。
- Games SDK が自動プラットフォーム認証をトリガーしますが、ユーザーに PGS プロファイルがないため、認証は失敗します。
- Games SDK は、ゲームが Google と統合されていることをユーザーに知らせるスナックバーを表示します。このスナックバーは操作可能で、ユーザーはプロフィールが作成されるまでリコールを無効にできます。
- ゲームがリコール アクセスをリクエストする。デバイスに PGS プロファイルがある場合や、デバイスに Google アカウントがない場合、PGS はリコール アクセス リクエストを拒否します。その場合、ゲームは PGS を使用せずに続行する必要があります。
- ユーザーがゲーム内アカウントでログインすると、ゲームはユーザーのゲーム内アカウントに対応するトークンとペルソナのペアを作成します。ゲームはこのペアを Google に保存します。ユーザーが他のゲーム内アカウントにログインした場合、ゲームは後でトークンをさらに保存する可能性があります。
新しいデバイスでゲームを起動する
- PGS プロファイルのないユーザーが、プロファイルなしのリコールが有効になっているゲームをデバイスで開きます。
- ゲームは、トークンとペルソナのペアを保存するで説明されているように、プロファイルなしの Recall トークンを記録します。
- ユーザーが、同じアカウント設定の別のデバイスで同じゲームを開きます。
- Games SDK がプロフィール作成をトリガーします。ユーザーは、以前に保存したリコール トークンを確認して拒否できます。ユーザーはこの時点で PGS プロファイルを作成します。
- PGS へのプラットフォームの自動認証が完了し、ゲームが認証ステータスを受け取ります。
- ゲームは通常どおりユーザーの Recall トークンを取得します。
次のステップ
Recall API をクライアントとゲームサーバーに統合するには、こちらのガイダンスに従ってください。