Microsoft.StoreServices .NET ライブラリとサンプルの活用
この記事で説明する原則とフローを実演するために、Microsoft.StoreServices Sample を確認してください。このサンプルは、認証を管理し Microsoft Store サービスへの呼び出しを行うために Microsoft.StoreServices ライブラリを使用しています。サンプル サービス自体には、サブスクリプション製品を管理する例のロジックがあり、セットアップに必要な構成ガイドを提供します。サブスクリプション製品のタイプ
Store 管理およびアドオン サブスクリプションの両方の製品タイプは、Recurrence サービスと連携してユーザーのサブスクリプションを表示および管理できます。これらの各製品タイプの詳細については、適切な製品タイプを選択するを参照してください。ユーザーのサブスクリプションの照会
サブスクリプションの状態のプライマリ エンドポイントとして、purchase.mp.microsoft.com/v8.0/b2b/recurrences/query を使用します。これはアクティブおよび履歴のサブスクリプション期間と、変更操作に必要なsubscriptionId を返します。また、Grace 期間と Dunning 期間を区別するために必要なフィールドも含まれています。
Collections API (b2bLicensePreview (v8) および publisherQuery (v9)) はアクティブなサブスクリプションのエンタイトルメントを表示できますが、同じ recurrence の詳細は示しません。
クライアント側とサーバー間で満足するエンタイトルメント チェックの遅延
バンドルに新しいアイテム (満足するエンタイトルメント) を追加する更新を公開すると、クライアントとサーバー間 API クエリの間で新しいアイテムの可視性に遅延があります。この遅延は、異なる Store システムでカタログ キャッシュが異なる間隔で更新されるために発生します。変更がカタログに公開されると、ローカル ライセンス サービスは通常最初に更新情報を取得し、publisherQuery で使用されるキャッシュは 2 ~ 3 時間後になります。したがって、クライアント側 API がアクセスを許可してから、サーバー間呼び出しが新しいアイテムの所有権を反映するまでには数時間かかることを想定してください。 Recurrence サービス自体は影響を受けません。新しく追加されたアイテムに対して満足するエンタイトルメントを照会する publisherQuery または b2bLicensePreview エンドポイントのみが影響を受けます。サブスクリプションの開始日、更新日、期限切れ日を理解する
サブスクリプションのStartTime は、アクティブなサブスクリプションが開始された日付です。サブスクリプションが自動更新に設定されている場合、開始日は変わりませんが、翌月以降にサブスクリプションが更新されると、期限切れ日が変わります。サブスクリプションがキャンセル、期限切れ、または取り消しになった場合、ユーザーがサブスクリプションを再度購入すると新しいサブスクリプション オブジェクトが作成されます。新しいアクティブなサブスクリプション期間は、ユーザーが新しいサブスクリプションをアクティブ化または購入した日の StartTime を持ちます。
Microsoft Store 内のサブスクリプション期間は通常、月単位の数量として構成されます。たとえば、1 か月、3 か月、または 12 か月です。ユーザーが 1 か月のサブスクリプションを購入すると、StartTime はサブスクリプションを開始した日の UTC 深夜 (00:00:00) になります。ExpirationTime は、StartTime に月数 (日数ではない) を追加したものから 1 秒を引いた値 (23:59:59 UTC) になります。この値は、サブスクリプションが UTC 深夜のちょうど前に期限切れになるようにするためのものです。 ただし、月によって日数が異なるため、月の 29 日、30 日、31 日に開始されたサブスクリプションでは競合が発生します。
ユーザーの
StartTime がこれらの日のいずれかに該当する場合、ExpirationTime は期限切れとなる月の最終日の 23:59:59 UTC となるように変更されます。この方法により、更新日は常に月初の UTC 深夜 (00:00:00) となり、ExpirationTime は常に月末の 23:59:59 UTC となります。
1 か月サブスクリプションの開始日、更新日、期限切れ日の動作例
Grace および Dunning 状態を理解する
ExpirationTime に自動更新の支払いが失敗した場合、サブスクリプションは Grace に入り、未解決の場合は Dunning に入ります。両方の期間は状態を InDunning と報告するため、現在の UTC 時刻を ExpirationTimeWithGrace と比較して現在の期間を判断します。
ユーザーのサブスクリプションが Grace または Dunning にある間は、Microsoft アカウント サービスとサブスクリプションで請求状態を確認するようユーザーに通知する必要があります。
これらの各状態にテスト用にアカウントを適切に設定するには、サブスクリプション製品のテストを参照してください。
Grace 期間
Grace 期間中は、Store が更新の支払いを再試行している間、サブスクリプションの特典を有効にしたままにします。更新が成功した場合、使用された Grace の日数は次の期間から差し引かれます。ExpirationTimeWithGrace の前に支払いが解決されない場合、サブスクリプションは Dunning に移行します。
Dunning 期間
Dunning は Grace の終了後に開始されます。この期間中はサブスクリプションの特典を無効にします。Dunning 中はユーザーは同じサブスクリプションを再購入または引き換えることはできません。Dunning を通して支払いが未解決のままの場合、サブスクリプションは非アクティブになります。Grace と Dunning の長さ
ユーザーのサブスクリプションの変更
サービスは purchase.mp.microsoft.com/v8.0/b2b/recurrences//change を使用してサブスクリプションを変更することもできます。サポートされている操作には、日数の追加、自動更新の無効化、およびサブスクリプションのキャンセルがあります。サービスは、ユーザーのサブスクリプションを操作するためにrecurrenceId (RecurrenceQuery API の id と同じ値、および Collections query API からの recurrenceData 値) が必要です。
Recurrence Change エンドポイントがサービスに役立つ例をいくつか示します。
- サービス停止を経験したユーザーのサブスクリプションに時間を追加する。
- 顧客サービス サポート チームと統合して、サブスクリプション状態やキャンセルなどの情報でユーザーを支援する。
- ユーザーが自動更新などの設定を変更したり、サブスクリプションを終了したりできるようにするゲーム内 UI。
サブスクリプション製品のテスト
Recurrence Change API はテスト用にも使用できます。Extend は負の日数値を受け入れ、テスト サブスクリプションを目的の状態に進めることができます。
アクティブ、非アクティブ、キャンセル状態のテスト
サブスクリプションのアクティブ、非アクティブ、キャンセル状態をテストする場合、サブスクリプションの基本価格を $0.00 にできます。テスト アカウントにサブスクリプションを追加してアクティブ状態を確認し、Recurrence Change エンドポイントを使用して自動更新を無効にします。次に、Recurrence Change エンドポイントを使用してサブスクリプションをキャンセルするか、ExpirationTime が現在の UTC DateTime を過ぎるように十分な日数を差し引きます。
Grace および Dunning 状態のテスト
Grace および Dunning 状態をテストするには、サブスクリプションにゼロ以外の価格が必要です。さらに、
ExpirationTime を過ぎた後の以降の支払いが成功しないようにテスト アカウントを構成する必要があります。現在、Microsoft Store にはテスト用の支払い手段がないため、アカウントを設定する最も簡単な方法は、プリペイド通貨コードを使用することです。
- $0.99 などの低価格でテスト環境にサブスクリプションを設定します。
- 最初のサブスクリプション購入 (税込) を賄うが更新はできない金額として、XBOX プリペイド ギフト カードを購入します ($1.00 または $2.00)。
- ギフト カードをテスト アカウントで引き換えます。
- テスト アカウントでサブスクリプションを購入します。
- サブスクリプションの自動更新が有効になっているが、サブスクリプションを更新するのに十分な資金がないことを確認します。
- Recurrence Change を使用してサブスクリプションの
ExpirationTimeを次の 24 時間以内に移動します (以下のメモを参照)。 ExpirationTimeを自然に経過させ、状態がInDunningに表示されるのを待ちます (ExpirationTimeの後に最大 24 時間かかることがあります)。
Grace および Dunning 期間の「InDunning」状態にアカウントを適切に入れるには、アカウントは自然に
ExpirationTime および ExpirationTimeWithGrace の日付を過ぎる必要があります。日数を差し引くときは、次の 24 時間以内の ExpirationTime をターゲットとし、その後時間を自然に経過させてください。ExpirationTime を既に過去の時点に移動すると、InDunning が表示されず、テスト状態が無効になる場合があります。この問題を解決する唯一の方法は、サブスクリプションをキャンセルして新しいテスト サブスクリプションを作成することです。