rc-revenuecat-api-quick-reference

RevenueCat API クイックリファレンス

Phase 0: 意図

Android コードやサーバーのロジックを記述する際に、RevenueCat API の仕様をすばやく確認する必要がある場合に、このスキルを使用してください。ここでは、次のような質問への答えを確認できます。

• 特定の Purchases.configure の動作を制御するビルダーオプションはどれですか？
• awaitPurchase、awaitOfferings、awaitCustomerInfo、awaitRestore、awaitLogIn、awaitLogOut の戻り値の型とシグネチャは何ですか？
• Offering、Package、Product、Entitlement の各フィールドをどのように読み取りますか？
• どの PurchasesErrorCode に応じて処理を分岐すべきですか？
• Customer Info の更新を受け取るには、どのリスナーコールバックを登録しますか？

このスキルを詳しいチュートリアルとして使用しないでください。手順ごとのガイダンスや設計上の根拠が必要な場合は、機能別のスキル（購入フロー、SDK の設定、エラー処理、サブスクリプションの状態）を参照してください。

Phase 1: 検索先

表を検索する前に、SDK と REST のどちらを使うか決めてください。

SDK を使用する場合（クライアント側、Android アプリのコード）：

• コードは Android アプリ内の Activity、ViewModel、またはアプリにバンドルされたバックグラウンドワーカーで実行されます。
• 購入の開始、購入の復元、キャッシュされた CustomerInfo の読み取り、Offerings の取得、ユーザーの識別またはログアウト、更新のリスニングが必要です。
• UI で Entitlement に基づくアクセス制御を行います。

REST API を使用する場合（サーバー側）：

• コードはバックエンド、Webhook ハンドラー、管理ツール、またはスケジュールされたジョブで実行されます。
• プロモーション Entitlement の付与または取り消し、サブスクリプションの上書き、別のサービスからの購入者情報の検索、返金、別のシステムへのイベント配信が必要です。
• SDK を組み込めないシステムと連携しています。

このスキルの表には、付録 A の Android SDK 10.x の仕様がそのまま記載されています。REST エンドポイントのパス、認証、ペイロードについては、revenuecat.com の付録全文とバックエンドおよび Webhook のスキルを参照し、このファイルは SDK の索引として使用してください。

Phase 2: リファレンス表

SDK の初期化

// Minimum setup
Purchases.configure(
    PurchasesConfiguration.Builder(context, "api_key").build()
)

// Full options
Purchases.configure(
    PurchasesConfiguration.Builder(context, "api_key")
        .appUserID("user_id")                    // null for anonymous
        .showInAppMessagesAutomatically(true)    // default: true
        .purchasesAreCompletedBy(PurchasesAreCompletedBy.REVENUECAT) // default
        .entitlementVerificationMode(EntitlementVerificationMode.INFORMATIONAL)
        .diagnosticsEnabled(false)               // default: false
        .pendingTransactionsForPrepaidPlansEnabled(false) // default: false
        .build()
)

Purchases.logLevel = LogLevel.DEBUG // before configure()

主な操作（コルーチン）

// Fetch offerings
val offerings: Offerings = Purchases.sharedInstance.awaitOfferings()

// Fetch specific products
val products: List<StoreProduct> = Purchases.sharedInstance.awaitGetProducts(
    listOf("product_id"),
    type = ProductType.INAPP // or SUBS, or null for all
)

// Purchase
val result: PurchaseResult = Purchases.sharedInstance.awaitPurchase(
    PurchaseParams.Builder(activity, packageOrStoreProductOrSubscriptionOption).build()
)

// Purchase upgrade/downgrade
val result = Purchases.sharedInstance.awaitPurchase(
    PurchaseParams.Builder(activity, newPackage)
        .oldProductId("old_product_id")
        .googleReplacementMode(GoogleReplacementMode.WITH_TIME_PRORATION)
        .build()
)

// Get customer info
val customerInfo: CustomerInfo = Purchases.sharedInstance.awaitCustomerInfo()
val fresh: CustomerInfo = Purchases.sharedInstance.awaitCustomerInfo(
    fetchPolicy = CacheFetchPolicy.FETCH_CURRENT
)

// Restore
val customerInfo: CustomerInfo = Purchases.sharedInstance.awaitRestore()

// Log in / log out
val loginResult: LogInResult = Purchases.sharedInstance.awaitLogIn("user_id")
// loginResult.customerInfo, loginResult.created (Boolean)
val customerInfo: CustomerInfo = Purchases.sharedInstance.awaitLogOut()

Offerings の構造

val offerings: Offerings
offerings.current          // current Offering
offerings.all              // Map<String, Offering>
offerings["my_offering"]   // by identifier
offerings.getCurrentOfferingForPlacement("placement_id") // targeting

val offering: Offering
offering.identifier
offering.monthly           // Package? (shortcut)
offering.annual            // Package?
offering.weekly            // Package?
offering.availablePackages // List<Package>
offering.metadata          // Map<String, Any>

