Epic Online Services (EOS) ではカタログ アイテムのアカウント所有権を検証する方法が複数あります。推奨されるのは、Ecom インターフェース を使って EOS SDK API を使用する方法です。このドキュメントは、RESTful エンドポイントを使用して所有権情報にアクセスすることを推奨しているタイトルやサービスのためのものです。EOS には、所有権検証を直接オンラインで実行するための RESTful サービス エンドポイントがあり、クライアントとサービスとの間で受け渡し可能な所有権トークンを作成して検証します。また、利用資格レコードを列挙して処理する利用資格サービスもあります。
所有権検証に使用する方法はユースケースによって異なります。オンライン方式は、エンドポイントと直接統合することで、ゲーム クライアントまたはゲーム サーバーから使用できます。所有権検証トークン方式では、ゲーム クライアント、ユーザー、利用資格およびシグネチャに関する情報を含むトークンが提供され、ゲーム クライアントまたはその他のサービスがそれを検証することができます。所有権検証を行うサードパーティ製のサービスを統合している場合は、所有権検証トークン チェックを使用して、ユーザーのデータにサービスがアクセスできないようにすることをお勧めします。
所有権チェックはツリー全体を探索して、指定した catalogItemId へのアクセス権をユーザーが持っているかどうかをチェックします。利用資格は特定の取引が発生しているかどうかを確認する際に役立ちます。たとえば、ユーザーがゲームのデラックス版を購入し、それに DLC1 にアクセス可能なシーズンパスが含まれている場合、所有権チェックは TRUE を返しますが、それに対し、利用資格チェックでは DLC1 は含まれません。
アクセス トークンを取得するためには、事前に認証サービスと統合を行う必要があります。認証の情報については、Epic アカウント サービスを開始する を参照してください。
ダイレクトな所有権の検証
ユーザーにアイテム、またはアイテム リストの所有権があるかどうかをチェックするエンドポイント。
このエンドポイントは、'https://api.epicgames.dev/epic/oauth/v1/.well-known/openid-configuration' を使って実装されたコンフィギュレーション SDK 1.5+ または OAuth OpenID Connect exchange を介して取得した認証トークンに適用します。
Bearer 承認を使用して Authorization ヘッダにアクセス トークンを渡す必要があります。
このエンドポイントは以下のクエリ パラメータをサポートします。
| パラメータ | 説明 |
|---|---|
nsCatalogItemId | {{sandboxId:catalogItemId}} の書式で、このパラメータを繰り返すことで、sandboxId と catalogItem の複数の組み合わせをチェックできます。 |
sandboxId | このパラメータを使用して、特定のサンドボックスで所有されている catalogItemIds の完全なリストを取得できます。 |
所有権情報を取得するリクエストの例を以下のスニペットに示します。
トークン ベースでの所有権の検証
所有権検証トークンは署名付きの JWT で、有効期限は 5 分間です。所有権検証トークンは、RS512 (SHA-512 を使用した RSA PKCS#1 シグネチャ、RSA キー サイズ 2048) を使用して署名されています。
トークン ベースでの所有権検証の実行には 2 つのステップがあります。
-
所有権検証トークンのリクエスト
-
公開キーを使用したトークンの検証
ゲーム クライアント/サーバーが所有権検証トークンを取得すると、所有権検証を行う必要のある任意の統合サービスにトークンを渡すことができます。トークンを検証する統合サービスは JWT をアンパックして kid (キー ID) を展開します。その後、そのキー ID の公開キーを取得してシグネチャを検証します。
トークンには以下の情報が含まれます。
| クレーム | 説明 |
|---|---|
| jti | このトークン固有の ID。 |
| sub | トークンのリクエストに使用されたアカウントのアカウント ID。 |
| clid | トークンのリクエストに使用されたクライアントのクライアント ID。 |
| ent | このトークンで確認された利用資格所有権の配列。この値が空の場合、そのアカウントはリクエストされた利用資格を持ちません。 |
| iat | トークンが発行された時刻を示す UNIX タイムスタンプ。 |
| exp | トークンの有効期限を示す UNIX タイムスタンプ。 |
所有権検証トークンをリクエストする
所有権検証トークンをリクエストするために、クライアントは HTTP POST リクエストを所有権トークン エンドポイントに対して発行します。
以下が所有権検証トークンをリクエストするエンドポイントです。
Bearer 承認を使用して Authorization ヘッダにアクセス トークンを渡す必要があります。
このエンドポイントでは、以下のリクエスト ボディがサポートされます。
注:Content-Type は「application/x-www-form-urlencoded」で、パラメータがリクエスト ボディに含められている必要があります。
| パラメータ | 説明 |
|---|---|
nsCatalogItemId | {{sandboxId:catalogItemId}} の書式で、このパラメータを繰り返すことで、sandboxId と catalogItem の複数の組み合わせをチェックできます。 |
検証トークンを取得するリクエストの例を以下のスニペットに示します。
egoc1~ は Epic Games Ownership Check を表すプレフィックスです。デコードの際には取り除いてください。
トークンには、base64 でエンコードされた 3 つの JSON オブジェクトがあり、それぞれ JWT のヘッダ、ペイロード、シグネチャに対応しています。詳細については、「JWT のドキュメント」を参照してください。
以下は JWT ヘッダの例です。
以下は JWT ボディの例です。
所有権検証トークンを検証する
トークンのシグネチャを検証するには、公開キーを取得する必要があります。キーを取得するには、キー ID (JWT 内の kid) が必要です。レスポンスには JSON Web Key (JWK) が含まれ、これを使用して JWT 内のシグネチャを検証できます。
公開キーをリクエストするために、クライアント/サーバーは HTTP リクエストを公開キー エンドポイントに対して発行します。
以下が公開キー エンドポイントです。
公開キーを取得するリクエストの例を以下のスニペットに示します。
ダイレクトな利用資格の列挙
アカウントのダイレクトな利用資格のリストが必要な場合にチェックするエンドポイント。
所有権のチェックのみが必要な場合は、Epic が推奨する上述の所有権チェック API を使用してください。
Bearer 承認を使用して Authorization ヘッダにアクセス トークンを渡す必要があります。
このエンドポイントは以下のクエリ パラメータをサポートします。
| パラメータ | 説明 |
|---|---|
sandboxId | ゲーム タイトルの名前空間。 |
entitlementName | オプションです。利用資格の名前。指定されていない場合は、sandboxId 以下の利用資格が返されます。このパラメータを繰り返すことで、複数の利用資格をチェックできます。 |
includeRedeemed | オプションです。 このパラメータは、引き換えられた利用資格を含めるかどうかを指定します。デフォルトは false です。true に設定されていない場合、結果には引き換えられてない 利用資格のみが含まれます。 |
ユーザーとサンドボックスの利用資格をすべて取得するリクエストの例を以下のスニペットに示します。
トークン ベースでの利用資格の検証
利用資格検証トークンは、RS512 (SHA-512 を使用した RSA PKCS#1 署名、RSA キー サイズ 2048) を使用して署名された JWT であり、作成後 5 分で有効期限が切れます。
トークン ベースでの所有権検証の実行には 2 つのステップがあります。
-
利用資格検証トークンのリクエスト
-
公開キーを使用したトークンの検証
ゲーム クライアント/サーバーが利用資格検証トークンを取得すると、所有権検証を行う必要のある任意の統合サービスにトークンを渡すことができます。トークンを検証する統合サービスは JWT をアンパックして kid (キー ID) を展開します。その後、そのキー ID の公開キーを取得してシグネチャを検証します。
トークンには以下の情報が含まれます。
| 利用資格検証トークン クレーム | |
|---|---|
| jti | このトークン固有の ID。 |
| sub | トークンのリクエストに使用されたアカウントのアカウント ID。 |
| clid | トークンのリクエストに使用されたクライアントのクライアント ID。 |
| ent | このトークンで確認された利用資格の配列。この値が空の場合、そのアカウントはリクエストされた利用資格または sandboxId の資格を持ちません。 |
| iat | トークンが発行された時刻を示す UNIX タイムスタンプ。 |
| exp | トークンの有効期限を示す UNIX タイムスタンプ。 |
利用資格検証トークンを要求する
利用資格検証トークンをリクエストするために、クライアントは HTTP POST リクエストを所有権トークン エンドポイントに対して発行します。
利用資格検証トークンをリクエストするエンドポイントは、https://api.epicgames.dev/epic/ecom/v1/platforms/{platform}/identities/{identityId}/entitlementToken です。
Bearer 承認を使用して Authorization ヘッダにアクセス トークンを渡す必要があります。
このエンドポイントでは、以下のリクエスト パラメータがサポートされます。
| リクエスト パラメータ | |
|---|---|
sandboxId | ゲーム タイトルの名前空間。 |
entitlementName | (オプション) 利用資格の名前。指定されていない場合は、sandboxId 以下の利用資格が返されます。このパラメータを繰り返すことで、複数の利用資格をチェックできます。 |
検証トークンを取得するリクエストの例を以下のスニペットに示します。
Note: egoc1~ is the prefix to represent Epic Games Ownership Check.デコードの際には取り除いてください。
トークンには、base64 でエンコードされた 3 つの JSON オブジェクトがあり、それぞれ JWT のヘッダ、ペイロード、シグネチャに対応しています。詳細については、JWT ドキュメントを参照してください。
以下は JWT ヘッダの例です。
以下は JWT ボディの例です。
利用資格検証トークンを検証する
トークンのシグネチャを検証するには、公開キーを取得する必要があります。キーを取得するには、キー ID (JWT 内の kid) が必要です。レスポンスには JWT 内のシグネチャを検証することができる JSON Web Key (JWK) が含まれます。
公開キーをリクエストするために、クライアント/サーバーは HTTP リクエストを公開キー エンドポイントに対して発行します。
公開キー エンドポイントは https://ecommerceintegration-public-service-ecomprod02.ol.epicgames.com/ecommerceintegration/api/public/publickeys/{kid} です。
公開キーを取得するリクエストの例を以下のスニペットに示します。
オファーをクエリする
ユーザーが利用可能なカタログ オファーのリストを要求するために、クライアントはオファー エンドポイントに HTTP GET リクエストを行います。
Epic Online Services で定義されたカタログ オファーのリストを要求するエンドポイントは以下の通りです。
本 API は、SDK API EOS_Ecom_QueryOffers と同じデータを提供します。SDK API の使用方法については、「EOS API リファレンス ドキュメント」を参照してください。
YBearer 承認を使用して Authorization ヘッダにアクセス トークンを渡す必要があります。
ユーザーとサンドボックスのオファーを要求するためのリクエストの例を以下のスニペットに示します。
The following is a sample response from the server for a virtual currency offer:
priceInfo 構造体の通貨値の読み込み方法は decimals フィールドの値に依存します。もし decimals の値が 2 (USD、CAD、Euro など) であれば、 discountPrice と originalPrice フィールドの値はセントになります。したがって、値をドル単位に変換するには、金額を 100 で割ります (例: 350 は 3.50 USD に相当します)。
もし decimals フィールドの値が 0 (JPY、KRW など) であれば、他のフィールドの値は指定された通貨に対応したものとなります。変換は必要ありません。
利用資格の引き換え/使用
以下は利用資格の引き換え/使用のためのエンドポイントです。利用資格の引き換えが行われると、利用資格の状態は「非アクティブ」に変更されます。
Bearer 承認を使用して Authorization ヘッダにアクセス トークンを渡す必要があります。
このエンドポイントでは、以下のリクエスト ボディがサポートされます。
ユーザーとサンドボックスの複数の利用資格を取得するリクエストの例を以下のスニペットに示します。