Connect インターフェース

Connect インターフェースは、異なる ID プロバイダのユーザー アカウント間の接続を処理します。

Connect インターフェース は、提供されるすべてのサービスで、Epic Online Services (EOS) エコシステムの中核である、ユーザーの ID へのアクセスを提供します。ユーザーの ID は、Epic Games のサービス内で使用する際に、外部の ID プロバイダ のアカウントへリンクすることができます。プレーヤーは、1 つ以上のエターナルのユーザーアカウントを、同じ組織内のすべての製品にまたがる一意のプレーヤー ID に関連付けることができます。

Game Services Web API の使用については Connect Web API を参照してください。

ID プロバイダーの設定に関する詳細は、「ID プロバイダを管理する」を参照してください。

AuthVSConnect.png

アカウントを管理する

ユーザーは一連の外部認証情報を使用してログインします。該当製品にユーザーが既に存在する場合は、設定された期間 (現在、1 時間) 存続する アクセス トークン が付与されます。トークンの有効期限前になるとゲームに通知されます。この場合、ゲームはその時点で有効な外部認証情報が付与されている既存のトークンを更新しなければなりません。

Epic Games では外部プロバイダのアクセス権限を管理していません。そのため、このインターフェースの目的は、トークンを暗黙的に更新したり、その他長期間のアクセスを付与することではありません。ユーザーが外部アカウント プロバイダで引き続き有効であることを確認して、そのユーザーが当社のサービスにアクセスできる期間を延長することだけを行います。また、外部アカウント プロバイダにアプリケーションへのアクセスに対する権限があることが前提となります。

Connect Interface Account Flow

このアカウントで利用可能なサービスへのアクセスには、EOS_ProductUserId データ構造体を使用したアカウント識別が必要です。すべてのインターフェースで、この構造体の使用方法を明確に指定して、タイプ セーフであることを保証する必要があります。この構造体は、Epic Games アカウントに対して提供される認証インターフェースに関連付けられている EOS_EpicAccountId とは異なります。このサービスでは、Epic Games アカウントを使用することは必須ではありません。

ログインする

ログインするには、サポートされているプラットフォームの外部認証情報を含む EOS_Connect_LoginOptions を使用して EOS_Connect_Login を呼び出します。

Epic Games アカウントの場合、EOS_Auth_CopyUserAuthToken から現在の認証トークンを取得して、EOS_EExternalCredentialTypeEOS_ECT_EPIC に設定するだけです。

EOS_HConnect ハンドル、EOS_Connect_LoginOptions 構造体、およびコールバック情報を関数に渡します。EOS_HPlatform ハンドルがティックしている場合、操作が終了すると、指定したコールバックが実行されます。

結果が成功の場合、アプリケーションは認証を必要とするその他のインターフェースへのアクセスに進むことができます。ユーザーが存在しない場合、ログイン API は EOS_InvalidUser という結果を返します。これには EOS_ContinuanceToken も含まれています。ログイン試行の詳細が提供されているので、このトークンはログイン フローの次のステップで必要になります。

この時点で、次のことを特定する必要があります。サービスに登録済みであることが判明している他の外部認証情報セットがあるか (「外部アカウントを関連づける」を参照)、あるいは新しいアカウントを作成する必要があるか (「アカウントを作成する」を参照) をユーザーに確認します。

認証トークンの更新通知

EOS_Connect_AddNotifyAuthExpiration に指定されたコールバック関数は、既存のアクセス トークンの有効期限が近づくたびに実行されます。このコールバック関数の実行は、有効期限が近づくたびにアプリケーションが他の外部アクセス トークンを取得して、EOS_Connect_Login 関数を使用して SDK に取得したトークンを提供できるタイミングで行われる必要があります。 認証トークンの更新通知のリッスンを停止するには、EOS_Connect_RemoveNotifyAuthExpiration 関数を使用します。

ステータス変更通知

ユーザーの認証ステータスが変化されたら必ずアプリケーションに通知できるように、接続インターフェースでは、ステータス変更通知のコールバックを提供しています。

EOS_Connect_AddNotifyUserLoginStatusChanged に対して指定したコールバック関数は、ローカル ユーザーの認証ステータスが変更されるたびに実行されます。このコールバック関数の実行は、有効期限通知が無視された場合、外部プロバイダの認証情報がアクセス トークンを更新できない場合、または管理上の理由によりバックエンド サービスによってアクセスが明示的に取り消された場合にのみ行われます。このコールバックは、EOS エコシステムの他のコールがこの認証トークンを無効と検知した場合のみ実行されます。その他の場合、自動で実行はしません。

