rc-backend

RevenueCat を使用したバックエンドアーキテクチャ

RevenueCat を使ってレシート検証サーバーを構築する必要はありません。バックエンドにも役割はありますが、それは RevenueCat の状態を利用することであり、Google Play の購入トークンを検証することではありません。

フェーズ 1：調査

RevenueCat のバックエンドがレシート検証サーバーです。Android SDK が購入トークンを送信すると、RevenueCat のバックエンドは次の処理を行います。

1. Google Play Developer API に対して purchases.subscriptionsv2.get または purchases.products.get を呼び出します。
2. レシートが正規のものであり、想定されるプロダクトと一致することを検証します。
3. トランザクションをデータベースに記録します。
4. SDK に CustomerInfo を返します。

Android アプリが Google Play Developer API を呼び出すことはありません。サーバーも呼び出しません。

バックエンドのコードを書く前に、デプロイ環境について次の点を確認してください。

• Android アプリを設定済みの RevenueCat プロジェクトがある。
• Project Settings の API Keys からシークレット API キーを取得している（アプリに埋め込む公開 Android SDK キーではありません）。
• SDK が使用する app_user_id（認証システムで使用するものと同じ識別子）がわかっている。
• バックエンドにリアルタイムの状態（REST API）とイベント駆動の状態（ウェブフック）のどちらが必要かを決めている。

アプリがクライアント内でのみ機能を制限する場合、バックエンドコンポーネントはまったく必要ない可能性があります。RevenueCat は CustomerInfo が SDK に届く前にサーバー側で検証し、EntitlementVerificationMode.INFORMATIONAL または .ENFORCED によってクライアント上で署名検証を追加できます。サーバー上でエンタイトルメントを検証できる場合にのみ、プレミアムコンテンツをサーバーから配信してください。

フェーズ 2：計画

バックエンドの各責務を RevenueCat の仕組みに対応付けます。

ユースケース	仕組み	備考
購入、更新、キャンセルへの対応	ウェブフックレシーバー	RevenueCat が正規化されたイベントを送信し、サーバーが独自の DB を更新します。
ユーザーの現在のエンタイトルメントの確認	GET /v1/subscribers/{app_user_id}	Authorization ヘッダーにシークレット API キーを指定します。
プロモーションアクセスの付与（サポート、返金、無償提供）	POST /v1/subscribers/{app_user_id}/entitlements/{entitlement_id}/promotional	サーバー側のみで実行します。
プロモーションアクセスの取り消し	POST /v1/subscribers/{app_user_id}/entitlements/{entitlement_id}/revoke_promotionals	サーバー側のみで実行します。
サーバー側のデータからサブスクライバー属性を設定	POST /v1/subscribers/{app_user_id}/attributes	SDK が認識しない CRM フィールドに便利です。
大量データのエクスポート	RevenueCat のデータエクスポート	ウェアハウスへの定期エクスポートです。

バックエンドが引き続き担うもの：

• ユーザー認証。
• ユーザーとそのアクセスレベルを管理するデータベース。
• プレミアムコンテンツを配信する API エンドポイント。
• RevenueCat イベントを処理するウェブフックレシーバー。

バックエンドが担わないもの：

• Google Play Developer API の認証情報。
• レシート検証コード。
• linkedPurchaseToken チェーンのたどり処理。
• 7 つのサブスクリプション状態にまたがるサブスクリプション状態の計算。

フェーズ 3：実行

サブスクライバーを読み取る

GET https://api.revenuecat.com/v1/subscribers/{app_user_id}
Authorization: Bearer sk_...
X-Platform: android

レスポンスボディは、Android SDK が返すものと同じ CustomerInfo 構造です。プレミアム API レスポンスを制限するサーバー側エンドポイントで使用してください。

プロモーションエンタイトルメントを付与する

POST https://api.revenuecat.com/v1/subscribers/{app_user_id}/entitlements/{entitlement_id}/promotional
Authorization: Bearer sk_...
Content-Type: application/json

{"duration": "monthly"}

duration の有効な値には daily、three_day、weekly、monthly、two_month、three_month、six_month、yearly、lifetime があります。サポートのワークフローで使用し、クライアントからは決して使用しないでください。

例：サーバーから Kotlin Ktor を呼び出す

val response = client.get("https://api.revenuecat.com/v1/subscribers/$appUserId") {
    header("Authorization", "Bearer ${System.getenv("RC_SECRET_KEY")}")
    header("X-Platform", "android")
}

API キーのルール

キー	保存場所	可能な操作
Android 公開 SDK キー	Android アプリに埋め込み	購入を送信し、現在のユーザーの CustomerInfo を取得します。
シークレット API キー	サーバーの環境変数のみ	任意のサブスクライバーの読み取り、プロモーションの付与または取り消し、属性の設定、一括操作を実行できます。

シークレットキーを Android APK、BuildConfig フィールド、またはクライアントバンドルに含めてはいけません。漏えいした場合はローテーションしてください。データベースのパスワードと同様に扱ってください。

Webhook 受信処理の概要

post("/revenuecat/webhook") {
    val auth = call.request.header("Authorization")
    require(auth == "Bearer ${System.getenv("RC_WEBHOOK_SECRET")}")
    val event = call.receive<RevenueCatEvent>()
    when (event.type) {
        "INITIAL_PURCHASE", "RENEWAL" -> grantAccess(event.appUserId, event.entitlements)
        "CANCELLATION", "EXPIRATION" -> scheduleRevocation(event.appUserId)
    }
    call.respond(HttpStatusCode.OK)
}

RevenueCat ダッシュボードで設定した認証ヘッダーを検証してください。すばやく 2xx を返してください。2xx 以外のレスポンスの場合、RevenueCat は再試行します。

実装しないこと

• Google Play のレシート検証エンドポイントは実装しないでください。RevenueCat がすでに検証しています。
• 手動で検証するために、Android クライアントからサーバーへ購入トークンを渡さないでください。往復処理は SDK が行います。
• SDK を使わないカスタム連携を構築する場合を除き、バックエンドから Google Play Developer API にクエリを送信しないでください。
• サブスクリプションの 7 つの状態からなるステートマシンをデータベースに複製しないでください。代わりに CustomerInfo.entitlements.active または Webhook イベントを利用してください。

参考資料

• 章全体