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 Subsystem の Store (読み取り専用コード) インターフェースおよび Purchase (読み取り/書き込みコード) インターフェースの両方が所有するすべてのコードに対応しています。次の表に、Online Systems の Commerce インターフェースのオブジェクトと、以前の Online Subsystem でそれに対応するオブジェクトとの一致関係を示します。
| Online Services | Online Subsystem | ||
|---|---|---|---|
| インターフェース | オブジェクト | インターフェース | オブジェクト |
| Commerce | Offer | Store | Offer |
| Commerce | Entitlement | Purchase | Entitlement |
詳細情報
API リファレンス
ヘッダ ファイル
また、必要に応じてヘッダ ファイル「Commerce.h」を直接見ることで、詳細を確認することもできます。Commerce インターフェースのヘッダ ファイル「Commerce.h」は次のディレクトリに格納されています。
Engine\Plugins\Online\OnlineServices\Source\OnlineServicesInterface\Public\Online
UE のソース コードの入手方法に関するステップごとのガイドについては、「Unreal Engine のソース コードをダウンロードする」を参照してください。
関数パラメータおよび戻り型
関数パラメータおよび戻り型 (パラメータの渡し方、関数が戻す結果の処理など) については、「Online Services Overview (Online Services の概要)」ページの「Functions (関数)」セクションを参照してください。
