rc-payment-recovery

支払いの復旧

Google Play で更新に失敗すると、サブスクリプションは 2 つの状態を経由します。猶予期間（Google がカードへの再請求を試みている間もユーザーはアクセスを維持できます）と、アカウント保留（ユーザーが支払い方法を修正するまでアクセスが取り消されます）です。RevenueCat では、どちらの状態も自動的に CustomerInfo に反映され、Google のアプリ内メッセージがデフォルトで表示されます。

フェーズ 1：理解する

更新に失敗すると、次の 3 つのことが起こります。

状態	アクセス	RevenueCat での表示方法	ユーザーに表示される内容
猶予期間	維持	entitlement.isActive == true かつ billingIssueDetectedAt != null	デフォルトでは Google のアプリ内スナックバー
アカウント保留	取り消し	entitlement.isActive == false かつ billingIssueDetectedAt != null	デフォルトでは Google のアプリ内スナックバー
復旧	維持	billingIssueDetectedAt == null	何も表示されません

SDK では、次の 2 つのシグナルが重要です。

• EntitlementInfo.billingIssueDetectedAt は、Google が請求の問題を報告した時点から、ユーザーが解決するまで null 以外の値になります。
• EntitlementInfo.isActive で、ユーザーが引き続きアクセスできるかどうかを確認できます。

バックエンドでは、状態が遷移するたびに BILLING_ISSUE ウェブフックが 1 回発火します。RTDN をデコードする必要はありません。

フェーズ 2：計画する

アプリのコードを書く前に、本当に必要なものを決めましょう。ほとんどのアプリでは、何もする必要はありません。

次の点を確認してください。

1. デフォルトの Google アプリ内メッセージを表示しますか？表示する場合は、何もする必要はありません。SDK は BillingClient の接続時に showInAppMessagesIfNeeded を呼び出します。
2. 独自のバナーやダイアログを表示しますか？表示する場合は、CustomerInfo から billingIssueDetectedAt を読み取り、isActive に応じて処理を分岐します。
3. 特定の画面でのみメッセージを表示しますか？表示する場合は、自動呼び出しを無効にし、独自に showInAppMessagesIfNeeded(activity) を呼び出します。
4. サーバー側のフラグ（たとえば、支払い復旧を促すメールを送信するためのもの）が必要ですか？必要な場合は、BILLING_ISSUE ウェブフックを処理します。アプリのコードは必要ありません。

デフォルトの動作だけでよい場合は、ここで終了です。

フェーズ 3：実行する

デフォルト（推奨）

アプリ内メッセージの自動表示を有効にしたままにします。これはデフォルトの設定です。

PurchasesConfiguration.Builder(context, apiKey)
    .showInAppMessagesAutomatically(true)
    .build()

手動で呼び出す

自動呼び出しを無効にし、選択したアクティビティからメッセージを表示します。

PurchasesConfiguration.Builder(context, apiKey)
    .showInAppMessagesAutomatically(false)
    .build()

Purchases.sharedInstance.showInAppMessagesIfNeeded(activity)

猶予期間中に独自の UI を表示する

エンタイトルメントを読み取り、両方のフラグに応じて処理を分岐します。

val entitlement = customerInfo.entitlements["pro_access"]
when {
    entitlement == null || !entitlement.isActive ->
        showSubscribeScreen()
    entitlement.billingIssueDetectedAt != null && entitlement.isActive ->
        showGracePeriodWarning()
    entitlement.billingIssueDetectedAt != null && !entitlement.isActive ->
        showAccountHoldScreen()
    else ->
        showPremiumContent()
}

ユーザーを支払い方法の修正画面に誘導する

CustomerInfo.managementURL は Google Play のサブスクリプションページを示します。

customerInfo.managementURL?.let { url ->
    startActivity(Intent(Intent.ACTION_VIEW, url))
}

フェーズ 4：検証する

各状態遷移をテストします。

• 更新が拒否される Google Play テストカードを使い、サブスクリプションを猶予期間に移行させます。
• entitlement.billingIssueDetectedAt が null 以外の値になり、isActive が true のままであることを確認します。
• アカウント保留になるまで待ち、billingIssueDetectedAt が null 以外のまま、isActive が false に変わることを確認します。
• 支払い方法を更新し、billingIssueDetectedAt が null に戻ることを確認します。
• バックエンドで、最初の状態遷移時に BILLING_ISSUE ウェブフックが発火することを確認します。

参考資料

• 章全体