Ecom インターフェース

購入と所有権の確認を処理するインターフェースです。

Epic Games Store Only

Ecom インターフェース は、Epic Online Services (EOS) を使用するデベロッパーが Epic Games ストア (EGS) 経由でインゲーム購入をサポートできるようにします。このインターフェースによって、ゲーム全体、ゲームのダウンロード コンテンツ (DLC)、バーチャル商品やインゲーム通貨などの製品の管理が可能になります。オファーの提供、購入処理の完了、所有権の確認、購入アイテムとの引き換えなどが含まれます。

Ecom インターフェースで Web API を使用する方法については、「Web API による所有者の確認」を参照してください。

Ecom インターフェースにアクセスするには、Platform インターフェース の関数である EOS_Platform_GetEcomInterface を通じて EOS_HEcom ハンドルを取得する必要があります。すべての Ecom インターフェースの関数は、最初のパラメータとしてこのハンドルが必要です。リクエストが完了したときにコールバックがトリガーされるようにするには、EOS_HPlatform ハンドルがティックしていることを確認する必要があります。

Ecom インターフェースを使用するには、Epic Account Services (EAS) をアクティブにし、ユーザー同意 を取得して Basic Profile にアクセスする必要があります。EAS は Developer Portal 上で有効にすることができます。詳細は「Epic のドキュメント」を参照してください。EAS およびユーザー同意がなくても、EOS SDK および Ecom インターフェースの初期化を行うことができますが、バックエンド サービスへのすべての Ecom インターフェース機能呼び出しは失敗します。

インゲーム ストアを操作する

EOS のインゲーム ストアは 2 つの関数を実行して操作します。ストアからの Catalog Offers (「Offers」とも呼ばれます) を購入に向けてユーザーに提示し、ユーザーが購入できるようにします。EOS SDK は、ゲーム デベロッパーが望む方法でストア カタログから表示するオファーの一覧を取得するための機能を提供します。オファー データには、オファーに関する情報をユーザーに紹介するために使用する主要な画像とリリースの詳細など、ユーザーが取得する 1 つ以上のアイテムが含まれます。

ユーザーが購入を決めると、チェックアウト プロセスがデータを EGS Overlay へプッシュし、購入プロセスを最終決定します。その後 EOS は、ゲームが正常に完了したというイベントにおいてフルフィルメントを実行できるようにトランザクション ハンドルを提供して、トランザクションの結果をゲームに通知します。

EOS_PF_DISABLE_OVERLAY flag が設定されている場合、Ecom インターフェースの購入関連機能は無効になります。

カタログ オファー データ

Catalog Offers (型 EOS_Ecom_CatalogOffer) には、ストアをブラウズするユーザーに基づいて、ローカライズされた価格情報と説明するテキストが含まれます。ています。価格のローカリゼーションには割引の適用と現地通貨への変換が含まれます。現地価格には "USD" (US ドルを表す) などの通貨コードが含まれ、その通貨における最小単位が表示されます。たとえば、2.99 US ドルのオファーは値 299 が相当します。

ストア カタログを提示する

EOS_Ecom_QueryOffers 関数を呼び出すことで、Developer Portal で定義されたカタログ オファーのリストを取得することができます。この関数は EOS_Ecom_QueryOffersOptions データ構造体を受け取り、完了時にデリゲート EOS_Ecom_QueryOffersCallbackInfo を呼び出します。EOS_Ecom_QueryOffersOptions 構造体を以下のように初期化します。

プロパティ

ApiVersion

EOS_ECOM_QUERYOFFERS_API_LATEST

LocalUserId

クエリをリクエストするローカル ユーザーの EOS_EpicAccountId

OverrideCatalogNamespace

初期化において指定した以外の場合は、オプションの製品名前空間

デリゲートを受け取る EOS_Ecom_QueryOffersCallbackInfoResultCode が正常を表示したら、リクエストしたオファー データはテンポラリ キャッシュで使用できます。EOS_Ecom_GetOfferCount を使ってキャッシュ内に格納されたオファーの数を決定し、EOS_Ecom_CopyOfferByIndex を使ってそこから個々のオファー (型 EOS_Ecom_CatalogOffer) のコピーを取得します。オファー内の各アイテムには、そのアイテムと紐づいている画像とリリース詳細に関するデータが含まれます。これは別々に取り出すことができます。オファーのコピーの必要がなくなった場合は、EOS_Ecom_CatalogOffer_Release を使って解放します。