認証が原因で失敗する可能性のある特定のコールのすべてのメッセージを処理する必要があります。EOS_Connect_Login を呼び出して、元のコールを再試行し成功することで回復可能な場合が多いです。

ステータス変更通知のリッスンを停止するには、EOS_Connect_RemoveNotifyUserLoginStatusChanged 関数を使用します。

現在の認証ステータスを確認する

必要に応じて、プレイヤーの現在のステータスを確認するには、EOS_Connect_GetLoginStatus 関数を使用します。この関数はオンライン サービスとの前回の通信に基づいて認証ステータスを特定するのですぐに結果が返されます。そのため、コールバック関数は使用しません。

ユーザーを作成する

ユーザーを作成すると、ログイン時に使用した外部認証情報を提供したユーザーには、製品ユーザー ID が生成されます。ほとんどの場合、新しいユーザーを作成する前に、ユーザーにプロンプトを表示して、他にログインする手段があるかどうかを確認する必要があります。この確認を行うことで、クロスプラットフォーム環境での混乱とアカウント/ユーザーのマージに関する問題が軽減されます。

アプリケーションの目的がユーザーの新しい製品ユーザー ID の作成である場合は、単に、EOS_Connect_Login に対する前の呼び出しの EOS_ContinuanceToken を含む EOS_Connect_CreateUserOptions を使用して EOS_Connect_CreateUser を呼び出します。

EOS_HConnect ハンドル、EOS_Connect_CreateUserOptions 構造体、およびコールバック情報を関数に渡します。EOS_HPlatform ハンドルがティックしている場合、操作が終了すると、指定したコールバックが実行されます。

外部アカウントをリンクする

アプリケーションへのログインのフローで、ユーザーが他の外部認証情報セットでログインできると特定されている場合は、最初のログイン呼び出しの EOS_ContinuanceToken を格納して、EOS_Connect_Login を使用してログインを再試行し、ログインに成功したら、直ちに EOS_Connect_LinkAccount を呼び出します。この操作により、2 つの外部アカウントが 1 つの製品ユーザー ID に関連付けられます。Epic Games のサービスの機能は拡大しているため、3 つ以上のアカウントを関連づけることができます。

アプリケーションの目的が既存の製品ユーザー ID に新しい外部アカウントをリンクすることである場合は、単に、EOS_Connect_Login に対する前の呼び出しの EOS_ContinuanceToken を含む EOS_Connect_LinkAccountOptions および EOS_Connect_Login に対する成功した呼び出しでログインしたユーザーの製品ユーザー ID を使用して EOS_Connect_LinkAccount を呼び出します。

EOS_HConnect ハンドル、EOS_Connect_LinkAccountOptions 構造体、およびコールバック情報を関数に渡します。EOS_HPlatform ハンドルがティックしている場合、操作が終了すると、指定したコールバックが実行されます。

EOS Connect ユーザーは、外部アカウント ID で、または [Developer Portal (デベロッパー ポータル)] の [Account] ダッシュボードを介して製品ユーザー ID を使用することで、検索できます。プレイヤーのリンク済みの外部アカウントのキーチェーンは組織レベルで管理されるため、[Account] ダッシュボードは [Organization management (組織管理)] メニュー項目の隣にあります。[Account] ダッシュボードではプレイヤーを検索できるため、カスタマー サポートがプレイヤーのリクエストに応じてアカウント リンクを削除する際に役立ちます。このダッシュボードを使用すると、SDK 統合テスト時に EOS Connect ユーザーまたはリンク済みのアカウントを削除することもできます。これに合わせて、Epic Games では、既存の内部ダッシュボードに EOS のユーザー管理機能を組み込むための Web REST API をデベロッパーに提供する予定です。

外部アカウントのリンクを解除する

ログイン フローを初めて使用する場合、別のプラットフォームでプレイしたり、別の外部アカウントの資格情報を使用したりすることで、ユーザーが既に持っているゲームデータを使用せずに、ログインしたアカウント (通常はローカル プラットフォーム アカウント) に対して、新しい製品ユーザIDを誤って作成してしまう可能性があります。ユーザーはゲームのクロスプレイ機能を認識していない可能性があります。ユーザーはゲームのクロスプレイ機能を認識していない可能性があります。

