Kmp Starter Feature Purchases

Purchases (RevenueCat)

Subscriptions, one-time purchases, dynamic paywalls, and remote metadata via RevenueCat. Clean Architecture, fully integrated with Analytics and Navigation.

Where things live

1. Setup RevenueCat

Add API keys in composeApp/.../core/AppConstants.kt (debug/prod split, Android vs iOS):

object AppConstants {
    private const val RC_TEST_STORE_API_KEY = "test_api_key"

    private val RC_PROD_API_KEY = when (platform) {
        is Platform.Android -> "goog_android_api_key"
        is Platform.Ios -> "apple_api_key"
    }

    val REVENUE_CAT_API_KEY =
        if (platform.debug) RC_TEST_STORE_API_KEY else RC_PROD_API_KEY
}

In the RevenueCat dashboard: create products (weekly/yearly/...), create an Offering (make it default), and add Store Listing Metadata (FAQs, reviews, paywall version, product titles/descriptions/badges/discount labels).

2. Check entitlement (Compose)

val isPro = rememberIsProUser()              // Boolean — any active entitlement
val products = rememberActiveProducts().value // List<Product> — active products

if (!isPro) AdBanner()

rememberIsProUser() = rememberActiveProducts().value.isNotEmpty().

3. Navigate to the paywall

Navigate to AppScreens.Purchases — registered in composeApp/src/commonMain/kotlin/<your-package>/core/navigation/AppScreens.kt (e.g. data object Purchases : AppScreens()). Do not invent StarterScreens.Purchases.

navigator.navigateTo(AppScreens.Purchases)

The screen auto-handles: loading products, starting purchase, restoring purchases, loading discount product, loading paywall metadata, and showing the discount dialog.

4. Customize the paywall

composeApp/src/commonMain/kotlin/<your-package>/core/navigation/StarterPaywallDefaults.kt is the single place to edit paywall strings, hero image, and feature list:

• starterDefaultPaywallV1() — builds Paywalls.V1 from Res.string.paywall_v1_* + Res.drawable.*.
• starterDefaultPaywallV1Features() — the List<PurchaseFeature> (icon + string) shown.
• Swap the referenced Res.string.paywall_v1_* / drawable for your own resources (see resources-theme skill; regenerate accessors with :features:resources:generateAccessors).

5. Paywall metadata — publish/purchases.json

publish/purchases.json is the source you update for your project's RevenueCat offering metadata. RevenueCatPurchasesRepository reads these keys from the current offering, decoded against the domain models:

• paywall_meta_data → PaywallMetadata (faqs, reviews, version). GetPaywallMetadataLogic feeds PurchasesViewModel.
• products_meta_data → per-product metadata keyed by store product id (title, description, badge, badgeBg, discountPercentage, isTrial), decoded into Product/ProductBadge.
• discountOffer → identifier of the discount offering (maps to DISCOUNT_OFFER_IDENTIFIER_KEY).
• Product ids in products_meta_data must match your Google Play / App Store SKUs (e.g. kmp_pro.weekly, kmp_pro.yearly).

So: edit publish/purchases.json to reflect your products/FAQs/reviews, then mirror that JSON into the RevenueCat offering's metadata. %price% placeholders are formatted via Product.formatValues().

Example:

{
  "discountOffer": "kmp_starter_early_bird_discount",
  "paywall_meta_data": {
    "version": 1,
    "faqs": [
      { "question": "Does it support Android & iOS?", "answer": "Yes, fully shared KMP setup." }
    ],
    "reviews": [
      { "author": "Alex", "rating": 5.0, "review": "Saved weeks of setup time." }
    ]
  },
  "products_meta_data": {
    "kmp_pro.weekly": { "title": "Weekly Pro", "description": "Full access for %price%.", "badge": null },
    "kmp_pro.yearly": { "title": "Yearly Pro", "description": "Best value for %price%.", "badge": "Save 50%" }
  }
}

6. Custom ViewModel — PurchasesLogics

If you don't want PurchasesViewModel, inject PurchasesLogics and build your own VM. It bundles:

• getProducts, startPurchase, restorePurchases, getPaywallMetadata, getCurrentPurchaseStatus, getDiscountProduct, signInToPurchase

Call signIn(userId) (via SignInToPurchaseLogic) right after the user logs in so entitlements are tied to the account and restorable across devices.

7. Pro-gating — recommend what to lock

When planning a paid tier, look at the app and recommend features that can be Pro-gated. Keep the core experience free; gate the power/advanced features that only engaged users want.

Heuristics:

• Free (core): the primary value — the thing that gets a user hooked and makes the app usable on day one.
• Pro (gate): advanced controls, higher limits, power features, saving/export, customization, and any feature users "level up" into.

Example — a web-to-PDF app gates: extra page sizes (A3/A2/A1/A0), custom margins, custom CSS/JS, orientation, image/JS/cache/user-agent web settings, char + bookmark limits. The basic A4 convert stays free.

Only implement pro-gating when the user asks. When they do, propose the split first (free vs Pro), get agreement, then implement.