Commerce インターフェース

ゲームプレイ以外でのゲーム コンテンツの購入と引き換え

Online Services の Commerce インターフェース は、ゲームプレイ以外でのゲーム コンテンツの購入/引き換え機能をプレイヤーに提供するゲーム サービス向けの Unreal Engine の基盤となるインターフェースです。Commerce インターフェースは、次の 2 つの主要なコンポーネントで構成されています。

  • トランザクション:プラットフォーム通貨を使用してストアのアイテムを購入するプロセス。

    • トランザクションが完了すると、インターフェースによってプレイヤーに適切な利用資格が付与されます。

  • 利用資格:プレイヤーが受け取る、または使用する資格のあるコンテンツ。

    • プレイヤーがアイテムの購入、またはゲーム コードの引き換えを行ったことにより、利用資格を受け取るか、使用することができます。

API の概要

次の表は、Commerce インターフェースに含まれる関数の概要です。

関数

説明

Offers (オファー)

QueryOffers

ストアから使用可能なすべてのオファーのリストをフェッチし、インターフェースにキャッシュします。これには、使用可能なダウンロード コンテンツ (DLC)、バンドル、アイテムなどが含まれます。

QueryOffersById

指定された ID のリストから使用可能なオファーのリストをフェッチし、インターフェースにキャッシュします。

GetOffers

QueryOffers でキャッシュされたインターフェースからオファーを取得します。

GetOffersById

インターフェースでキャッシュされた、指定の ID のリストからオファーを取得します。

Store (ストア)

ShowStoreUI

ユーザーがゲーム クライアント以外でストア情報を表示したり、トランザクションを処理するためのネイティブのストア UI を表示します。

Checkout (チェックアウト)

Checkout

GetOffers または GetOffersById で取得した 1 つ以上の購入オファーを使用して、購入プロセスを開始します。

Event Listening (イベントのリッスン)

OnPurchaseCompleted

ローカル ユーザーがトランザクションを完了するたびに発行されるイベント。これは、Checkout で内部で開始することも、ネイティブのストア UI を使用して外部で開始することもできます。

Entitlements (利用資格)

QueryTransactionEntitlements

成功した Checkout 呼び出しに該当するインゲームの利用資格を表示し、プレイヤーにこの利用資格で使用可能な機能を提供します。

QueryEntitlements

ストアから特定のユーザーの取得済み利用資格のリストをフェッチし、インターフェースにキャッシュします。

GetEntitlements

QueryEntitlements でキャッシュされたインターフェースから利用資格を取得します。

RedeemEntitlement

利用資格に「redeemed」(引き換え済み) とマークします。それ以降は、その利用資格をクエリするとフラグが「redeemed」になります。これは、利用資格を管理する外部のゲーム サービスがない場合に役立ちます。

Verification (検証)

RetreiveS2SToken

プラットフォームと通信して、付与された利用資格の所有権を検証するためにゲーム サービスのバックエンドに送信できるトークンを返します。

プロセス フロー

次に、ユーザーがインゲーム ストアにアクセスして購入し、購入した内容を使用するために検証を行う一連のフローを Online Services の Commerce インターフェースで制御するプロセス フローの例を示します。

ゲームを起動する

ユーザーがゲームを起動し、希望するオンライン サービスで認証に成功すると、ゲームは QueryEntitlements を呼び出します。QueryEntitlements でキャッシュされたデータと、ユーザーのセーブ データに登録されている利用資格を比較し、オフラインの間に付与された利用資格を確認して、適宜ユーザーに該当する利用資格を適用します。同時に、OnPurchaseCompleted イベントを使用して、今後ユーザーが購入を完了した場合に発行されるメッセージをリッスンします。

In-Game Store インターフェースにアクセスする

ユーザーがインゲーム時にストアのメニューを開きます。ゲームで、ユーザーがストアを開くためのロード画面が表示され、同時に QueryOffers が呼び出されます。クエリが解決されたら、ゲームは GetOffers を呼び出してデータのローカル コピーを取得します。ローカル コピーは、UI フレームワークに渡され、ゲーム オファーをレンダリングして表示します。

トランザクションを実行する

オファーのアイテムが表示されたら、ユーザーは特定の製品の購入を決定します。この例では、この製品を PRODUCT_A とします。ユーザーは、インゲームのカートに PRODUCT_A を追加し (インゲーム UI によって処理される)、トランザクションを確認します。ユーザーの認証後、ゲームは PRODUCT_A の ID を使用して Checkout を呼び出します。これにより、最終確認と支払い処理を行うプラットフォーム UI に遷移します。

Checkout が正常に解決され、OnPurchaseCompleted イベントが発行されると、ゲームは指定されたトランザクション ID で QueryTransactionEntitlements を呼び出し、トランザクションの一部としてユーザーに付与されたインゲームの利用資格 ID を取得し、ユーザーのセーブ ゲームに適用します。PRODUCT_A がユーザーのゲームプレイにグローバルに付与できないアイテムである場合は、ゲームで RedeemEntitlement を呼び出すことで、PRODUCT_A に対する利用資格が重複して付与されないようにします。

トランザクションを検証する

購入および PRODUCT_A の引き換えが正常に行われたら、ユーザーは新たに購入した PRODUCT_A でオンライン プレイを開始することを決定します。ゲーム サーバーを認証する際に、ゲームは、ローカル ユーザーが新しい利用資格を請求していることを認識すると、検証トークンを要求して、製品が適正であることを確認します。ゲームは検証用に指定された ID に対して RetrieveS2SToken を呼び出し、JSON Web Token (JWT) を取得します。その後、バックエンド サービスがこの JWT を使用してプラットフォーム サービスに接続し、製品の所有権を検証します。これが正常に返されると、ユーザーは新規に購入したアイテムを使用してオンライン プレイに参加することができます。

Online Subsystem からコードを変換する

Online Services の Commerce インターフェースは Online SubsystemStore (読み取り専用コード) インターフェースおよび Purchase (読み取り/書き込みコード) インターフェースの両方が所有するすべてのコードに対応しています。次の表に、Online Systems の Commerce インターフェースのオブジェクトと、以前の Online Subsystem でそれに対応するオブジェクトとの一致関係を示します。

Online Services

Online Subsystem

インターフェース

オブジェクト

インターフェース

オブジェクト

Commerce

Offer

Store

Offer

Commerce

Entitlement

Purchase

Entitlement

詳細情報

API リファレンス

ヘッダ ファイル

また、必要に応じてヘッダ ファイル「Commerce.h」を直接見ることで、詳細を確認することもできます。Commerce インターフェースのヘッダ ファイル「Commerce.h」は次のディレクトリに格納されています。

UNREAL_ENGINE_ROOT\Engine\Plugins\Online\OnlineServices\Source\OnlineServicesInterface\Public\Online

UE のソース コードの入手方法に関するステップごとのガイドについては、「Unreal Engine のソース コードをダウンロードする」を参照してください。

関数パラメータおよび戻り型

関数パラメータおよび戻り型 (パラメータの渡し方、関数が戻す結果の処理など) については、「Online Services Overview (Online Services の概要)」ページの「Functions (関数)」セクションを参照してください。

Unreal Engine のドキュメントを改善するために協力をお願いします!どのような改善を望んでいるかご意見をお聞かせください。
調査に参加する
キャンセル