エンタイトルメント
エンタイトルメントは、ゲーム、サブスクリプション、アドオンなどのデジタル製品にアクセスして使用する顧客の権利を表します。Microsoft Store で行われるすべての購入や引き換えは、Microsoft の collections サービスで追跡される 1 つ以上のエンタイトルメントとなります。エンタイトルメントで機能する製品タイプの詳細については、適切な製品タイプを選択するを参照してください。 製品のエンタイトルメントは、プレイヤーが製品を直接購入する、満足させる製品 (バンドルやサブスクリプションなど) を購入する、または別のユーザーから共有されたエンタイトルメントを通じて付与されます。エンタイトルメントは、アクティブ、非アクティブ、期限切れ、取り消し済みなど、複数の状態をサポートします。 ゲーム クライアントとサービスはプレイヤーのエンタイトルメントを照会できますが、結果は異なる場合があります。- クライアント API はアクティブな状態のエンタイトルメントのみを返せますが、すべてのエンタイトルメントの種類 (直接、共有、満足) を返すことができます。ただし、エンタイトルメントの種類はクライアントには表示されません。
- サービス API は任意の状態のエンタイトルメントを返せますが、デバイス コンテキストがないため共有エンタイトルメントを返せません。ただし、直接エンタイトルメントと満足エンタイトルメントを区別できます。
エンタイトルメントの共有とオフライン可用性
- 製品を所有するアカウントが現在のデバイスをオフライン デバイスに指定した場合 (コンソールの Home XBOX または PC の オフライン権限 を使用)、デバイス上の他のアカウントと消費型以外のエンタイトルメントを共有します。
- 消費型のエンタイトルメントは、購入したアカウントに紐付けられた直接エンタイトルメントであり、デバイス上の他のアカウントと共有できません。
- すべてのエンタイトルメント クエリにはオンライン接続が必要です。オフライン時にプレイヤーのアクセス権を判断するためにエンタイトルメントを使用しないでください。代わりにライセンス供与を使用してください。
ゲーム クライアントでのエンタイトルメントの使用
クライアントがカタログ要求を送信するたびに、返される各 XStoreProduct のIsInUserCollection プロパティを設定するために、collections サービスへの対応する呼び出しを送信します。IsInUserCollection が true の場合、プレイヤーに製品を使用する権利があることを示します。ゲーム内ストアフロントで購入可能として表示するか、プレイヤーが既に「所有」しているとして表示するかを決定するときにこの値を使用してください。
アドオン コンテンツの XStoreProduct の詳細は、次の方法で取得できます。
- XStoreQueryAssociatedProductsAsync / Result - 購入可能な製品のみを返します。結果には、非表示の製品、バンドルでのみ利用可能な製品、または Microsoft Store で購入できなくなった製品は含まれません。
- XStoreQueryProductsAsync / Result - 特定の製品を照会するために使用します。この関数を使用して、単一の製品または製品のサブセットに対するエンタイトルメントの変更を確認します。
ゲーム サービスでのエンタイトルメントの使用
ゲーム サービスを使用するときは、エンタイトルメントを照会および管理するためのより高度なオプションが利用できます。可能な内容の一例:- 発行元カタログ全体にわたるユーザーのエンタイトルメントを照会します。
- 直接エンタイトルメントと満足エンタイトルメントを区別して、プレイヤーがどのようにコンテンツを取得したかをより深く理解します。
- 将来の開始日を持つ非アクティブなエンタイトルメントを照会して、まだ予約購入状態の購入を検出します。
- 堅牢でクロスプラットフォームな消費型エコシステムを管理します (消費型ベースのエコシステムを参照)。
- Clawback サービスを使用して製品の返金を検出します (サービスから返金とチャージバックを管理するを参照)。
- XBOX Game Pass サブスクリプションの状態を検出して、ゲーム内でサブスクライバーに特典を付与します (サービスから XBOX Game Pass サブスクリプションのアクセスを検出するを参照)。
エンタイトルメントに関する考慮事項
- PC 上の開発者サンドボックスで操作する場合、クライアントは XBOX App にサインインしているアカウントの代わりにすべてのエンタイトルメント クエリを行います。
- PC 上の RETAIL で操作する場合、クライアントは Microsoft Store にサインインしているアカウントの代わりにすべてのエンタイトルメント クエリを行います。ゲームにサインインしているアカウントが Microsoft Store にサインインしているアカウントと一致しない場合、アカウントの不一致シナリオが発生することがあります (詳細については、Store アカウントの不一致を処理するを参照してください)。
ライセンス供与
ライセンスは、デバイス上でコンテンツにアクセスするユーザーの権利を確認するデジタル キーです。ライセンスを取得する前に、ユーザーが製品を使用する権利を持つか、製品を含むディスク (パッケージを含むゲームおよび耐久型) を挿入する必要があります。 耐久型 (パッケージの有無を問わず) を扱う際は、共有、並行性、およびオフライン可用性に関する期待に合わせるためにライセンス供与を使用してください (ゲームの製品共有モデルを参照)。 ライセンスは、ゲームが使用するライセンス モデルに応じたデバイスの制限と並行性チェックの対象となります (オープン ライセンスと制限的ライセンスを参照)。プレイヤーに製品のアクティブなエンタイトルメントがあっても、デバイスで使用する有効なライセンスを取得できないことがあります。ライセンス共有とオフライン可用性
次の条件のいずれかが true の場合、デバイスでライセンス共有が発生します。- 所有者のアカウントがサインインしていてオンライン接続が確立されている状態で、ゲームがライセンスを取得した。
- ゲームが所有者のアカウントのオフライン ライセンス (コンソールの Home XBOX または PC の オフライン権限 としてオフライン デバイスに指定) を取得した。このシナリオでは、所有アカウントがデバイスにサインインしていなくても、他のアカウントとライセンスを共有できます。
- プレイヤーが DLC (パッケージを含む耐久型) を含むディスクを挿入し、DLC がデバイスにインストールされた。
- 製品を所有するアカウントが現在のデバイスを「オフライン」デバイスに指定する (コンソールの Home XBOX または PC の オフライン権限 を使用)。オフライン指定が有効化された後、ゲームはオンライン中に耐久型製品のライセンスを取得する必要があります。次にゲームを起動したときに、オフライン対応ライセンスを取得します。
- プレイヤーが DLC (パッケージを含む耐久型) を含むディスクを挿入し、DLC がデバイスにインストールされている。
ゲーム クライアントでのライセンスの使用
次のフローを使用して、耐久型 (パッケージの有無を問わず) をライセンス供与できます。- XStoreCanAcquireLicenseForStoreIdAsync / Result は、並行性チェックを呼び出さずにライセンスをプレビューします。XStoreCanLicenseStatus が
Licensableの場合、ゲームは耐久型ライセンスの取得を試みることができます。このプレビュー チェックにはオンライン接続が必要です。 - XStoreAcquireLicenseForDurablesAsync / Result は、デバイスにライセンスがない、または現在のライセンスが期限切れの場合にライセンス供与サービスを呼び出してライセンスを取得します。デバイス上に製品のアクティブなライセンスが既にあるか、この API をオフラインで呼び出した場合は、キャッシュ済みのライセンスが返されます。キャッシュ済みライセンスが返された場合、現在のプレイヤーには有効でない可能性があります。
- ゲーム内のコンテンツをアンロックする前に、常に XStoreIsLicenseValid を呼び出してライセンスが有効かどうかを確認してください。
- 有効なライセンスを取得した場合は、XStoreRegisterPackageLicenseLost を使用してライセンス消失イベントをリッスンします。ライセンスが失われた場合は、ライセンスの再取得を試みてください。ライセンスを再取得できない場合は、いつコンテンツへのプレイヤーのアクセスをブロックするか、しないかを (ゲームの設計に応じて) 決定してください。
- ライセンス消失イベントを処理した後は、XStoreUnregisterPackageLicenseLost を呼び出し、XStoreCloseLicenseHandle を呼び出して古いライセンス ハンドルを解放してください。
ゲーム サービスでのライセンスの使用
ライセンスはデバイスに紐付けられており、ゲーム サービスから照会することはできません。ただし、クライアントは XStoreQueryLicenseTokenAsync / Result を呼び出して、ゲーム サービスを使用して追加の検証を提供できます。詳細については、ライセンス トークンの使用を参照してください。ライセンス供与に関する考慮事項
- 購入が完了してから新しいライセンスを取得できるまでに遅延がある場合があります。ユーザーのエンタイトルメントへの変更を確認し、耐久型製品の新しいエンタイトルメントが追加された後にライセンスを取得してください。
- サイドロードされたパッケージを展開する場合、パッケージを含む耐久型のテスト ライセンスは自動的に付与されます。パッケージを含む耐久型のライセンス供与シナリオをテストするには、代わりにライセンスの上書き、または Store からインストールされたパッケージを使用してください。詳細については、ライセンス テストの有効化を参照してください。
- ゲームが耐久型ライセンスを取得すると、ライセンスはデバイス上にキャッシュされます。ライセンスは、システムがライセンスの更新をトリガーするまでキャッシュから取得されます (更新を強制する API はありません)。XStoreAcquireLicense* の繰り返し呼び出しはデバイスのキャッシュを確認し、サービスは確認しません。
- ライセンス消失コールバックは、現在のプレイヤーに別のアカウントに属するキャッシュ済みライセンスがシステムから誤って返された場合の検出に役立ちます。そのような場合、ライセンス消失イベントが直ちに発生し、XStoreAcquireLicense* が再度呼び出されると、新しいライセンスが提供されます。
- ライセンス共有とキャッシュにより、テスト マシンがクリーンでない状態になることがあります。詳細については、XStore 開発のトラブルシューティングを参照してください。
サンプル リソース
プレイヤーのエンタイトルメントを照会し、耐久型ライセンスを取得する方法を示すサンプル コードについては、次のリソースを参照してください。- InGameStore サンプル (GitHub): 製品の取得、購入、エンタイトルメント、耐久型のライセンス供与など、XStore の機能を示す C++ サンプル。
- DownloadableContent サンプル (GitHub): パッケージ化された耐久型の列挙とライセンス供与など、XStore と XPackage の機能を示す C++ サンプル。
- UnityInGameStore サンプル (GitHub): Unity ゲーム エンジンと Microsoft GDK API パッケージを使用して XStore の機能を示す C# サンプル。
リファレンス API ドキュメント
- XStore (API の内容)
- 関数
- XStoreQueryAssociatedProductsAsync
- Result
- XStoreQueryProductsAsync
- Result
- XStoreQueryEntitledProductsAsync
- Result
- XStoreCanAcquireLicenseForStoreIdAsync
- Result
- XStoreAcquireLicenseForDurablesAsync
- Result
- XStoreIsLicenseValid
- XStoreRegisterPackageLicenseLost
- XStoreUnregisterPackageLicenseLost
- XStoreCloseLicenseHandle
- XStoreCanAcquireLicenseForPackageAsync
- Result
- XStoreAcquireLicenseForPackageAsync
- Result
- XStoreQueryLicenseTokenAsync
- Result
- 構造体
- 関数
- XPackage (API の内容)
関連項目
コマースの概要XStore API リファレンス