integrating-revenuecat

RevenueCat (Flutter) Latest Version Best Practices Guide (v10.x)

Goal

RevenueCat is the industry-standard solution for handling In-App Purchases (IAP) and subscriptions in mobile applications. In Flutter, the official package is purchases_flutter (paired with purchases_ui_flutter for pre-built paywall UI).

Instructions

1. Core Concept: Entitlements > Products

In traditional IAP development, developers often focus on "which Product ID the user purchased." RevenueCat's best practice is: Always check the user's Entitlements.

• Products: The actual items configured in Apple/Google consoles (e.g., monthly_sub_199).
• Offerings: RevenueCat packages multiple Products into a display offering (e.g., a default offering contains "Monthly" and "Annual" subscriptions). This makes A/B testing extremely easy, allowing you to swap products without changing the APP code.
• Entitlements: The ultimate goal unlocked after a user purchases (e.g., pro_access).

👉 Your APP logic should ALWAYS only check if pro_access is active. Do not care about which offering the user bought to get it.

2. Dependencies and Initialization Setup

2.1 Install Packages

dependencies:
  purchases_flutter: ^10.0.1
  # 🌟 Highly Recommended: Use the official native UI checkout templates (Paywalls) to reduce the pain of building your own UI
  purchases_ui_flutter: ^10.0.1 

2.2 Platform Specific Configurations (Extremely Important)

• Android (AndroidManifest.xml): Be sure to set the main Activity's launchMode to singleTask or singleTop. Otherwise, unexpected behaviors like canceled purchases might occur when the user switches back from the Google Play payment screen.
• iOS: Ensure Xcode 14.0+, and the deployment target is generally recommended to be iOS 13.0+.

2.3 Initialization (On App Startup)

Complete the initialization as early as possible, either in main() or before the App UI renders.

import 'dart:io';
import 'package:flutter/foundation.dart';
import 'package:purchases_flutter/purchases_flutter.dart';

Future<void> initPlatformState() async {
  await Purchases.setLogLevel(kDebugMode ? LogLevel.debug : LogLevel.info);

  PurchasesConfiguration? configuration;
  if (Platform.isAndroid) {
    // Android natively uses a Builder underneath; just provide the API Key in Flutter
    configuration = PurchasesConfiguration('goog_api_key_here');
  } else if (Platform.isIOS) {
    configuration = PurchasesConfiguration('appl_api_key_here')
      // 🌟 v7+ Best Practice: Explicitly define StoreKit version (defaults to auto-select, but StoreKit 2 requires In-App Purchase Key configurations in your RevenueCat Dashboard)
      ..storeKitVersion = StoreKitVersion.storeKit2; 
  }
  
  if (configuration != null) {
    // 🌟 Best Practice: Pass your own user ID here to help RevenueCat sync across devices.
    // configuration.appUserID = "my_app_user_id";

    // ⚠️ Deprecation Notice: "Observer Mode" is now legacy. If your App fundamentally completes its own transactions (instead of RevenueCat), deploy:
    // configuration.purchasesAreCompletedBy = PurchasesAreCompletedByMyApp(storeKitVersion: StoreKitVersion.storeKit2);

    await Purchases.configure(configuration);
  }
}