個々のアイテム データを表示する

キャッシュからオファーを取得したら、そのオファーに含まれるアイテム数を決定するために EOS_Ecom_GetOfferItemCount を呼び出して、 EOS_Ecom_CopyOfferItemByIndex を使って個々の EOS_Ecom_CatalogItem のコピーを取得します。この構造体には、購入時に提供する Entitlement (利用資格) の ID に加えてローカライズされたテキストが含まれます。データのコピーにアロケートされたメモリを解放するためには、EOS_Ecom_CatalogItem_Release を呼び出します。

アイテムに関連づいている画像もキャッシュで使用できます。EOS_Ecom_GetItemImageInfoCount を呼び出して任意のアイテムと紐づいている画像の数を決定し、EOS_Ecom_CopyItemImageInfoByIndex を使って画像の URL、ディメンション、用途の EOS_Ecom_KeyImageInfo を取得することができます。このデータのコピーが不要になったら EOS_Ecom_KeyImageInfo_Release を呼び出して使用しているメモリを解放します。

キャッシュからアイテムに対するリリース詳細を取得するために、まず EOS_Ecom_GetItemReleaseCount を使って存在するデータ エントリ数を調べます。その後で EOS_Ecom_CopyItemReleaseByIndex を使ってデータ (型 EOS_Ecom_CatalogRelease) の個々の構成要素を取得します。必要がなくなった場合は、EOS_Ecom_CatalogRelease_Release を呼び出してこのデータを解放します。

ストアから購入する

ユーザーがストアから何かを購入する場合、ユーザーはカタログ オファーを受け取ります。購入が完了すると、ユーザーはオファー内に含まれるアイテム (複数) を所有します。各アイテムが購入者のユーザー アカウントに 1 つ以上の Entitlements (利用資格) を追加します。

ストアからの購入には、3 つのアクションが含まれます。購入する、所有権を確認する、利用資格を引き換える (オプション) です。

ユーザーが購入を行うと、EOS_Ecom_CheckoutOptions 構造体で EOS_Ecom_Checkout を呼び出します。構造体を次のように初期化します。

プロパティ

ApiVersion

EOS_ECOM_CHECKOUT_API_LATEST

LocalUserId

購入するローカル ユーザーの EOS_EpicAccountId

OverrideCatalogNamespace

指定されない場合、現在の SandboxId がカタログ名前空間として提供されます。

EntryCount

Entries パラメータのこの構造体へ提供される EOS_EcomCheckoutEntry 要素の数。

Entries

EOS_Ecom_CheckoutEntry 要素の配列。ユーザーが購入を望む各オファーに対する EOS_Ecom_CatalogOfferId データと構造体と同じ ApiVersion を含みます。

この呼び出しを行うと、EOS はこの情報を使って購入トークンを生成します。EOS はこの購入トークンを使って独自のオーバーレイを開き、ユーザーが購入を確認し、支払いオプションを選択し、トランザクションを確定またはキャンセルできるようにします。オーバーレイが閉じると、成功、失敗、ユーザーによるキャンセルの場合に関係なく、コールバック (型 EOS_Ecom_OnCheckoutCallback) が EOS_Ecom_CheckoutCallbackInfo パラメータで実行しトランザクションを列挙します。このコールバック情報では、トランザクションが成功すると TransactionId は non-null となり、失敗またはキャンセルだと null になります。

コールバック経由で最初の戻りが来る前に EOS_Ecom_Checkout に対して追加の呼び出しがされると、EOS_AlreadyPending エラーとなります。

完了した購入データへアクセスする

正常なユーザー購入に続いて有効なトランザクション ID がある場合、EOS_Ecom_CopyTransactionById 関数に渡して EOS_Ecom_HTransaction を取得することができます。EOS_Ecom_Transaction_GetEntitlementsCount はトランザクションに関連する利用資格の番号を返し、EOS_Ecom_Transaction_CopyEntitlementByIndex は個々の利用資格を取得します。必要がなくなった場合は、EOS_Ecom_Entitlement_Release を呼び出してこのデータを解放します。

トランザクション ID に関連する利用資格には、EOS_Ecom_QueryEntitlement 関数によって取得できるものと同じデータが含まれていますが、キャッシュ ポリシーによって異なります。この差のために、購入後にトランザクション ID を使って取得する利用資格は、明示的に EOS_Ecom_Transaction_Release を呼び出すまでトランザクション固有キャッシュ内に留まります。

