XStore API 呼び出しの準備
すべてのXStore API は、XStoreCreateContext を使用して作成された XStoreContextHandle を介して動作します。
このコンテキストにより、コンソールでは指定したユーザー、PC では利用可能な既定のユーザーのコンテキストで Store 操作を実行できます。コンソールでは、Suspend または Quick Resume イベントによってコンテキストが無効になります。これらの状況を安全に処理するには、XStoreContextHandle を閉じ、ゲームが中断状態から再開するたびに再作成してください。
1. ユーザーが購入できるものの決定
ゲームが購入用に提供するのは、通常はアドオンです。次のコードは、ゲームが利用可能な製品を把握するために必要な基本的な XStoreQueryAssociatedProductsAsync API 呼び出しを示しています。 このクエリは自動的に、ゲームに関連付けられている 購入可能な アドオンのみを返します。同じ発行元 (つまり、同じパートナー センター アカウントで構成されている) に関連付けられている無関係な製品も、パートナー センターの [製品関係のセットアップ] セクションで、ゲームがその製品に「販売可能」の関係で設定されていれば、この呼び出しで返すことができます。 製品関係の構成について詳しくは、ゲームの製品関係を構成するを参照してください。注意事項
XStoreQueryAssociatedProductsAsyncでは、購入可能な製品のみが返されます。バンドルでのみ付与される製品や、独立して購入できるように設定されていない製品は返されません。後者については、XStoreQueryProductsAsyncを使用してください。- 返される製品の数は事前にわかっていないため、カウントを蓄積する必要があります。
ページング
関連製品またはエンタイトルメントを照会するときは、ページングの処理はオプションではありません。サービスから返されるページ数と、1 ページあたりに返される項目数は、環境やサービスの負荷によって異なる場合があります。ページングを処理する方法の例については、XStoreQueryAssociatedProductsAsync を参照してください。その他のオプション
XStoreQueryProductsAsync は、storeId がわかっている場合や、他の actionFilters が必要な場合に、特定の製品を照会するために使用できます。「アクション」とは、Purchase、License、Gift、Redeem などの動詞を含む、製品に適用される使用シナリオです。
XStoreQueryAssociatedProductsForStoreIdAsync は、他のゲームの関連製品を照会するために使用でき、別のタイトルのアドオンをクロスセルするのに便利です。
XStoreQueryProductForCurrentGameAsync は、現在実行中のゲームの製品のみを照会するためのものです。
XStoreShowAssociatedProductsUIAsync は、ユーザーを Microsoft Store アプリに遷移させ、製品の種類でフィルターされた関連製品のビューに移動します。この API は、ゲーム内のインターフェイスで提示する利用可能な製品を列挙する代替手段です。
2. ユーザーが所有または権利を持つ製品の評価
この手順では前述のコードとほぼ同じものを使用しますが、次の置き換えを行います。- XStoreQueryAssociatedProductsAsync → XStoreQueryEntitledProductsAsync
- XStoreQueryAssociatedProductsResult → XStoreQueryEntitledProductsResult
QueryEntitledProducts API は、ユーザーに権利がある製品を返します。エンタイトルメント (権利があること) とは、ユーザーが製品を直接所有している、他の製品 (バンドルやサブスクリプションなど) を通じてエンタイトルメントを満たしている、または別のユーザーからの共有エンタイトルメントを通じて権利を得ていることを意味します。
さらに、XStoreQueryAssociatedProductsAsync (および関連関数) の結果によってエンタイトルメントが決まります。XStoreProduct 構造体には、ユーザーが権利を持つ場合に true に設定される isInUserCollection フィールドが含まれます。
消費型の所有権
消費型の数量はXStoreProduct.skus[i].collectionData.quantity に記載されています。通常、消費型製品には SKU が 1 つしかありません。
数量を照会するために XStoreQueryConsumableBalanceRemainingAsync を使用することもできますが、各呼び出しがサービス呼び出しを発生させるため、多数の消費型に対して個別に使用しないでください。
消費型ベースのエコシステムの整合性を維持するには、消費型のサービス側検証と引き換えを使用してください。詳細については、消費型ベースのエコシステムを参照してください。
耐久型の所有権
アカウントが製品を所有しているかを確認するだけでは、ゲーム内でその製品を使用する権利があると判断するには不十分です。耐久型製品は、ゲームの製品共有モデルで説明されているコンテンツ共有ポリシーに従う必要があります。 コンテンツ共有のルールに従ってライセンス供与可能かを判定するには、パッケージを含む耐久型 に対して XStoreAcquireLicenseForPackageAsync を使用します。 パッケージのない耐久型 に対して同じことを行うには、XStoreAcquireLicenseForDurablesAsync を使用します。 デジタル ライセンス供与されたゲームに対して、ライセンス供与可能なパッケージのない耐久型製品の一覧を返すには、XStoreQueryAddOnLicensesAsync を使用します。 詳細については、ダウンロード可能なコンテンツの管理とライセンス供与およびパッケージのない耐久型の使用方法を参照してください。3. 対象製品の購入
購入可能な製品の購入フローを表示するには、storeId を XStoreShowPurchaseUIAsync API に渡します。
リファレンス API ドキュメント
- XStore (API の内容)
- 関数
- XStoreCreateContext
- XStoreQueryAssociatedProductsAsync
- XStoreQueryProductsAsync
- XStoreQueryAssociatedProductsForStoreIdAsync
- XStoreQueryProductForCurrentGameAsync
- XStoreShowAssociatedProductsUIAsync
- XStoreQueryEntitledProductsAsync
- XStoreQueryAssociatedProductsResult
- XStoreQueryEntitledProductsResult
- XStoreQueryConsumableBalanceRemainingAsync
- XStoreAcquireLicenseForPackageAsync
- XStoreAcquireLicenseForDurablesAsync
- XStoreQueryAddOnLicensesAsync
- XStoreShowPurchaseUIAsync
- 構造体
- 関数
