vie_revenue_cat 1.0.0

A production-grade, highly extensible RevenueCat & Hybrid In-App Purchase Manager for Flutter. Effortlessly handles Native RevenueCat Paywalls (purchases_ui_flutter), custom local Flutter paywalls, dy [...]

Vie RevenueCat (vie_revenue_cat)

A production-grade, highly extensible RevenueCat & Hybrid In-App Purchase Manager for Flutter.

Effortlessly manage Native RevenueCat Paywalls (purchases_ui_flutter), custom Local Flutter Paywalls, dynamic Firebase Remote Config Routing, reactive entitlement state management, and seamless feature gating across multiple applications.

---

🌟 Key Features

• 🚀 Hybrid Paywall Routing: Dynamically switch between Native RevenueCat Paywalls and Local Flutter Dialogs per screen using Firebase Remote Config.
• ⚡ Reactive Pro State: Instant GetX reactivity (isPro.value, activeEntitlement, customerInfo).
• 🛡️ Clean Dismissal Lifecycle: Native paywall dismissals (X button) close gracefully without secondary popups or error toasts.
• 🔒 Feature Gating (PremiumGate): Gate any button, function, or screen with a single line of code (PremiumGate.checkAccess()).
• 🎨 Built-in Pro UI Widgets:
  • PremiumBuilder: Render different widgets for Pro vs Free users.
  • ProBadge: Customizable, auto-hiding "PRO" / "VIP" badge with gradients and animations.
  • ProGateWrapper: Intercept clicks and show paywalls automatically with optional lock overlays.
• 🔄 Auto-Restores & Status Syncing: Built-in receipt validation, user logIn/logOut, and restore purchases workflows.
• 📦 Zero App Bloat for Ad-Only Apps: Completely decoupled from ad managers.

---

📦 Installation

Add vie_revenue_cat to your app's pubspec.yaml:

dependencies:
  vie_revenue_cat:
    path: ../Package/revnuecat_package # Local path or git repository

---

🚀 Quick Start

1. Initialize RevenueCatManager

Call RevenueCatManager.instance.init() in your main() function or AppBinding:

import 'package:get/get.dart';
import 'package:vie_revenue_cat/vie_revenue_cat.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Register singleton
  Get.put(RevenueCatManager());

  // Initialize
  await RevenueCatManager.instance.init(
    config: const RevenueCatConfig(
      appleApiKey: 'appl_YOUR_APPLE_PUBLIC_KEY',
      googleApiKey: 'goog_YOUR_GOOGLE_PUBLIC_KEY',
      entitlementId: 'pro',
      logLevel: LogLevel.debug,
    ),

    // 1. Dynamic Remote Config Router (Optional)
    remoteConfigResolver: (screenContext) {
      // Return 'rc', 'rc:promo_offering', or '5' based on Remote Config
      return FirebaseRemoteConfig.instance.getString('sub_$screenContext');
    },

    // 2. Local Paywall Builder (Optional fallback)
    localPaywallBuilder: (routeKey) {
      if (routeKey == '5') return const OneDaySubscriptionScreen();
      if (routeKey == '6') return const OneDaySubscriptionVariantTwoScreen();
      return const DefaultSubscriptionScreen();
    },

    // 3. Status Change Callback (Optional)
    onProStatusChanged: (isPro) {
      debugPrint('Pro status changed: $isPro');
    },
  );

  runApp(const MyApp());
}

---

🛠️ Usage Guide

1. Presenting Paywalls Dynamically

To show the appropriate paywall based on your screen context and Remote Config:

// Opens RevenueCat Native UI or your Local Panel automatically!
RevenueCatManager.instance.showPaywall(screenContext: 'home');

Remote Config Route Syntax:

Remote Config Value	Result
rc or 7	Opens default/current Native RevenueCat Paywall
rc:summer_sale	Opens Native RevenueCat Paywall with offering summer_sale
5	Opens your custom local Flutter Panel 5 via localPaywallBuilder
none / free	Does not show paywall (feature is free)

---

2. Feature Gating with PremiumGate

Protect features and actions behind a subscription with a single call:

ElevatedButton(
  onPressed: () {
    PremiumGate.checkAccess(
      screenContext: 'tools',
      onAllowed: () {
        // This code executes immediately if Pro,
        // OR after the user successfully subscribes!
        exportHighResPdf();
      },
    );
  },
  child: const Text('Export 4K PDF'),
)

---

3. Reactive UI Widgets

PremiumBuilder (Conditional UI)

PremiumBuilder(
  proBuilder: (context) => const Text('⭐ Pro Member Active'),
  freeBuilder: (context) => ElevatedButton(
    onPressed: () => RevenueCatManager.instance.showPaywall(),
    child: const Text('Upgrade to Pro'),
  ),
)

ProBadge (Auto-hiding Badge)

// Automatically disappears when user subscribes!
const ProBadge(
  label: 'VIP PRO',
  fontSize: 10,
)

ProGateWrapper (Click Interceptor & Lock Overlay)

ProGateWrapper(
  showLockOverlay: true,
  screenContext: 'ai_editor',
  onTap: () => startAiEditing(),
  child: const ToolTile(title: 'AI Magic Eraser'),
)

---

4. Restore Purchases

ElevatedButton(
  onPressed: () => RevenueCatManager.instance.restorePurchases(),
  child: const Text('Restore Purchases'),
)

---

5. Bridging with vie_app_ads_manager

Hide ads immediately when the user is Pro:

// Listen to pro status in your AppBinding
ever(RevenueCatManager.instance.isPro, (bool isPro) {
  if (isPro) {
    AdsRemoteServices.to.subscription.value = true;
  }
});

---

🧪 Running Tests

cd revnuecat_package
flutter test

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.