購入のフルフィルメント

購入するとユーザーのアカウントは利用資格を取得しますが、ユーザーはゲーム内で自分の購入の影響は見えないかもしれません。中には、購入の履行がユーザーが特定の利用資格を所有しているか確認してゲームロジックを結果に適用するのを同じほどシンプルなケースもあります。このようなケースでは、EOS SDK で所有権を確認するだけで十分です。消耗アイテムやゲーム通貨別のケースに関連する購入などのケースでは、インゲームで、または利用資格を引き換えることでサードパーティ バックエンド サービスを使って、注文を履行する必要があります。

利用資格を列挙する

ユーザー アカウントの利用資格を取得するには、以下のように初期化された EOS_Ecom_QueryEntitlementsOptions 構造体で`EOS_Ecom_QueryEntitlements` 関数を呼び出します。

プロパティ

ApiVersion

EOS_ECOM_QUERYENTITLEMENTS_API_LATEST

LocalUserId

利用資格を取得したいローカル ユーザーの EOS_EpicAccountId

EntitlementNames

確認したい Entitlement Name の配列

EntitlementNameCount

EntitlementNames プロパティに含まれる Entitlement Names の数。EOS_ECOM_QUERYENTITLEMENTS_MAX_ENTITLEMENT_IDS の最大数まで可能。0 を指定した場合は、ユーザー アカウントに関連づいたすべての利用資格をリクエストします。

bIncludeRedeemed

true の場合、引き換えられた利用資格は結果の中に含まれます。

操作の完了後に EOS は EOS_Ecom_QueryEntitlementsCallbackInfo パラメータを使って結果情報をキャッシュし、コールバック関数 (型 EOS_Ecom_OnQueryEntitlementsCallback) を実行します。このパラメータの ResultCodeEOS_Success の場合、キャッシュにはリクエストしたデータが含まれます。EOS_Ecom_GetEntitlementsCount を呼び出してキャッシュの利用資格数を決定し、 EOS_Ecom_CopyEntitlementByIndex を呼び出して、利用資格を提供するカタログ アイテム ID、その利用資格に一意のID、その他の関連データなど、個々の要素 (型 EOS_Ecom_Entitlement) のコピーを取得します。

利用資格を引き換える

利用資格を履行、またはサードパーティ サービスによるフルフィルメントの管理の後、EOS_Ecom_RedeemEntitlementsOptions 構造体を使って EOS_Ecom_RedeemEntitlements 関数を呼び出します。構造体を次のように初期化します。

プロパティ

ApiVersion

EOS_ECOM_REDEEMENTITLEMENTS_API_LATEST

LocalUserId

利用資格を引き換えるユーザー アカウントの ID

EntitlementIdCount

EntitlementIds 内の要素の数

EntitlementIds

引き換えるための利用資格 (型 EOS_Ecom_EntitlementId)

完了すると、コールバック型 EOS_Ecom_OnRedeemEntitlementsCallbackEOS_Ecom_RedeemEntitlementsCallbackInfo 構造体を受け取ります。

利用資格を引き換えた後、EOS_Ecom_QueryEntitlementsOptions パラメータの bIncludeRedeemedtrue に設定されていない限り、EOS_Ecom_QueryEntitlements の呼び出しの結果に表示されなくなります。

所有権を確認する

Ecom インターフェースでは、所有権の確認のために「オンライン」手法と「オフライン」手法の 2 つの手法を用意しています。オンライン手法では EpicEntitlement Service と直接統合されますが、オフライン手法では、ユーザーが確認できる、またはサードパーティのサービスに渡すことができる署名付きトークンを提供します。オンライン手法は、信頼されているゲーム サーバーでの利用や、照合が単純なクライアント システムで安全性の低いチェックを行う場合に便利です。オフライン手法は、ゲーム クライアント、ユーザー、利用資格 に関する情報と、ゲーム クライアントや外部サービスで確認可能な署名を含んだトークンを提供します。所有権確認を行うサードパーティー サービスと統合する場合、外部サービスにユーザーのデータへのアクセス権を付与することを避けるために、オフライン チェックを推奨します。

タイトルおよびサービスのオーナーシップ情報に RESTful エンドポイント経由でアクセスするには「Ecom Web APIs」を参照してください。