このようなシナリオでは、ユーザーは初期のログイン ダイアログをスキップして、ユーザーのデフォルト プラットフォームのアカウント認証情報 (ログイン アカウント) で続行し、EOS_Connect_Login API と EOS_Connect_CreateUser API のフローに従って新しい EOS_ProductUserId を作成します。その結果、ゲームの開始時に EOS_Connect_Login で使用されたのログイン アカウントが意図しない製品ユーザー ID と結びつけられるようになります。この状態から回復するには、ユーザーが初めてユーザー ログイン フローに再度入れるように、ユーザーは新しく作成されたキーチェーンからログイン アカウントのリンクの解除ができなければなりません。

ログインアカウントのリンクを解除すると、別の既存のキーチェーンにリンクされた別の外部アカウント資格情報のセットを使用してログインすることができます。成功すると、上記の Linking an External Account セクションで説明されたフローを使って、デフォルトのログイン アカウントを目的の既存のキーチェーンにリンクします。

別の状況もあります。ユーザーは、プラットフォーム間でゲームの進行状況を分離したり、別の方法で別のキーチェーンにリンクしたりするために、ログインアカウントを現在のキーチェーンから分離したい場合があります。

現在ログインしている製品ユーザー ID を所有するキーチェーンから外部アカウントのリンクを解除するには、 EOS_Connect_UnlinkAccountOptions を指定して EOS_Connect_UnlinkAccount を呼び出し、 EOS_Connect_Login への以前の呼び出しで返された EOS_ProductUserId として LocalUserId を指定します。操作が正常に完了すると、外部アカウントはキーチェーンに関連付けられなくなります。つまり、同じ外部アカウントに関連付けられた認証情報を使用して EOS_Connect_Login`で次にログインしようとすると、 EOS_ContinuanceToken`で `EOS_InvalidUser`結果が返されることを意味します。

アカウントのリンク作成操作と同様に、リンク解除操作の履歴は、Developer Portal のアカウント ダッシュボードから監査することができます。

アカウントのリンク解除に関する制限事項

アカウントを盗難から保護するために、キーチェーンからアカウントのリンクを解除できるのは、ローカル ユーザーが現在ログインしているアカウントのみです。これにより、悪意のあるものがリンクされたアカウントの 1 つにアクセスし、それを使用してキーチェーンにリンクされた他のすべてのアカウントを削除することを防ぎます。また、リンク解除操作により、既存の認証セッションを使用して、キーチェーンの他のリンクされたアカウントのいずれかを使った認証なしにエントリを再リンクおよび上書きすることができないため、悪意ある人物がリンクされていないアカウントを同じプラットフォーム上の対応するアカウントに置き換えることも防止されます。

これらの制限事項は、アカウント盗難の状況に関連する潜在的な攻撃対象領域を制限するために設けられました。

デバイス ID を使用する

ユーザーが、新規アカウントを作成したり、既存のアカウントを関連づけるほどの段階ではないとアプリケーションが判断した場合、アプリケーションは EOS Connect の デバイス ID 機能を使用して新しい永続的な疑似アカウントを作成することができます。この機能を使用すると、アプリケーションでは、外部ログイン認証情報を使用しないで、ローカル ユーザーの永続的なアクセス認証情報を作成できます。これにより、バックエンド サービスでは複数のゲーム セッションを通じてそのローカル デバイスの現在のユーザーを記憶できます。デバイス ID 機能は特に個人用のモバイル デバイスで使用されます。この機能を使用すると、アカウント認証情報の入力を求められることなく、ユーザーが自動的にログインできたり、ゲームの進行状況データを保持するために直ちにログインを求められることなく、ゲーム プレイを開始したりできます。

ただし、デバイス ID は本物のユーザー アカウントに関連付いておらず、ローカル デバイスを一意に識別するためのみに使用できるため、初期の進行マイルストーンまで進んだら、認証情報やアカウントの喪失を防止できるように、外部認証方法をデバイス ID アカウントに関連づけるようユーザーに求めることを強く推奨します。

最終的にはデバイス ID アカウントを本物のユーザー ID にリンクしないと、デバイス自体に問題等が発生した場合、すべての進行状況とゲーム データが永久に失われます。EOS SDK では、ローカル デバイスの現在ログインしているユーザーのキーチェーンにデバイス ID の認証情報をローカルに格納します。ローカル ユーザーのプロファイルがリセットされたり、失われたりした場合、それ以降に失われたデバイス ID を回復することはできません。

