クイック スタート ガイド

e コマース機能、重要な用語および e コマース API の一般的なユースケースに関するサポート ガイドです。

10 分で読めます

e コマースの概要

Epic Games Store は e コマース機能の拡張セットを提供し、これを使用すると、ダウンロード可能なコンテンツ (DLC) または仮想通貨など、ゲームに関連する購入可能なアイテムまたは引き換え可能なアイテムを管理することができます。製品内でバンドルを最適化できるように、システムは階層として設定されています。以下の情報はこのシステムを展開したものです。重要な用語の概要を示し、ゲーム内およびバックエンド機能をサポートする e コマース API の使用方法の一般的なユースケースを提供しています。

e コマース API のガイダンスについては、「API リファレンス」を参照してください。

e コマース コンフィギュレーションおよび用語の例

Epic Games Store の e コマース機能を説明するため、以下のコンフィギュレーション例を見てみましょう。

図 1：製品の e コマース コンフィギュレーションの例

この例では、製品 (My Game) が 3 つの サンドボックス (開発、ステージ、ライブ) で設定されています。これらのサンドボックスには、それぞれ独自の e コマース コンフィギュレーションがあり、次の項目のうち 1 つ以上の項目から構成されています。

  • カタログ オファー：カタログ オファー (オファーとも呼ばれる) は、カタログ アイテムと関連価格 (0 の場合もある) の組み合わせです。ユーザーは Epic Games Store でオファーを購入できます。ユーザーがオファーを購入すると、バックエンド サービスによって、オファー内に含まれる各アイテムに対してユーザーに 利用資格 が付与されます。

    • 注記: 利用資格とは、Epic Games ストア インフラストラクチャ内でユーザーが所有するものです。利用資格によって、1 つ以上のカタログ アイテムにアクセスできるようになります。

  • カタログ アイテム:カタログ アイテム (オーディエンス とも呼ばれる) は、ゲーム全体、インゲーム通貨、武器のスキンといったバーチャル商品や、その他のタイプのダウンロード可能なコンテンツを表します。サービスでは、カタログ アイテムを使用して利用資格をユーザーに対して付与する方法を定義します。利用資格は 1 つのカタログ アイテムに直接関連付けられ、所有権を追加のカタログ アイテムに付与することができます。

    • ヒント: カタログ アイテムは、Epic Games Store の動的バンドル機能で他のカタログ アイテムを付与するように設定できます。この機能を使用して、関連するオファーを時間の経過とともに更新することができます。たとえば、新しい DLC のリリース時にシーズン パスの所有者がシームレスに所有権を取得できるようにすることができます。

  • ライブラリ アイテム:ライブラリ アイテム (ゲーム アイテムとも呼ばれる) は一種のカタログ アイテムで、Epic Games ストア インフラストラクチャではこれを使用して、アーティファクト ID またはクラウド セーブ コンフィギュレーションなど、このカタログ アイテムの追加のプロパティを設定します。ライブラリ アイテムは、常にカタログ アイテムにリンクしています。

    • 注記 アーティファクトとは、ゲームクライアントや DLC など、ダウンロード可能でプレイ可能なゲームのコンテンツを表します。アーティファクトはライブラリ アイテムにリンクしています。バイナリをアーティファクトにリンクするものを設定し、これにより、Epic Games Launcher がダウンロードおよびインストールするコンテンツを決定できます。バイナリは、BuildPatch ツール BuildPatch ツール を使用してアップロードできます。

カタログ オファーおよびカタログ アイテムは Epic Online Services SDK Ecom インターフェースまたは (Web API) で公開されています。これを使用すると、製品に設定されているすべてのカタログ オファーとカタログ アイテムをクエリしたり、カタログ オファーのインゲームのチェックアウト フローを表示したり、カタログ アイテムや利用資格の所有権情報をクエリしたりすることができます。