オンラインでの所有権検証

ユーザーが特定のカタログ アイテムを所有しているかどうかを判断するには、EOS_Ecom_QueryOwnership を呼び出して EOS_Ecom_QueryOwnershipOptions 構造体を渡します。これで、サーバーから所有権情報が取得され、指定した EOS_Ecom_OnQueryOwnershipCallback コールバック関数に渡されます。コールバック関数は、指定した void ポインタも取得します。これには、リクエストのコンテキストを把握するために製品が必要とする情報が含まれる場合があります。まず、EOS_Ecom_QueryOwnershipOptions 構造体に次の情報を入力します。

プロパティ

ApiVersion

EOS_ECOM_QUERYOWNERSHIP_API_LATEST

LocalUserId

所有権をクエリするローカル ユーザーの EOS_EpicAccountIdCatalog Item (Item) 説明テキストと価格情報のローカライズに必要。

CatalogItemIds

所有者を確認するための Catalog Item ID

CatalogItemIdCount

CatalogItemIds に含まれる要素の数

CatalogNamespace

初期化中に指定したものでない場合、オプションの製品名前空間

完了したら、EOS によって、リクエストされた (そして void ポインタが) EOS_Ecom_OnQueryOwnershipCallback 構造体に格納されたデータを使用してコールバック関数が呼び出されます。この構造体には EOS_Ecom_ItemOwnership メンバの配列が含まれています。各メンバーは、クエリしたクエリしたアイテムの 1 つを記述しており、そのアイテムをユーザーが所有しているかどうかを示しています。サーバーが認識しない項目は所有されないものとして返されます。

オフラインでの所有者検証

所有権をチェックして、結果をローカルに数分間キャッシュするには、EOS_Ecom_QueryOwnershipToken を使用します。この関数は、次のように初期化した EOS_Ecom_QueryOwnershipTokenOptions 構造体を受け取ります。

プロパティ

ApiVersion

EOS_ECOM_QUERYOWNERSHIPTOKEN_API_LATEST

LocalUserId

利用資格をクエリする対象のユーザーの FUniqueNetId

CatalogItemIds

利用資格をチェックする対象の最大 32 (EOS_ECOM_QUERYOWNERSHIPTOKEN_MAX_CATALOGITEM_IDS) 個のカタログ アイテムを含んだ配列。EOS_Ecom_CatalogItemId 型。

CatalogItemIdCount

CatalogItemIds に含まれるカタログ アイテムの個数。

CatalogNamespace

初期化中に指定したものでない場合、オプションの製品名前空間

操作が完了すると、コールバック関数 (EOS_Ecom_OnQueryOwnershipTokenCallback 型) が、有効期限が 5 分の JSON Web Token (JWT) を含む EOS_Ecom_QueryOwnershipTokenCallbackInfo 構造体を受け取ります。パブリック キーで JWT を照合し、Key ID を解凍するためにアンパックすることができます。サードパーティー サービスに送信することもできます。すると、サードパーティー サービスが EGS の利用資格情報を確認できます。追加の Web 呼び出しから取得するか、組織と共有した公開キーは、JWT の署名の確認に利用できる JSON Web Key (JWK) の形式をしています。HTTP リクエストをするには、GET を https://ecommerceintegration-public-service-ecomprod02.ol.epicgames.com/ecommerceintegration/api/public/publickeys/{kid} に送ります。以下はサンプル リクエストです。

GET
/ecommerceintegration/api/public/publickeys/pbvnNIE97vErdePGIRoG41h8hnP_2wIxG8xbwZCIj3g HTTP/1.1
Host: ecommerceintegration-public-service-ecomprod02.ol.epicgames.com
{
    "kty":"RSA",
    "e":"AQAB",
    "kid": "pbvnNIE97vErdePGIRoG41h8hnP_2wIxG8xbwZCIj3g",
"n": "gcStqtD8XD9c9ifNuxXT9Xd_EEZLLCw34yxINRQPt0MxEWkoOFsuisRWGktSFtGrnUuQnp8GQY0k4Pyl_yDItWAcRtO7JUjrhQnxx3xXp_0P8xJMH1ny-RcxHF3bEJWhDzNW5PBpBjQTQZis-83499z-4OlNA7oUnDKEJkqNfzh4mMDFluPxvW_Hwpaw71nhzJI7-N-BdsPsLdqUANajLsFKq9fr06Lek_tm-6-RUxNPE3yS0x0UIsGyapA4Apcczz0xTzRDfwOkq_TyKGZiZc7vtgjkWnqdsCyXZC7dzKJvg0ggO3mKXhqZNNC_2pz24o1X_xCbG8rXtuvX8-ux-Q"
}

