Payments

RevenueCat integration

The Flutter template uses:

• purchases_flutter
• purchases_ui_flutter

The service boundary is services/revenuecat_service.dart; pages should use monetizationProvider rather than calling the SDK directly.

Build-time configuration

Public RevenueCat SDK keys are passed with Dart defines:

flutter run \
  --dart-define=REVENUECAT_ANDROID_API_KEY=goog_xxxxx

flutter build appbundle --release \
  --dart-define=REVENUECAT_ANDROID_API_KEY=goog_xxxxx

Use REVENUECAT_IOS_API_KEY for iOS. The config also supports BILLING_ENABLED, BILLING_PAGE_ENABLED, ONBOARDING_PAYWALL_ENABLED, and ONBOARDING_PAYWALL_SKIPPABLE.

Current identifiers:

• Entitlement: Bowlerplate Pro
• Lifetime product: bowlerplate_pro_lifetime
• Yearly product: bowlerplate_pro_yearly
• Monthly product: bowlerplate_pro_monthly

Create matching products/entitlement in RevenueCat before release.

Runtime behavior

• Account configures RevenueCat with the authenticated backend UUID and refreshes server entitlements from GET /api/v1/app/billing/entitlements.
• Guest configures an anonymous RevenueCat customer and never asks BowlerKit for server entitlements.
• Paywall, restore purchases, customer center, and entitlement gates run on native iOS/Android when public keys are available.
• Store purchase/restore actions require internet access even in Guest mode.

Use PremiumAccess.require(ref) for feature gates and presentPaywallIfNeeded() for the existing paywall flow. Keep entitlement identifiers stable; changing them requires a RevenueCat migration.

AdMob integration

The generated Flutter app also initializes google_mobile_ads for both profiles. Development native configuration and the banner widget use Google's test app/ad-unit IDs. Replace the test IDs in android/app/src/main/AndroidManifest.xml, ios/Runner/Info.plist, and widgets/test_banner_ad.dart only after consent, policy, and release IDs are ready. Ad loading failures should not block startup.

Release checklist

1. Configure store products and Bowlerplate Pro in RevenueCat.
2. Pass platform-specific public SDK keys through your build pipeline.
3. Decide whether ads are enabled, configure consent, and replace every Google test app/ad-unit ID before release.
4. Configure store signing/tester accounts.
5. Test Account UUID association, Guest anonymous purchases, restore, logout/login, backend entitlement fallback, ad no-fill, and offline/error states.
6. Build a native release-like artifact; web/desktop runs do not exercise native billing/ads.

Relevant files

• config/monetization_config.dart
• services/revenuecat_service.dart
• providers/monetization_provider.dart
• services/billing_entitlement_service.dart
• pages/billing/page.dart