In-App Purchases

## When to Use User needs to implement in-app purchases, subscriptions, paywalls, or monetization flows. Agent handles native APIs (StoreKit 2, Google Play Billing), cross-platform SDKs (RevenueCat, Adapty, Qonversion), paywall design, server verification, and subscription analytics. ## Quick Reference | Topic | File | |-------|------| | iOS StoreKit 2 | `storekit.md` | | Android Billing | `google-play.md` | | Flutter packages | `flutter.md` | | RevenueCat SDK | `revenuecat.md` | | Platform comparison | `platforms.md` | | Server verification | `server.md` | | Paywall design | `paywalls.md` | | Subscription metrics | `analytics.md` | | Testing & sandbox | `testing.md` | ## Core Rules ### 1. Choose Your Architecture | Approach | When to Use | Tradeoff | |----------|-------------|----------| | Native only | Single platform, full control | More code, no cross-platform sync | | RevenueCat/Adapty | Cross-platform, fast launch | 1-2% fee, dependency | | Hybrid | Native + own backend | Full control, more work | ### 2. Platform SDKs (Managed) | Platform | Pricing | Best For | |----------|---------|----------| | RevenueCat | Free <$2.5k MTR, then 1% | Most apps, best docs | | Adapty | Free <$10k MTR, then 0.6% | Cost-conscious, A/B paywalls | | Qonversion | Free <$10k MTR, then 3% | Simple setup | | Superwall | Paywall-focused | Paywall A/B only | | Glassfy | Free <$10k, then 0.5% | Budget option | ### 3. Product Types | Type | iOS | Android | Use Case | |------|-----|---------|----------| | Consumable | ✅ | ✅ | Credits, coins, lives | | Non-consumable | ✅ | ✅ | Unlock feature forever | | Auto-renewable | ✅ | ✅ | Subscriptions | | Non-renewing | ✅ | ❌ | Season pass, time-limited | ### 4. Server Verification is Non-Negotiable Never trust client-side validation alone: - iOS: App Store Server API with JWS verification - Android: Google Play Developer API - RevenueCat: Webhooks + REST API ### 5. Handle All Transaction States | State | Action | |-------|--------| | Purchased | Verify → grant → finish | | Pending | Wait, show pending UI | | Failed | Show error, don't grant | | Deferred | Wait for parental approval | | Refunded | Revoke immediately | | Grace period | Limited access, prompt payment | | Billing retry | Maintain access during retry | ### 6. Subscription Lifecycle Events Must handle all of these (native or via webhooks): - INITIAL_PURCHASE → grant access - RENEWAL → extend access - CANCELLATION → mark will-expire - EXPIRATION → revoke access - BILLING_ISSUE → prompt to update payment - GRACE_PERIOD → limited access window - PRICE_INCREASE → consent required (iOS) - REFUND → revoke + flag user - UPGRADE/DOWNGRADE → prorate ### 7. Restore Purchases Always Required by App Store guidelines: - Prominent restore button - Works for logged-out users - Handles family sharing (iOS) - Cross-device sync ### 8. Paywall Best Practices See `paywalls.md` for detailed patterns: - Show value before price - Anchor pricing (3 options, highlight middle) - Free trial prominent - Social proof if available - A/B test everything ### 9. Testing Strategy | Environment | iOS | Android | |-------------|-----|---------| | Dev/Debug | StoreKit Config file | License testers | | Sandbox | Sandbox accounts | Internal testing | | Production | Real accounts | Production | Sandbox subscription times: - 1 week → 3 minutes - 1 month → 5 minutes - 1 year → 1 hour ### 10. App Store Guidelines - No external payment links (anti-steering) - Must use IAP for digital goods - Physical goods/services can use Stripe - Reader apps have exceptions - 15-30% commission applies ## Common Traps - Testing with real money → use sandbox/test accounts - Not finishing transactions → auto-refund (Android 3 days) - Hardcoding prices → always fetch from store (regional pricing) - Missing transaction observer → lose purchases made outside app - No server verification → trivially bypassable - Ignoring grace period → users churn when they could recover - Poor paywall UX → kills conversion regardless of price - Not tracking metrics → can't optimize what you don't measure - Forgetting restore button → App Store rejection - Not handling family sharing → confused users