所有権検証トークンの詳細

所有権検証トークンは、RS512 (SHA-512 を使用した RSA PKCS#1 署名、RSA キー サイズ 2048) を使用して署名された JWT であり、作成後 5 分で有効期限が切れます。トークンには以下の情報が含まれます。

クレーム

説明

jti

このトークンの一意の識別子

sub

トークンのリクエストに使用されたアカウントのアカウント ID

clid

トークンのリクエストに使用されたクライアントのクライアント ID

ent

このトークンで確認された利用資格の配列。この値が空の場合、そのアカウントは所定の sandboxId に関してリクエストされたいずれの利用資格も持ちません。

iat

トークンが発行された時間を示す Unix タイムスタンプ

exp

トークンの有効期限が切れる時間を示す Unix タイムスタンプ

OwnershipVerificationToken.png

Ecom インターフェース用語集

このセクションでは Ecom インターフェース内で一般的に使用される用語と定義を説明します。

用語

定義

Catalog Offers (カタログ オファー)

カタログ オファーは、1 つ以上のアイテムの組み合わせと関連価格です (0 の場合もあります)。カタログ オファーの購入後、ユーザーのアカウントは 1 つ以上の利用資格を受け取ります。

Catalog Item (カタログ アイテム)

アイテムには、ゲーム全体、ある種のダウンロード コンテンツの他、ゲーム内通貨や武器のスキンといったバーチャル商品などがあります。アイテムはどのように利用資格をアカウントに対して承認するかを定義するために使用されます。ローカルにグループ化された利用資格に対しても使用する利用資格名も含みます。

Entitlement (利用資格)

利用資格とは、ユーザーの所有物を指しますが、その内容は製品によって異なる場合があります。利用資格は動的です。 1 つ以上のアイテムへのアクセス権を付与しますが、実際は動的であり、製品の存続期間にわたってアイテムへのアクセス権の追加や削除をサポートしています。

Consumable Entitlement (消費する利用資格)

消費する利用資格は持続性が限られており、ゲーム内でアイテムを使用するたびに「使用回数」が減少します。これは、ゲーム内通貨、XP ブーストの他、消費して補充することのできるアイテムでよく使用されています。外部サービスが Entitlement を実行する場合もあります。その外部サービスが Entitlement に関する情報を受信すると、情報が引き換えられ、その使用カウントは 0 に減少し、ユーザー アカウントから効果的に削除されます。それを過ぎると、外部サービスはアイテムのゲーム内エフェクトを処理する責任を負います。

Durable Entitlement (永続的な利用資格)

所定の形式のダウンロード コンテンツやゲーム全体など、一部の購入品は永続します。サードパーティー サービスが必要とする場合、権限が委譲されたら利用資格を「非アクティブ」としてマークできます。

Fulfillment (フルフィルメント)

利用資格は、ユーザー アカウントの一部となった後、フルフィルメントを行う必要があります。これは暗黙的にして SDK API でチェックすることができます。または、サードパーティー サービスがバックエンド API 呼び出しを通じてフルフィルメントの責任を引き受けることができます。

以下の表は、ECom インターフェース内で使用されるさまざまな ID タイプと説明です。

ID タイプ

説明

Catalog Offer ID

ストアでのオファーに対する一意の識別子です。これらの ID は製品内で一意です。チェックアウト プロセスには Catalog Offer ID が必要です。

Catalog Item ID

製品内で一意であり、単一のカタログ アイテムを特性します。特定のユーザーが対応するカタログ アイテムを所有しているかどうかを確認するために必要な ID です。

Entitlement Name

各 Catalog Item は関連づいた Entitlement Name を持つことができます。グループ化に使用することができます。Ecom インターフェースは許可された Catalog Offer で Catalog Item と関連づけられた Entitlement Name を基づく利用資格をクエリすることができます。

Entitlement ID

そのユーザーで格納された特定の利用資格として、ユーザー アカウントで Catalog Offer とその Catalog Item マニフェストを履行します。各利用資格は独自の一意の識別子があります。この ID は利用資格の引き換え時に Ecom インターフェースによって使用されます。