サービスからのサブスクリプション製品の管理
タイトルまたはパブリッシャーがサブスクリプション製品を使用している場合は、バックエンド サービスを開発してユーザーのサブスクリプションの状態を検証し、サブスクリプションを管理することをお勧めします。 これにより、サービスはユーザーのサブスクリプションの状態とサポート チームに関する追加のインサイトを得て、ユーザーのサブスクリプションに関する問題の解決、時間の追加、取り消しを行うことができます。
この記事では、Recurrence サービス エンドポイントを使用して、独自のサービスでこれらのシナリオを有効にする方法について説明します。
Microsoft.Store Services .NET ライブラリとサンプルの利用
この記事で概説されている原則とフローを示すために、Microsoft.StoreServices サンプルを確認してください。 このサンプルでは、Microsoft.StoreServices ライブラリを使用して認証を管理し、Microsoft StoreServices を呼び出します。 サンプル サービス自体には、サブスクリプション製品を管理するためのサンプル ロジックがあり、設定するための構成ガイドが提供されています。
サブスクリプション製品の種類
ストア管理のサブスクリプションとアドオン サブスクリプションの両方の製品の種類は、Recurrence サービスと連携して、ユーザーのサブスクリプションを表示および管理します。 これらの製品の種類の詳細については、「適切な製品の種類の選択」を参照してください。
ユーザー サブスクリプションのクエリ
purchase.mp.microsoft.com/v8.0/b2b/recurrences/query は、ユーザーのサブスクリプション情報を照会するためのメイン エンドポイントです。 このエンドポイントは、ユーザーの現在アクティブなサブスクリプション期間と過去のサブスクリプション期間の両方を報告します。 さらに、サブスクリプションに変更を加えるのに必要な subscriptionId と、サブスクリプションが猶予期間と催告期間であるタイミングを検出するための詳細情報が提供されます。
コレクション エンドポイント (B2bLicensePreview (v8) または PublisherQuery (v9)) は、どちらもユーザーのアクティブなサブスクリプションを返しますが、Recuurence クエリ API が行うレベルの詳細と情報は提供しません。
クライアントとサーバー間のエンタイトルメント チェックを満たすまでの延期期間
新しいアイテム (エンタイトルメントを満たす) を追加するサブスクリプションに更新プログラムを発行すると、クライアントで有効になっているエンタイトルメントと b2bLicensePreview や PublisherQuery などのサーバー間クエリに反映されるまでに遅延が発生します。 これは、異なるストア システムによって使用されるカタログ キャッシュが異なる間隔で更新されるためです。 変更がカタログに発行されると、通常、ローカル ライセンス サービスは更新された情報を最初に取得し、PublisherQuery によって使用されるキャッシュは 2 から 3 時間以内に取得されます。 そのため、発行後、ユーザーがコンテンツを受け取る権利を持つ数時間が発生しますが、PublisherQuery に対するサーバー間の呼び出しでは、新しく含まれる項目の結果はまだ返されないことに注意してください。 サブスクリプション自体に対する定期的なサービスのクエリは、サブスクリプション自体の影響を受けず、PublisherQuery または b2bLicensePreview から前提条件を満たしたエンタイトルメントまたは含まれるアイテムに対してクエリを実行するときにサブスクリプションに追加される項目のみです。
サブスクリプションの開始日、更新日、有効期限について
サブスクリプションの StartTime の日付は必ず、アクティブなサブスクリプションが開始された日付になります。
サブスクリプションが自動更新に設定されている場合、開始日は変わりませんが、次の月にサブスクリプションが更新されると有効期限が変更されます。
サブスクリプションが取り消された場合、期限切れになった場合、または取り消された場合、ユーザーがサブスクリプションをもう一度購入すると、新しいサブスクリプション オブジェクトが作成されます。
この新しいアクティブなサブスクリプション期間は、StartTime が新しいサブスクリプションをアクティブ化または購入した日の日付になります。
Microsoft Store 内のサブスクリプション期間は、通常、月の数量として構成されます。
たとえば、1 か月、3 か月、12 か月などです。
ユーザーが 1 か月のサブスクリプションを購入すると、StartTime はサブスクリプションを開始した日の午前 0 時 UTC (00:00:00) になります。
ExpirationTime は、StartTime から 1 秒引いた時刻 (23:59:59 UTC) に、月数が追加された数値になります (日数ではありません)。
これにより、サブスクリプションは UTC 時間の午前 0 時直前に期限切れになります。
ただし、月によって日数が異なるため、月の 29 日、30 日、または 31 日から開始するサブスクリプションとの競合が発生します。
ユーザーの StartTime がこれらの日のいずれかに該当する場合、ExpirationTime は、有効期限の月の最終日の 23:59:59 UTC に変更されます。
これにより、更新日が常に次の月の最初の日の午前 0 時 UTC (00:00:00) になり、ExpirationTime は月の最終日の 23:59:59 UTC になります。
1 か月サブスクリプションの開始日、更新日、有効期限の動作の例
| 購入日 | StartTime | ExpireTime | 自動更新日 | アクティブな日数 |
|---|---|---|---|---|
| 2023-02-27T12:00:00Z | 2023-02-27T00:00:00Z | 2023-03-26T23:59:59Z | 2023-03-27T00:00:00Z | 28 |
| 2023-03-27T12:00:00Z | 2023-03-27T00:00:00Z | 2023-04-26T23:59:59Z | 2023-05-27T00:00:00Z | 31 |
| 2023-03-29T12:00:00Z | 2023-03-29T00:00:00Z | 2023-04-30T23:59:59Z | 2023-05-01T00:00:00Z | 32 |
| 2023-04-29T12:00:00Z | 2023-04-29T00:00:00Z | 2023-05-31T23:59:59Z | 2023-06-01T00:00:00Z | 33 |
| 2023-04-30T12:00:00Z | 2023-04-30T00:00:00Z | 2023-05-31T23:59:59Z | 2023-06-01T00:00:00Z | 32 |
| 2024-02-27T12:00:00Z | 2024-02-27T00:00:00Z | 2024-03-26T23:59:59Z | 2024-03-27T00:00:00Z | 29 (うるう年) |
猶予期間と催告期間の状態について
ユーザーがサブスクリプションの自動更新に登録されている場合、Microsoft Store は、サブスクリプションの ExpirationTime 値に基づいて、ユーザーのアカウントで支払い方法の請求を試みます。
支払いが完了できない場合、サブスクリプションは取り消されず、Microsoft Store が支払いの解決と再試行を試みる間、猶予期間、さらに催告期間へと移行します。
猶予期間と催告期間の両方で、サブスクリプションの状態は InDunning として表示されます。
サブスクリプション製品をサービスと統合する場合は、ユーザーが猶予期間または催告期間に入った時期を特定し、以下の情報に基づいて適切なアクションを実行するためのチェックを理解して実装する必要があります。
テスト用にこれらの各状態にアカウントを適切に設定するには、「サブスクリプション製品のテスト」を参照してください。
猶予期間
猶予期間は、有料サブスクリプションの ExpirationTime を過ぎている場合でも、ユーザーが引き続きサブスクリプションの特典を受けられる期間です。
この間、Microsoft Store は引き続きユーザーの支払い方法で自動更新を試みます。
これにより、ユーザーは必要に応じて期限切れのクレジット カードを解決したり、アカウントに資金を追加したりして、サブスクリプションの特典を失うことはありません。
支払い方法が修正され、自動更新トランザクションが完了すると、経過した猶予期間分がユーザーの次のサブスクリプション期間から減算されます。 例: サブスクリプションの期間は 30 日間で、ユーザーのアカウントは支払い方法が修正されている間に猶予期間に 3 日間費やしました。 自動更新トランザクションが成功すると、さらに 30 日間有効になります。 ただし、使用した 3 日間の猶予期間は新しい ExpirationTime から削除されるため、更新トランザクションから 27 日後にサブスクリプションの有効期限が切れます。 この結果、新しい ExpirationTime は以前の ExpirationTime から 30 日後となり、ユーザーは猶予期間に入ったため、無料の期間は得ませんでした。
猶予期間と催告期間の両方が同じ状態 (InDunning) を共有するため、サービスは現在の UTC 時刻を ExpirationTimeWithGrace 値と照合して、ユーザーが猶予期間にあるかどうかを判断する必要があります。
この間に、サブスクリプションの更新に問題がある可能性があることをユーザーに通知し、[Microsoft アカウント サービスとサブスクリプション] ページを確認するようにユーザーにメッセージを送信することもできます。
自動更新が ExpirationTimeWithGrace によって解決されない場合、アカウントは催告期間に入ります。
催告期間
催告期間は、ユーザーの猶予期間が切れた後に設定される時間であり、ユーザーはすでに自分のアカウントでサブスクリプションの特典を受け取れなくなります。 催告期間中、Microsoft Store は新しいサブスクリプション期間に対してユーザーのアカウントの課金を試みます。 課金が成功した場合、ユーザーの次のサブスクリプション期間から猶予期間がまるまる減算されます。
催告期間中、ユーザーはストアを通じてサブスクリプション自体で再購入または引き換えることができません。 これにより、ユーザーは猶予期間に入り、猶予期間が終了したときに新しいサブスクリプションを開始するだけでは、無料時間を取得できません。 催告期間は猶予期間よりもはるかに長い期間ですが、催告期間の終了時までに支払いが完了しない場合、サブスクリプションは非アクティブになります。
ユーザーのサブスクリプションの変更
これらのサービスを使って、ユーザーのサブスクリプションの状態を照会するだけでなく、ユーザーの代わりにユーザーのサブスクリプション製品を修正および変更することもできます。
purchase.mp.microsoft.com/v8.0/b2b/recurrences/{recurrenceId}/change エンドポイントを使用すると、サービスは特定のサブスクリプションへの時間の追加、キャンセル、払い戻し、自動更新の無効化を行うことができます。
Recurrence 変更エンドポイントを呼び出すには、まず、purchase.mp.microsoft.com/v8.0/b2b/recurrences/query エンドポイントから取得した recurrenceId 値が必要です。
Recurrence 変更エンドポイントをサービスで使用する方法の例を次に示します:
- サービスのダウンタイムが発生したユーザーのサブスクリプションに時間を追加する。
- カスタマー サービス サポート チームとの統合により、ユーザーにサブスクリプションの状態やキャンセルなどに関する情報を提供する。
- ゲーム内 UI で、ユーザーが自動更新を無効にしたり、サブスクリプションを終了したりすることを簡単に許可できるようにする。
サブスクリプション製品のテスト
Recurrence 変更エンドポイントは、サブスクリプション製品の開発とテストにも使用できます。
Extend 操作では、テスト アカウントのアクティブなサブスクリプションから減算する負の日数を受け付けます。
これにより、テスト アカウントをサブスクリプションにサブスクライブし、サブスクリプションから日数を削除して目的のテスト状態に到達できます。
アクティブ、非アクティブ、取り消し済みの状態のテスト
サブスクリプションのアクティブ状態、非アクティブ状態、キャンセル済み状態のテストは、0.00 ドルの価格に設定されたサブスクリプションで行うことができます。
サブスクリプションをテスト アカウントに追加してアクティブな状態を確認し、Recurrence 変更エンドポイントを使用して自動更新を無効にします。
次に、Recurrence 変更エンドポイントを使用して、サブスクリプションをキャンセルするか、ExpirationTime が現在の UTC DateTime を過ぎるまで日数を減算します。
猶予期間と催告期間の状態のテスト
サブスクリプション アカウントを猶予期間および 催告期間の状態にするには、サブスクリプションの価格が 0 以外である必要があります。また、アカウントは、ExpirationTime が経過したときにその金額を購入できない状態である必要があります。
現在、Microsoft Store にはテスト用の支払い方法がないため、アカウントを設定する最も簡単な方法は、次のようにプリペイド通貨コードを使用することです。
- テスト環境で$0.99 などの低価格ポイントでサブスクリプションを設定します。
- 1.00 ドルまたは 2.00 ドルで Xbox プリペイド ギフト カードを購入して、最初のサブスクリプション購入 (税別) をカバーしますが、更新は行いません。
- テスト アカウントでギフト カードを使います。
- テスト アカウントでサブスクリプションを購入します。
- サブスクリプションの自動更新が有効になっているが、サブスクリプションを更新するのに十分な資金がないことを確認します。
- Recurrence 変更を使用して、サブスクリプションの
ExpirationTimeを次の 24 時間以内に移動します (これが重要な理由については、以下の注を参照してください)。 -
ExpirationTimeが自然に経過するまで待機し、'InDunning' の状態を表示します (ExpirationTime後に最大 24 時間かかる場合があります)。
"猶予期間"、"催告期間"、"非アクティブ" へと適切な変化を確認するには、ExpirationTime を人為的に移動することなく、アカウントが自然にこれらの手順を実行できるようにする必要もあります。
注意
猶予期間と催告期間でアカウントを 'InDunning' 状態に適切に取得するには、アカウントが ExpirationTime と ExpirationTimeWithGrace の日付を自然に過ぎる必要があります。
テスト サブスクリプションから日数を減算する場合は、現在の UTC DateTime から次の 24 時間以内に ExpirationTime を得るのに十分なだけ減算します。
次に、アカウントが次の 24 時間でその DateTime を自然に経過し、状態が "InDunning" と表示されます。
ExpirationTime を現在の UTC DateTime より遠くに移動した場合、状態は 'InDunning' に変更されず、そのアカウント/サブスクリプションのテスト値は無効になります。
また、現在のサブスクリプション アイテムがキャンセルされ、アカウントで新しいサブスクリプションが購入されるまで、テスト アカウントは猶予期間と催告期間を適切にテストできない状態になります。
関連項目
purchase.mp.microsoft.com/v8.0/b2b/recurrences/query
purchase.mp.microsoft.com/v8.0/b2b/recurrences/{recurrenceId}/change