rc-understanding-revenuecat

RevenueCat を理解する

フェーズ 0：目的

RevenueCat のコードを書く前に、このスキルを使ってください。後続のスキル（セットアップ、設定、購入フロー、エンタイトルメント）を理解するために必要な用語と考え方を説明します。

次のいずれかに当てはまる場合は、ここから始めてください。

• RevenueCat を初めて使う方、または生の Play Billing 統合から移行する方。
• どの概念がダッシュボードのどの項目に対応するのか分からない方。
• ユーザーの具体的な目的に応じて、どの後続スキルを呼び出すべきか判断する必要がある方。

Offering、Package、Product、Entitlement の違いをすでに理解しており、Purchases.sharedInstance が唯一のエントリーポイントであることも知っている場合は、このスキルをスキップしてください。

フェーズ 1：全体像を把握する

Android のアプリ内購入を生のまま実装するには、3 つのシステムが個別に必要です。RevenueCat はこの 3 つすべてを、1 つの SDK と 1 つのダッシュボードにまとめます。

生の Google Play スタック	RevenueCat による代替	配置場所
クライアント上の BillingClient	Purchases SDK	Android アプリ
サーバー上の Google Play Developer API	RevenueCat バックエンド	RevenueCat が管理
Cloud Pub/Sub 経由の Real Time Developer Notifications	RevenueCat のウェブフック	RevenueCat が管理し、サーバーに配信

呼び出し経路は次のとおりです。

Your App
  -> Purchases SDK
  -> RevenueCat Backend
  -> Google Play Developer API
  -> Google Play

アプリは Purchases SDK と通信します。SDK は購入 UI のために Google Play と通信し、検証とエンタイトルメントの保存のために RevenueCat バックエンドと通信します。サーバー側のコードは Google Play ではなく、RevenueCat バックエンドと通信します。

その結果、RevenueCat は購入検証の経路に入ります。ユーザーが購入を完了すると、アプリに確認が届く前に SDK がトークンを RevenueCat に送信します。自分でサーバー側の検証を構築する必要がなくなる代わりに、ネットワークの往復が発生します。

知っておくべき 4 つの概念

概念	内容	定義場所
Product	サブスクリプション、基本プラン、または買い切り購入	Google Play Console
Package	種類を示すラベル（月額、年額、ライフタイム、カスタム）を付けた Product。ペイウォールに表示する単位	RevenueCat ダッシュボード
Offering	Package のグループ。1 つの Offering が Current として設定され、offerings.current から返されます	RevenueCat ダッシュボード
Entitlement	アプリが確認する論理的なアクセスレベル（例："pro_access"）。Product は Entitlement に紐付けます	RevenueCat ダッシュボード

CustomerInfo は、ユーザーの購入履歴と有効な Entitlement を実行時に表すスナップショットで、RevenueCat が計算してキャッシュします。

ほとんどの場合に必要な、2 つの読み取り

val offerings = Purchases.sharedInstance.awaitOfferings()
val monthly = offerings.current?.monthly

val customerInfo = Purchases.sharedInstance.awaitCustomerInfo()
val hasPro = customerInfo.entitlements["pro_access"]?.isActive == true

isActive は、7 種類の Play サブスクリプション状態（ACTIVE、IN_GRACE_PERIOD、ON_HOLD、PAUSED、CANCELED、EXPIRED、PENDING）をすでにサーバー側で解決します。クライアント側でこのロジックを再実装する必要はありません。

シングルトン

Purchases.sharedInstance が唯一のエントリーポイントです。アプリの起動時に一度設定します。

Purchases.configure(
    PurchasesConfiguration.Builder(context, "your_api_key")
        .appUserID("optional_user_id")
        .build()
)

BillingClient とは異なり、シングルトンでは接続状態を管理する必要がありません。再接続し、呼び出しをキューに入れる処理も担います。

RevenueCat が代替しないもの

• Google Play Console。Product、基本プラン、オファーは引き続きここで作成します。
• アプリの UI。引き続きペイウォールを構築し、価格を表示します。RevenueCat はデータを提供します。
• 認証システム。ユーザー ID はご自身で用意し、SDK に渡します。

トレードオフ

検証の複雑さを委ねる代わりに、依存関係が増えます。RevenueCat バックエンドが停止すると、購入検証に影響します。対策は 2 つありますが、それぞれ異なるものです。

機能	内容	適用されるタイミング
CustomerInfo のディスクキャッシュ	エンタイトルメントの確認時に、最後に取得したサーバー状態を返します	自動。常に有効
Offline Entitlements	ローカルの Play ストア購入情報から、デバイス上でエンタイトルメントを計算します	明示的に設定した場合のみ

どちらも、バックエンドに接続できることの完全な代替にはなりません。該当する場合は、両方を使用してください。

フェーズ 2：ユーザーの目的を下流のスキルに対応付ける

上記のモデルを把握したら、ユーザーが実際に何をしたいのかに応じて、次のスキルを選びます。

ユーザーの目的	次のスキル
SDK をインストールし、Gradle を設定し、権限を追加して、Play Console の商品を設定する	rc-setup
Purchases.configure を呼び出し、appUserID を渡し、ログレベルを設定して、属性を追加する	rc-configuring-the-sdk
Offerings を取得し、ペイウォールを表示し、purchase を呼び出して、結果を処理する	rc-purchase-flow
customerInfo.entitlements["..."]?.isActive を確認し、機能を制限し、更新を監視する	revenuecat/entitlements-and-customerinfo
ユーザーを識別、エイリアス設定、またはログアウトする	revenuecat/user-identity
購入の復元、デバイス間での利用、プロモーションコードを処理する	revenuecat/restore-and-recovery
RevenueCat からサーバー側イベントを受信する	rc-webhooks
本番環境で特定の購入、レシート、またはエンタイトルメントをデバッグする	revenuecat/debugging

ユーザーの目的がどの行にも当てはまらない場合は、ここにとどまり、振り分ける前に意図を確認し続けます。

フェーズ 3：整合性の確認

このスキルを離れて下流のスキルに振り分ける前に、次の点を声に出して確認します。

1. ユーザーの質問が、3 つの基盤要素（クライアント課金、サーバーの Play Developer API、RTDN）のどれに関係するかを説明できます。
2. ユーザーが Product、Package、Offering、Entitlement のどれについて質問しているかを説明できます。これらは互換性のあるものではありません。
3. ユーザーに必要なのが Offerings（販売するもの）か、CustomerInfo（ユーザーがすでに所有しているもの）かを把握しています。混乱の大半は、この 2 つを混同することから生じます。
4. 次に呼び出す下流のスキルを 1 つだけ選んでいるか、具体的な確認質問を用意しています。

4 つの項目のいずれかを満たしていない場合は、先に進む前にフェーズ 1 または該当する章を読み直してください。

参考資料

• 章全体