コンフィギュレーション例では、ライブ サンドボックスの製品に次の 4 つのオファーを使用して設定しています。

  • ベース ゲーム オファー:ゲームのベース エディションに対するカタログ オファーです。ベース ゲーム オファーは永続的な購入で、プレイヤーは購入後、永続的にこれを所有します。このオファーは、子ライブラリ アイテムが含まれる 1 つのカタログ アイテムから構成されます。

    • ベース ゲーム アイテム:ゲームのベース エディションに対するカタログ アイテムです。このカタログ アイテムは、以下 のユースケースの説明に従ってベース ゲームの所有権を検証するために使用します。
    • ベース ゲーム ライブラリ アイテム:ベース ゲーム アーティファクト、クラウド セーブ ゲーム コンフィギュレーションまたは他のプロパティの設定に使用されるカタログ アイテムです。

  • デラックス ゲーム オファー:ゲームのデラックス エディションに対するカタログ オファーです。このオファーは永続購入であり、次のカタログ アイテムから構成されます。

    • デラックス ゲーム アイテム:このエディションの所有権を検証するために使用可能なゲームのデラックス エディション用のカタログ アイテムです。デラックス ゲーム アイテムはそのライブラリ アイテムにリンクしていません。代わりに前述のベース ゲーム アイテムおよび後述する DLC アイテムにリンクしています。

  • DLC オファー:ゲームの DLC 用カタログ オファーであり、このオファーは永続購入です。

    • DLC アイテム:ゲームの DLC 用カタログ アイテムです。このカタログ アイテムは、DLC の所有権を検証するために使用します。
    • DLC ライブラリ アイテム:DLC アーティファクトまたは他のプロパティの設定に使用されるカタログ アイテムです。

  • 100 コイン オファー:インゲーム通貨の 100 コインのカタログ オファーです。このオファーは消耗品の購入で、プレイヤーは何度もこれを購入でき、消耗品のためにインゲームで履行できます。

    • 100 コイン アイテム:100 コイン オファー用カタログ アイテムです。このカタログ アイテムは、オファーに関する追加情報を取得するために使用します。ただし、オファーは消耗品の購入であるため、所有権を検証するために使用しません。

注記： 消耗品を別のオファーの購入で付与することはできません。つまり、デラックス ゲーム オファーで、購入の一部としてプレイヤーに 100 コインを付与する場合、100 コイン オファーがデラックス ゲーム内の [Included offers (含まれているオファー)] セクションに表示されないため、プレイヤーにコインを与えるインゲーム ロジックを組み込む必要があります。

e コマース API のユースケース

以下のセクションで、e コマース API を使用してインゲーム機能またはバックエンド機能をサポートする方法の一般的なユースケースの概要を説明します。

ゲームでカタログ オファーを表示して購入を有効にする

ユーザーが購入するカタログ オファーをインゲームで表示するには、次のフローを Epic Online Services SDK と組み合わせて使用します。

  1. 「Auth インターフェース」のドキュメントで説明されているように、EOS_Auth_Login を使用してユーザーを認証します。通常、これは、こちら で説明されているように、Epic Games Launcher で提供される ExchangeCode を使用して行われます。
  2. 「Ecom インターフェース」のドキュメントで説明されているように、EOS_Ecom_QueryOffers の API を使用して、使用可能なカタログ オファーのリストを取得します。説明されているパターンに従って、オファー数を決定し、SDK キャッシュから自分のコレクションにオファーをコピーします。
    • 前述のコンフィギュレーション例では、次のオファーのリストを取得します。
      • ベース ゲーム オファー
      • デラックス ゲーム オファー
      • DLC オファー
      • 100 コイン オファー
  3. EOS_Ecom_CatalogOffer コレクションを使用して、ローカライズされたタイトルと説明、価格、割引情報など、オファーの詳細を取得します。オファー情報には、オファーが購入できるかどうか、および現在のユーザーがすでに購入しているかどうかも示されます。

これで、この情報を使用してインゲームでオファーを表示し、使用可能なオファーを購入するためのボタンをユーザーに提示できるようになります (EOS_Ecom_CatalogOffer の bIsAvailableForPurchases プロパティで決まります)。このフローを使用するには、Epic Online Services ソーシャル オーバーレイ を使用するようにゲームを設定する必要があります。

  1. 「Ecom インターフェース」のドキュメントで説明されているように、EOS_Ecom_Checkout API を使用して、ユーザーが購入するオファーごとにカタログ オファー ID を渡します。
  2. 「Ecom インターフェース」のドキュメントで説明されているように、EOS_Ecom_CheckoutCallbackInfo で返される TransactionId を使用して、トランザクションが成功したかどうかを決定します。

EOS_Ecom_Checkout API を使用したトランザクションは、永続購入または消耗品の購入です。詳細については、必要に応じて次のシナリオを参照して購入を確認してください。