新しいデバイス ID を作成するには、アプリケーションで、ユーザーの DeviceModel を含む有効な EOS_Connect_CreateDeviceIdOptions 構造体を指定して EOS_Connect_CreateDeviceId 関数を呼び出す必要があります。この呼び出しにより、最終的には EOS_Connect_OnCreateDeviceIdCallback にバインドされた関数へのコールバックがトリガーされます。新しいデバイス ID が正常に作成され、ローカル デバイスのログイン ユーザーのキーチェーンに格納された場合、コールバック パラメータの ResultCode パラメータが EOS_EResult::EOS_Success に設定されます。既存のデバイス ID が既に存在する場合は、EOS_EResult::EOS_DuplicateNotAllowed が返されます。その他の場合は、ResultCode パラメータで操作が失敗した理由が特定されます。

一意のデバイス ID を使用してローカル ユーザーをログインさせるには、EOS_EExternalCredentialType::EOS_ECT_DEVICEID_ACCESS_TOKEN 外部認証情報型を使用して EOS_Connect_Login API を呼び出します。SDK では格納されたデバイス ID 認証情報を自動的に管理するため、EOS_Connect_Credentials 入力構造体の Token パラメータを NULL に設定する必要があります。ただし、デバイス ID は本物のユーザー ID に関連付けられていないため、EOS_Connect_UserLoginInfo 入力構造体にユーザーの有効な DisplayName を指定する必要があります。

ローカルのデバイス ID を本物の外部ユーザー アカウントに関連づけるには、まず、ゲームで、通常デバイス ID タイプの認証情報を使用しているローカル ユーザーをログインさせます。次に、ユーザーに本物の ID でログインするように求め、EOS_Connect_LoginEOS_ContinuanceToken とともに返されたら、EOS_Connect_Link API を使用して外部アカウントをリンクして、ローカル デバイスをユーザーの実際のアカウントに関連付けます。この操作により、ゲームを開始するたびにユーザーが自動的にログインできるようになります。外部ユーザー アカウントの認証情報の入力を求められることなく、ユーザーが自動的にログインできるように、デバイス ID を引き続き使用できるためです。

EOS_Connect_DeleteDeviceId API を呼び出して、ローカル デバイスの現在のユーザー プロファイルのデバイス ID を削除することもできます。削除は永続的な操作であるため、元に戻すことはできません。ただし、新しいデバイス ID を作成して、既存の外部ユーザー アカウントにその ID を関連づけると、いつでも自動ログイン機能を復元することができます。

デバイス ID に基づくゲーム進捗を関連づけられた既存のアカウント キーチェーンに関連づける

デバイス ID 疑似アカウントを外部ユーザー アカウントへ関連づける一般的なパスが不可能となる特別なケースがあります。このシナリオでは、ログインされた本物のユーザー アカウントは同じ EOS 組織の下の既存のキーチェーンにすでに属しています。そのようなケースでは、ゲームがまずローカル Device ID ログイン タイプを使って自動的にユーザーをログインさせ、その後にユーザーが本物のユーザー アカウント認証情報を使ってログインすると、EOS_Connect_Login API は EOS_ContinuanceToken の代わりに既存の EOS_ProductUserId を返します。この特別なシナリオに対処するために、EOS_Connect_TransferDeviceIdAccount API が使用されます。

EOS_Connect_TransferDeviceIdAccount API は EOS_ContinuanceToken の使用が求められるため、デバイス ID 疑似アカウントを既存のキーチェーンに関連づけることができません。さらに、プレイヤーには異なる 2 つの EOS_ProductUserIds が存在することになるため、ゲームはプレイヤーに対して、一方の EOS_ProductUserIds (ゲーム プロファイルなど) を廃止として破棄し、もう一方の EOS_ProductUserIds でプレイを継続するかどうかを選択させる必要があります。プレイヤーが一方のプロファイルの破棄を選択した場合、ゲームはバックエンドで永続的である、関連付けられたアカウントの既存のキーチェーンにローカル デバイス ID を関連づけることができます。

2 つの EOS_ProductUserIds が存在するシナリオに対処するには、ゲームはいつ Device ID ログイン タイプを使ってローカル ユーザーログインさせ、その後ユーザーが同じゲーム セッションで既存のアカウントを使ってログインし、かつ それに対してもう 1 つの EOS_ProductUserId セッションを受け取るのかを認識する必要があります。これにより、ゲームは一方の EOS_ProductUserIds に有意義なゲームの進行状況をもたないことをバックエンドで自動的に確認しようとします。このケースでは、ゲームはそれを自動的に破棄し、ローカルのデバイス ID 疑似アカウントを本物の外部ユーザー アカウントの既存のキーチェーンに関連づけます。