val pkg: Package
pkg.identifier             // "$rc_monthly", "$rc_annual", custom
pkg.packageType            // PackageType enum
pkg.product                // StoreProduct
pkg.webCheckoutURL         // URL? (RevenueCat web billing)

val product: StoreProduct
product.productId
product.title
product.description
product.price.formatted    // "$4.99"
product.price.amountMicros
product.price.currencyCode
product.period             // Period? (null for INAPP); use period.iso8601 for "P1M", "P1Y", etc.
product.subscriptionOptions // List<SubscriptionOption>? (null for INAPP)
product.defaultOption       // SubscriptionOption? best available offer

Entitlements

val customerInfo: CustomerInfo
customerInfo.entitlements.active         // Map<String, EntitlementInfo> (active only)
customerInfo.entitlements.all            // Map<String, EntitlementInfo> (all)
customerInfo.entitlements["pro_access"]  // EntitlementInfo?
customerInfo.activeSubscriptions         // Set<String> of "productId:basePlanId"
customerInfo.nonSubscriptionTransactions // List<Transaction>
customerInfo.managementURL               // Uri? to Play Store management

val entitlement: EntitlementInfo
entitlement.isActive                     // Boolean, the main access gate
entitlement.willRenew                    // false if canceled
entitlement.expirationDate               // Date? (null for lifetime)
entitlement.periodType                   // NORMAL, TRIAL, INTRO, PREPAID
entitlement.billingIssueDetectedAt       // Date? (non-null = grace/hold)
entitlement.unsubscribeDetectedAt        // Date? (non-null = canceled)
entitlement.store                        // PLAY_STORE, APP_STORE, etc.
entitlement.productIdentifier            // subscription product ID
entitlement.productPlanIdentifier        // base plan ID (Google only)
entitlement.verification                 // VerificationResult

エラー処理

// Purchase errors
try {
    Purchases.sharedInstance.awaitPurchase(params)
} catch (e: PurchasesTransactionException) {
    e.userCancelled     // Boolean
    e.error.code        // PurchasesErrorCode
    e.error.message     // description string
}

// Other errors
try {
    Purchases.sharedInstance.awaitOfferings()
} catch (e: PurchasesException) {
    e.error.code        // PurchasesErrorCode
}

// Key error codes
PurchasesErrorCode.PurchaseCancelledError
PurchasesErrorCode.ProductAlreadyPurchasedError
PurchasesErrorCode.PaymentPendingError
PurchasesErrorCode.NetworkError
PurchasesErrorCode.StoreProblemError
PurchasesErrorCode.IneligibleError
PurchasesErrorCode.ConfigurationError

リスナー

// CustomerInfo updates
Purchases.sharedInstance.updatedCustomerInfoListener =
    UpdatedCustomerInfoListener { customerInfo -> }

// Show in-app messages manually
Purchases.sharedInstance.showInAppMessagesIfNeeded(activity)

Phase 3: 典型的なコード例

Entitlement に基づいて機能へのアクセスを制御します。

val info = Purchases.sharedInstance.awaitCustomerInfo()
val hasPro = info.entitlements["pro_access"]?.isActive == true
if (hasPro) unlockFeature() else showPaywall()

現在の Offering から月額 Package を購入します。

val current = Purchases.sharedInstance.awaitOfferings().current ?: return
val monthly = current.monthly ?: return
val result = Purchases.sharedInstance.awaitPurchase(
    PurchaseParams.Builder(activity, monthly).build()
)

キャンセルと実際の失敗を区別して処理します。

try {
    Purchases.sharedInstance.awaitPurchase(params)
} catch (e: PurchasesTransactionException) {
    if (e.userCancelled) return
    when (e.error.code) {
        PurchasesErrorCode.PaymentPendingError -> showPendingUi()
        PurchasesErrorCode.NetworkError -> showRetry()
        else -> showGenericError(e.error.message)
    }
}

サーバー側で付与した後、最新の CustomerInfo を強制的に取得します。

val fresh = Purchases.sharedInstance.awaitCustomerInfo(
    fetchPolicy = CacheFetchPolicy.FETCH_CURRENT
)

識別済みユーザーとしてログインし、初回ログインかどうかを判定します。

val login = Purchases.sharedInstance.awaitLogIn("user_123")
val isNewAlias = login.created
val info = login.customerInfo

バックグラウンドでの Entitlement の変更に対応します。

Purchases.sharedInstance.updatedCustomerInfoListener =
    UpdatedCustomerInfoListener { info ->
        val active = info.entitlements["pro_access"]?.isActive == true
        uiState.update { it.copy(hasPro = active) }
    }

参考資料

• 章の全文

• このリポジトリ内の関連スキル：rc-configuring-the-sdk、rc-purchase-flow、rc-error-handling、rc-subscription-states、rc-backend、rc-webhooks。