独自のバックエンド サービスを使用して購入を安全に検証する

プレイヤーの購入を確認するには、ユーザーによる悪意のある行為の影響を受けない、独自のバックエンド サービスの使用をお勧めします。ユーザーから悪意のある動作の影響を受けないように、独自のバックエンド サービスからプレイヤーの購入を検証することをお勧めします。この検証を実装するカスタム バックエンド サービスがない場合、クライアント側の検証の詳細については、「購入した永続コンテンツを検証する」および「消耗品の購入を検証および履行する」のユースケースを参照してください。

バックエンド サービスを通じて検証を実行するには、Ecom Web API を利用した次の方法のいずれかを使用します。

ダイレクトな検証

ダイレクトな検証とは、直接アクセス トークンを使用して、バックエンド サービスから Ecom Web API を呼び出すことです。

  1. 「Auth Web API」のドキュメントの手順に従い、Ecom Web API とともに使用するアクセス トークンをリクエストします。
  2. 永続購入を検証するには、Ecom Web API の API を使用します。消耗品の購入を検証および引き換えを行うには、利用資格の列挙 および 引き換え の API を使用します。

トークンベースの検証

トークンベースの検証とは、バックエンド サービスに渡される、ゲームクライアントによって生成された JSON Web トークン (JWT) の信頼性を検証することです。この方法を使用すると、バックエンド サービスは、ゲームクライアントで生成された複数のトークンを検証するのに、公開キーを一度だけ (またはキーが無効化されるまで) 取得するだけで済みます。

  • 永続コンテンツの場合 (DLC など)：「Ecom インターフェース」のドキュメントの手順に従って、EOS_Ecom_QueryOwnershipToken API を使用してゲームクライアント コードで JWT を生成します。この JWT には複数のカタログ アイテムの所有権情報を含めることができます。
  • 消耗コンテンツの場合 (インゲーム通貨など)：「[Ecom インターフェース](/epic-games-store/services/ecom/ecom-overview#トークン ベースの利用資格の列挙)」のドキュメントの手順に従って、EOS_Ecom_QueryEntitlementToken API を使用してゲームクライアント コードで JWT を生成します。この JWT には複数のカタログ アイテムの所有権情報を含めることができます。

JWT を前述の手順に従って生成した後、JWT をバックエンド サービスに送信します。その後、トークンをデコードし、「Ecom Web API」のドキュメントに従ってトークンが正当なものであることを検証します。

購入した永続コンテンツを検証する (DLC など)

プレイヤーの購入を確認するには、ユーザーによる悪意のある行為の影響を受けない、独自のバックエンド サービスの使用をお勧めします。詳細については、「独自のバックエンド サービスを使用して購入を安全に検証する」のユースケースを参照してください。

ゲームクライアント内で永続コンテンツを検証するには、EOS_Ecom_QueryOwnership の API を使用します。この API は、カタログ アイテム ID のコレクションを渡すことで、所有権を検証します。この所有権の検証では、カタログ アイテム間の関係が自動的に考慮されます。

コンフィギュレーション例では、ユーザーはデラックス ゲーム オファーまたはベース ゲーム オファーを購入でき、各オファーがベース ゲーム アイテムに関連付けられているため、両方がベース ゲーム アイテムの検証に成功します。同様に、デラックス ゲーム オファーを購入すると、そのカタログ アイテムがデラックス ゲーム オファーにも関係しているため、DLC アイテムの検証が成功します。

次のフローは、EOS_Ecom_QueryOwnership の API を使用して永続コンテンツを検証する際に使用します。

  1. 「Auth インターフェース」のドキュメントで説明されているように、EOS_Auth_Login を使用してユーザーを認証します。通常、これは、こちら で説明されているように、Epic Games Launcher で提供される ExchangeCode を使用して行われます。

  2. 「Ecom インターフェース」のドキュメントで説明されているように、EOS_Ecom_QueryOffers の API を使用して、使用可能なカタログ オファーのリストを取得します。説明されているパターンに従って、オファー数を決定し、SDK キャッシュから自分のコレクションにオファーをコピーします。

  3. 「Ecom インターフェース」のドキュメントの手順に従い、オファーのコレクションを反復処理して、関連付けられているカタログ アイテム (EOS_Ecom_CatalogItem) を検索します。

    • コンフィギュレーション例では、各カタログ オファーに含まれているカタログ アイテムを取得します。
      • ベース ゲーム オファー → ベース ゲーム アイテム
      • デラックス ゲーム オファー → デラックス ゲーム アイテム
      • DLC オファー → DLC アイテム
      • 100 コイン オファー → 100 コイン アイテム

    これらのアイテムの所有権を検証する方法は 2 つあります。直接 SDK を使用するか、JSON Web トークン (JWT) を生成します。これらは、「Ecom インターフェース」のドキュメントで「ダイレクトな」方法および「トークンベース」の方法と呼ばれています。以下に「ダイレクトな」方法のステップを示しますが、「トークンベース」のメソッドの詳細については、このガイドの「独自のバックエンド サービスを使用して購入を安全に検証する」の項を参照してください。

  4. EOS_Ecom_QueryOwnership API を使用して、カタログ アイテム ID でユーザーの所有権情報をクエリします。 コールバックには、渡されたカタログ アイテム ID ごとの EOS_Ecom_ItemOwnership メンバーの配列が、対応する EOS_Ecom_Owned または EOS_Ecom_NotOwned の値とともに含まれています。

  5. 前述のコンフィギュレーション例では、ユーザーがデラックス ゲーム オファーを購入した場合、ベース ゲーム アイテム、デラックス ゲーム アイテムおよび DLC アイテムは、すべて EOS_Ecom_Owned としてマークされます。

ゲーム内通貨など消耗品の購入を検証および履行する

消耗品の購入は、EOS_Ecom_QueryEntitlements API および EOS_Ecom_RedeemEntitlements API をそれぞれ使用して、検証および消費できます。これらの API では、ユーザーがアイテムを 1 回以上購入したかどうかを検証し、ゲームで関連付けられている消耗品が付与されたかどうかのトラッキングを有効にします。EOS_Ecom_QueryEntitlements API は、CatalogItem ID と同じである EntitlementNames を受け取ります。

コンフィギュレーション例では、ユーザーは 100 コイン オファーを 1 回以上購入できます。これにより、利用資格を引き換えて、これらのコイン オファーを履行し、コインをプレイヤーのアカウントに追加できるようになります。

EOS_Ecom_QueryEntitlements API は購入した永続コンテンツの検証に使用 しないで ください。関連付けられているカタログ アイテム間の関係を考慮していないためです。コンフィギュレーション例のように、ユーザーは、ベース ゲーム アイテムと DLC アイテムの両方から構成されるデラックス ゲーム オファーを購入できます。このシナリオでは、EOS_Ecom_QueryEntitlements API ではデラックス ゲーム アイテムの利用資格のみが返され、ベース ゲーム アイテムまたは DLC アイテムとの関係は無視されます。

  1. 「Auth インターフェース」のドキュメントで説明されているように、EOS_Auth_Login を使用してユーザーを認証します。通常、これは、こちら で説明されているように、Epic Games Launcher で提供される ExchangeCode を使用して行われます。
  2. クエリする利用資格名がわかっている場合、ステップ 3 に進みます。わからない場合は、「購入した永続コンテンツを検証する」の前述のユースケースのステップ 1 と 2 に従って、適切な各カタログ アイテムの IDを取得します。取得したカタログ アイテム ID は、このプロセスに必要な利用資格名と同じです。
  3. 「Ecom インターフェース」のドキュメントの手順に従って、EOS_Ecom_QueryEntitlements を呼び出し、SDK キャッシュにユーザーの利用資格を設定します。次に、キャッシュから自分のコレクションに利用資格をコピーします。
    • 注記: デフォルトで、EOS_Ecom_QueryEntitlements API では、すでに引き換えられている利用資格は省略されます。
  4. キャッシュからコピーされた各 EOS_Ecom_Entitlement はユーザーが実行した購入を表し、これには一意の EntitlementId が含まれています。これらの ID を使用して、ゲーム コードで購入を履行できます。
    • コンフィギュレーション例では、ユーザーが 100 コイン オファーを 2 回購入すると、2 つの別々の EOS_Ecom_Entitlement のコピーが一意の EntitlementId を持つユーザーに対して存在します。
  5. ゲームで利用資格が履行されると (コインがプレイヤーのアカウントに追加された場合など)、「Ecom インターフェース」のドキュメントの手順に従って、EOS_Ecom_RedeemEntitlements API を使用して、利用資格を e コマース バックエンド サービスで引き換え済みとしてマークします。