ユーザーの代わりにゲームがこのケースを判断することができないと、ゲームはユーザーに処理の方法についての選択を促します。この選択ダイアログにおいて、プレイヤーはそれぞれの EOS_ProductUserId の比較することでゲームの進行状況を見直し、どちらを保持するか選択します。破棄されたゲームの進行状況は永久に失われ、破棄後の回復はできないことをユーザーに対して明確にすべきです。ゲームはユーザーにいずれのプロファイルも破棄せずに、いずれかを選択して現在のゲーム セッションでプレイを継続することを選択するオプションを提供する場合があります。

ユーザーがゲーム プロファイルの一方を破棄して、もう一方に永久に切り替えることを選択する場合、ゲームは ローカル デバイス ID 疑似アカウントを本物の外部ユーザー アカウントに関連づいたキーチェーンに転送するために EOS_Connect_TransferDeviceIdAccount API を呼び出します。API で、デバイス ID 転送オペレーションに保持するための正しい EOS_ProductUserId 値を指定するために、構造体 EOS_Connect_TransferDeviceIdAccountOptions を入力し ProductUserIdToPreserve パラメータを設定します。

外部アカウントのマッピングを取得する

他のインターフェースは、リモート ユーザーまたはその他の外部ユーザー (同一サーバー上のフレンド、プレイヤーなど) では EOS_ProductUserId を必要とします。マッピング API を使用して、外部ユーザー アカウント識別子を EOS_ProductUserId に変換することができます。

EOS_Connect_QueryExternalAccountMappings は、外部アカウント ID を SDK 表現に変換する非同期呼び出しです。EOS_EExternalAccountType を設定して、外部アカウント ID の隣接リストを文字列形式で提供します。

EOS_HConnect ハンドル、EOS_Connect_QueryExternalAccountMappingsOptions 構造体、およびコールバック情報を関数に渡します。EOS_HPlatform ハンドルがティックしている場合、操作が終了すると、指定したコールバックが実行されます。

コールバックが正常に返されたら、 EOS_Connect_GetExternalAccountMapping を使用してマッピングを取得できます。この関数は、EOS_Connect_QueryExternalAccountMappings と同様に EOS_EExternalAccountType を取り、文字列形式で外部アカウント ID を提供する呼び出しごとに 1 つの EOS_ProductUserId を返します。

製品ユーザー ID のマッピングを取得する

特定の製品ユーザー ID の外部マッピングを取得できるように、外部アカウントの製品ユーザー ID のマッピングも取得できます。 EOS_Connect_QueryProductUserIdMappings は非同期呼び出しで、表示名、最終ログイン時刻を含む追加のアカウント データとともに、特定のプラットフォーム上の外部の該当要素に EOS_ProductUserIds を変換します。製品ユーザー ID の隣接リストの指定のみを行います。

EOS_HConnect ハンドル、EOS_Connect_QueryProductUserIdMappingsOptions 構造体、およびコールバック情報を関数に渡します。EOS_HPlatform ハンドルがティックしている場合、操作が終了すると、指定したコールバックが実行されます。

コールバックが正常に返されたら、 EOS_Connect_GetProductUserIdMapping を使用してマッピングを取得できます。この関数は、EOS_EExternalAccountType と、外部アカウント ID を入力するための入力バッファおよびバッファ長を取ります。バッファが小さすぎる場合、バッファの適切なサイズが返されます。

EOS_Connect_GetProductUserExternalAccountCount を使用すると、製品ユーザーにリンクされている外部アカウントの数を取得します。

EOS_Connect_CopyProductUserExternalAccountByIndex を使用すると、インデックスを使用して製品ユーザーにリンクされた外部アカウントに関する情報を取得します。

EOS_Connect_CopyProductUserExternalAccountByAccountType を使用すると、製品ユーザーにリンクされた特定のタイプの外部アカウントに関する情報を取得します。

EOS_Connect_CopyProductUserExternalAccountByAccountId を使用すると、アカウント ID を使用して製品ユーザーにリンクされた外部アカウントに関する情報を取得します。

EOS_Connect_CopyProductUserInfo を使用すると、前回ログインした外部アカウントを参照として使用して、製品ユーザーに関する情報を取得します。

製品ユーザー ID が特定の外部プラットフォームにマップされていない場合は、上記に対して返された結果にデータは含まれません。つまり、ユーザーがそのタイプの外部アカウントを製品ユーザー ID に関連付けたことがないことを意味します。