diff --git a/PRD.md b/PRD.md index 37cc424..e301d23 100644 --- a/PRD.md +++ b/PRD.md @@ -44,6 +44,7 @@ SelfieCam is a professional-grade selfie camera app featuring a customizable scr 1. **Protocol-Oriented Programming (POP)** - All shared capabilities defined via protocols before concrete types 2. **MVVM-lite** - Views are "dumb" renderers; all logic lives in `@Observable` view models 3. **Bedrock Design System** - Centralized design tokens, no magic numbers + - Settings layout contract: `SettingsCard` owns horizontal insets, custom rows use `SettingsCardRow`, and in-card separators use `SettingsDivider` 4. **Full Accessibility** - Dynamic Type, VoiceOver labels/hints/traits/announcements 5. **Modern Swift & SwiftUI** - Swift 6 concurrency, `@MainActor`, modern APIs 6. **Testable & Reusable Design** - Protocols enable mocking and future package extraction diff --git a/README.md b/README.md index 98d1fb2..b9213d8 100644 --- a/README.md +++ b/README.md @@ -53,6 +53,7 @@ Perfect for low-light selfies, content creation, video calls, makeup application - Dynamic Type and ScaledMetric for readable text at all sizes - String Catalog localization ready (`.xcstrings`) - Consistent design system using Bedrock framework +- Settings cards follow Bedrock’s row contract (`SettingsCard` + `SettingsCardRow` + `SettingsDivider`) for consistent insets and row rhythm - Prevents screen dimming during camera use ## Screenshots diff --git a/SelfieCam.xcodeproj/project.pbxproj b/SelfieCam.xcodeproj/project.pbxproj index 10fdf24..fac7f2d 100644 --- a/SelfieCam.xcodeproj/project.pbxproj +++ b/SelfieCam.xcodeproj/project.pbxproj @@ -442,7 +442,7 @@ "$(inherited)", "@executable_path/Frameworks", ); - MARKETING_VERSION = 1.0; + MARKETING_VERSION = 1.2; PRODUCT_BUNDLE_IDENTIFIER = "$(APP_BUNDLE_IDENTIFIER)"; PRODUCT_NAME = "$(PRODUCT_NAME)"; STRING_CATALOG_GENERATE_SYMBOLS = YES; @@ -472,7 +472,7 @@ "$(inherited)", "@executable_path/Frameworks", ); - MARKETING_VERSION = 1.0; + MARKETING_VERSION = 1.2; PRODUCT_BUNDLE_IDENTIFIER = "$(APP_BUNDLE_IDENTIFIER)"; PRODUCT_NAME = "$(PRODUCT_NAME)"; STRING_CATALOG_GENERATE_SYMBOLS = YES; diff --git a/SelfieCam.xcodeproj/project.xcworkspace/xcuserdata/mattbruce.xcuserdatad/UserInterfaceState.xcuserstate b/SelfieCam.xcodeproj/project.xcworkspace/xcuserdata/mattbruce.xcuserdatad/UserInterfaceState.xcuserstate index 6721b1f..be1f7f7 100644 Binary files a/SelfieCam.xcodeproj/project.xcworkspace/xcuserdata/mattbruce.xcuserdatad/UserInterfaceState.xcuserstate and b/SelfieCam.xcodeproj/project.xcworkspace/xcuserdata/mattbruce.xcuserdatad/UserInterfaceState.xcuserstate differ diff --git a/SelfieCam/Features/Onboarding/Views/OnboardingSettingsView.swift b/SelfieCam/Features/Onboarding/Views/OnboardingSettingsView.swift index 5f0db25..9aeeb3a 100644 --- a/SelfieCam/Features/Onboarding/Views/OnboardingSettingsView.swift +++ b/SelfieCam/Features/Onboarding/Views/OnboardingSettingsView.swift @@ -39,6 +39,7 @@ struct OnboardingSettingsView: View { isOn: $viewModel.isRingLightEnabled, accentColor: AppAccent.primary ) + SettingsDivider(color: AppBorder.subtle) // Camera Position using Bedrock SettingsSegmentedPicker SettingsSegmentedPicker( diff --git a/SelfieCam/Features/Settings/Views/SettingsView.swift b/SelfieCam/Features/Settings/Views/SettingsView.swift index aad7580..b094d54 100644 --- a/SelfieCam/Features/Settings/Views/SettingsView.swift +++ b/SelfieCam/Features/Settings/Views/SettingsView.swift @@ -43,12 +43,17 @@ struct SettingsView: View { accentColor: AppAccent.primary ) .accessibilityHint(String(localized: "Enables or disables the ring light overlay")) + SettingsDivider(color: AppBorder.subtle) // Ring Size Slider ringSizeSlider + SettingsDivider(color: AppBorder.subtle) // Color Preset - colorPresetSection + SettingsCardRow { + colorPresetSection + } + SettingsDivider(color: AppBorder.subtle) // Ring Light Brightness ringLightBrightnessSlider @@ -61,9 +66,11 @@ struct SettingsView: View { SettingsCard(backgroundColor: AppSurface.card, borderColor: AppBorder.subtle) { // Camera Position cameraPositionPicker + SettingsDivider(color: AppBorder.subtle) // Flash Mode flashModePicker + SettingsDivider(color: AppBorder.subtle) // Flash Sync (premium) premiumToggle( @@ -72,9 +79,11 @@ struct SettingsView: View { isOn: $viewModel.isFlashSyncedWithRingLight, accessibilityHint: String(localized: "Syncs flash color with ring light color") ) + SettingsDivider(color: AppBorder.subtle) // HDR Mode hdrModePicker + SettingsDivider(color: AppBorder.subtle) // Center Stage (premium feature) premiumToggle( @@ -83,9 +92,12 @@ struct SettingsView: View { isOn: $viewModel.isCenterStageEnabled, accessibilityHint: String(localized: "Automatically adjusts camera to keep subject centered") ) + SettingsDivider(color: AppBorder.subtle) // Photo Quality - photoQualityPicker + SettingsCardRow { + photoQualityPicker + } } // MARK: - Display Section @@ -101,6 +113,7 @@ struct SettingsView: View { accentColor: AppAccent.primary ) .accessibilityHint(String(localized: "Shows a grid overlay to help compose your shot")) + SettingsDivider(color: AppBorder.subtle) // True Mirror (premium) premiumToggle( @@ -109,6 +122,7 @@ struct SettingsView: View { isOn: $viewModel.isMirrorFlipped, accessibilityHint: String(localized: "Flips the camera preview horizontally") ) + SettingsDivider(color: AppBorder.subtle) // Skin Smoothing (premium) premiumToggle( @@ -132,9 +146,12 @@ struct SettingsView: View { accentColor: AppAccent.primary ) .accessibilityHint(String(localized: "When enabled, photos and videos are saved immediately after capture")) + SettingsDivider(color: AppBorder.subtle) // Timer Selection - timerPicker + SettingsCardRow { + timerPicker + } } @@ -258,7 +275,6 @@ struct SettingsView: View { ) } } - .padding(.vertical, Design.Spacing.xSmall) } // MARK: - Flash Mode Picker @@ -585,40 +601,44 @@ struct SettingsView: View { // MARK: - Branding Debug Section #if DEBUG + @ViewBuilder private var brandingDebugSection: some View { - VStack(spacing: Design.Spacing.small) { - // Debug Premium Toggle - SettingsToggle( - title: "Enable Debug Premium", - subtitle: "Unlock all premium features for testing", - isOn: $viewModel.isDebugPremiumEnabled, - accentColor: AppAccent.primary - ) - - // Reset Onboarding Button + // Debug Premium Toggle + SettingsToggle( + title: "Enable Debug Premium", + subtitle: "Unlock all premium features for testing", + isOn: $viewModel.isDebugPremiumEnabled, + accentColor: AppAccent.primary + ) + SettingsDivider(color: AppBorder.subtle) + + // Reset Onboarding Button + SettingsCardRow { ResetOnboardingButton() - - // Icon Generator - SettingsNavigationRow( - title: "Icon Generator", - subtitle: "Generate and save app icon to Files", - backgroundColor: AppSurface.primary - ) { - IconGeneratorView(config: .selfieCam, appName: "SelfieCam") - } - - // Branding Preview - SettingsNavigationRow( - title: "Branding Preview", - subtitle: "Preview app icon and launch screen", - backgroundColor: AppSurface.primary - ) { - BrandingPreviewView( - iconConfig: .selfieCam, - launchConfig: .selfieCam, - appName: "SelfieCam" - ) - } + } + SettingsDivider(color: AppBorder.subtle) + + // Icon Generator + SettingsNavigationRow( + title: "Icon Generator", + subtitle: "Generate and save app icon to Files", + backgroundColor: .clear + ) { + IconGeneratorView(config: .selfieCam, appName: "SelfieCam") + } + SettingsDivider(color: AppBorder.subtle) + + // Branding Preview + SettingsNavigationRow( + title: "Branding Preview", + subtitle: "Preview app icon and launch screen", + backgroundColor: .clear + ) { + BrandingPreviewView( + iconConfig: .selfieCam, + launchConfig: .selfieCam, + appName: "SelfieCam" + ) } } #endif diff --git a/docs/REVENUECAT_INTEGRATION_GUIDE.md b/docs/REVENUECAT_INTEGRATION_GUIDE.md index 1942fce..c2d8af9 100644 --- a/docs/REVENUECAT_INTEGRATION_GUIDE.md +++ b/docs/REVENUECAT_INTEGRATION_GUIDE.md @@ -1,1270 +1,160 @@ ---- -name: revenuecat-ios-integration -description: Integrate RevenueCat for in-app purchases in iOS/SwiftUI apps. Covers SDK setup, xcconfig-based API key management, PremiumManager implementation, paywalls, and troubleshooting. Use when setting up RevenueCat, implementing subscriptions, configuring API keys via xcconfig/Info.plist, debugging "API key not configured" errors, or when the user mentions RevenueCat, in-app purchases, subscriptions, paywalls, or premium features. ---- +# RevenueCat Integration Guide - SelfieCam -# RevenueCat Integration Guide for iOS +This document describes the RevenueCat integration for SelfieCam and what needs to be configured for production. -A comprehensive, reusable guide for integrating RevenueCat into iOS apps with SwiftUI. This guide covers the complete flow from SDK setup to production deployment. +## Current Configuration -## Table of Contents +### API Key Setup -1. [Overview](#overview) -2. [Prerequisites](#prerequisites) -3. [SDK Installation](#sdk-installation) -4. [Configuration Architecture](#configuration-architecture) - - [Option A: Swift Secrets File](#option-a-swift-secrets-file-simple) - - [Option B: Separate Debug/Release Keys](#option-b-separate-debugrelease-keys-swift-files) - - [Option C: xcconfig + Info.plist (Recommended)](#option-c-xcconfig--infoplist-recommended-for-xcode-15-projects) -5. [PremiumManager Implementation](#premiummanager-implementation) -6. [Paywall Implementation](#paywall-implementation) -7. [Event Handling](#event-handling) -8. [App Store Connect Setup](#app-store-connect-setup) -9. [RevenueCat Dashboard Setup](#revenuecat-dashboard-setup) -10. [Testing Strategies](#testing-strategies) -11. [Production Checklist](#production-checklist) -12. [Troubleshooting](#troubleshooting) +SelfieCam uses xcconfig files to manage RevenueCat API keys, with the key injected into Info.plist at build time. + +**File Structure:** +``` +SelfieCam/ +├── Info.plist # Contains $(REVENUECAT_API_KEY) substitution +├── SelfieCam/ +│ └── Configuration/ +│ ├── Base.xcconfig # Shared settings +│ ├── Debug.xcconfig # Includes Secrets.debug.xcconfig +│ ├── Release.xcconfig # Includes Secrets.release.xcconfig +│ ├── Secrets.debug.xcconfig # Test API key (gitignored) +│ └── Secrets.release.xcconfig # Production API key (gitignored) +``` + +**Current Keys:** +- **Debug**: `test_mImwoNKwfgZcUNQuBLBuVPqSHBR` (configured ✅) +- **Release**: `appl_YOUR_PRODUCTION_KEY_HERE` (needs replacement ❌) + +### PremiumManager + +Located at: `SelfieCam/Shared/Premium/PremiumManager.swift` + +- Reads API key from `Bundle.main.object(forInfoDictionaryKey: "RevenueCatAPIKey")` +- Entitlement identifier: `"Selfie Cam by TopDog Pro"` +- Supports debug premium toggle via UserDefaults --- -## Overview +## Before Release Checklist -RevenueCat simplifies in-app purchases by: -- Handling receipt validation server-side -- Providing cross-platform subscription status -- Offering analytics (MRR, churn, LTV) -- Managing entitlements across multiple products -- Providing pre-built UI components (Paywalls, Customer Center) +### 1. Replace Production API Key -### Key Concepts +Edit `SelfieCam/Configuration/Secrets.release.xcconfig`: -| Concept | Description | -|---------|-------------| -| **Product** | An individual purchasable item (monthly, yearly, lifetime) | -| **Entitlement** | A feature or access level granted by one or more products | -| **Offering** | A collection of packages shown in a paywall | -| **Package** | A product wrapped with metadata for display | -| **Customer Info** | User's current subscription/purchase state | +``` +// Current (placeholder): +REVENUECAT_API_KEY = appl_YOUR_PRODUCTION_KEY_HERE ---- +// Replace with your production key from RevenueCat: +REVENUECAT_API_KEY = appl_your_actual_production_key +``` -## Prerequisites +Get the production key from: **RevenueCat Dashboard → Project Settings → API Keys → Public App-Specific API Key** -- Apple Developer Program membership ($99/year) -- RevenueCat account (free up to $2,500/month revenue) -- Xcode 15.0+ -- iOS 15.0+ deployment target -- Swift 5.9+ +### 2. Verify Entitlement Identifier ---- - -## SDK Installation - -### Swift Package Manager (Recommended) - -1. In Xcode: **File** → **Add Package Dependencies** -2. Enter: `https://github.com/RevenueCat/purchases-ios-spm` -3. Select version (use latest stable) -4. Add both packages to your target: - - `RevenueCat` - Core SDK - - `RevenueCatUI` - Paywalls and Customer Center - -### Package.swift (for packages) +The entitlement identifier in `PremiumManager.swift` must match exactly what's in RevenueCat: ```swift -dependencies: [ - .package(url: "https://github.com/RevenueCat/purchases-ios-spm", from: "5.0.0") -], -targets: [ - .target( - name: "YourApp", - dependencies: [ - .product(name: "RevenueCat", package: "purchases-ios-spm"), - .product(name: "RevenueCatUI", package: "purchases-ios-spm") - ] - ) -] +private let entitlementIdentifier = "Selfie Cam by TopDog Pro" ``` ---- +Verify this matches: **RevenueCat Dashboard → Entitlements → Your Entitlement Name** -## Configuration Architecture +### 3. Configure App Store Connect -### Secrets Management +- [ ] Products created with correct IDs +- [ ] Subscription group configured +- [ ] Paid Apps agreement accepted +- [ ] Bank and tax info submitted -Create a secure configuration system that separates API keys from source code. +### 4. Configure RevenueCat Dashboard -#### Option A: Swift Secrets File (Simple) +Follow these steps at [app.revenuecat.com](https://app.revenuecat.com): -Create `Configuration/Secrets.swift`: +#### Step 1: Create Project and App -```swift -// Secrets.swift -// DO NOT COMMIT THIS FILE TO VERSION CONTROL +1. Create a new project (or use existing) +2. Add iOS app with bundle ID: `com.mbrucedogs.SelfieCam` -import Foundation +#### Step 2: Connect to App Store -enum Secrets { - /// RevenueCat API Key - /// - Debug: Use test/sandbox key (starts with "test_") - /// - Release: Use production key (starts with "appl_") - static let revenueCatAPIKey = "YOUR_API_KEY_HERE" -} -``` +1. Go to **App Store Connect** → **Users and Access** → **Integrations** → **App-Specific Shared Secrets** +2. Generate a new shared secret for SelfieCam +3. In RevenueCat: **Project Settings** → **Apps** → **Selfie Cam** → Add the shared secret -Create `Configuration/Secrets.swift.template` (committed): +#### Step 3: Create Products -```swift -// Copy this file to Secrets.swift and add your actual API key -// Secrets.swift is gitignored +1. Go to **Products** → **+ New** +2. Add each product with IDs matching App Store Connect exactly: + - Example: `com.mbrucedogs.SelfieCam.pro.monthly` + - Example: `com.mbrucedogs.SelfieCam.pro.yearly` + - Example: `com.mbrucedogs.SelfieCam.pro.lifetime` -import Foundation +#### Step 4: Create Entitlement -enum Secrets { - static let revenueCatAPIKey = "YOUR_REVENUECAT_API_KEY_HERE" -} -``` +1. Go to **Entitlements** → **+ New** +2. Create entitlement with identifier: `Selfie Cam by TopDog Pro` +3. Attach all products that should grant this entitlement -Add to `.gitignore`: +#### Step 5: Create Offering -``` -**/Secrets.swift -``` - -#### Option B: Separate Debug/Release Keys (Swift Files) - -Create two secrets files: - -**`Secrets.debug.swift`** (for testing): -```swift -enum Secrets { - static let revenueCatAPIKey = "test_your_test_key" -} -``` - -**`Secrets.release.swift`** (for production): -```swift -enum Secrets { - static let revenueCatAPIKey = "appl_your_production_key" -} -``` - -Use build configurations or compiler flags to include the correct file. - -#### Option C: xcconfig + Info.plist (Recommended for Xcode 15+ Projects) - -This approach is the most robust for modern Xcode projects, especially those using `fileSystemSynchronizedGroups` (automatic file sync). It keeps secrets in xcconfig files and injects them into Info.plist at build time. - -**Why use this approach:** -- Secrets stay in gitignored xcconfig files -- Build settings automatically switch between debug/release keys -- Works with Xcode's auto-generated Info.plist replacement -- No Swift code changes needed to switch keys - -##### Step 1: Create xcconfig Structure - -Create the following files in `YourApp/Configuration/`: - -**`Base.xcconfig`** (committed to git): -``` -// Base.xcconfig - Source of truth for all identifiers - -COMPANY_IDENTIFIER = com.yourcompany -BUNDLE_ID_NAME = YourApp -PRODUCT_NAME = Your App -DEVELOPMENT_TEAM = YOUR_TEAM_ID - -APP_BUNDLE_IDENTIFIER = $(COMPANY_IDENTIFIER).$(BUNDLE_ID_NAME) -``` - -**`Debug.xcconfig`** (committed to git): -``` -// Debug.xcconfig -#include "Base.xcconfig" -#include "Secrets.debug.xcconfig" -``` - -**`Release.xcconfig`** (committed to git): -``` -// Release.xcconfig -#include "Base.xcconfig" -#include "Secrets.release.xcconfig" -``` - -**`Secrets.debug.xcconfig`** (gitignored): -``` -// Secrets.debug.xcconfig -// ⚠️ DO NOT COMMIT THIS FILE - -// RevenueCat Test API Key (starts with "test_") -REVENUECAT_API_KEY = test_your_test_key_here -``` - -**`Secrets.release.xcconfig`** (gitignored): -``` -// Secrets.release.xcconfig -// ⚠️ DO NOT COMMIT THIS FILE - -// RevenueCat Production API Key (starts with "appl_") -REVENUECAT_API_KEY = appl_your_production_key_here -``` - -Add to `.gitignore`: -``` -**/Secrets.debug.xcconfig -**/Secrets.release.xcconfig -``` - -##### Step 2: Create Info.plist at Project Root - -**CRITICAL:** For projects using `fileSystemSynchronizedGroups`, the Info.plist MUST be placed at the **project root** (same level as the `.xcodeproj`), NOT inside the synced app folder. Otherwise Xcode will automatically add it to Copy Bundle Resources and cause build failures. - -Create `Info.plist` at the project root (e.g., `YourApp/Info.plist`, NOT `YourApp/YourApp/Info.plist`): - -```xml - - - - - CFBundleDevelopmentRegion - $(DEVELOPMENT_LANGUAGE) - CFBundleExecutable - $(EXECUTABLE_NAME) - CFBundleIdentifier - $(PRODUCT_BUNDLE_IDENTIFIER) - CFBundleInfoDictionaryVersion - 6.0 - CFBundleName - $(PRODUCT_NAME) - CFBundlePackageType - $(PRODUCT_BUNDLE_PACKAGE_TYPE) - CFBundleShortVersionString - $(MARKETING_VERSION) - CFBundleVersion - $(CURRENT_PROJECT_VERSION) - CFBundleDisplayName - $(PRODUCT_NAME) - LSRequiresIPhoneOS - - UILaunchStoryboardName - LaunchScreen - UIApplicationSceneManifest - - UIApplicationSupportsMultipleScenes - - UISceneConfigurations - - - UIApplicationSupportsIndirectInputEvents - - UISupportedInterfaceOrientations - - UIInterfaceOrientationPortrait - UIInterfaceOrientationLandscapeLeft - UIInterfaceOrientationLandscapeRight - - UISupportedInterfaceOrientations~ipad - - UIInterfaceOrientationPortrait - UIInterfaceOrientationPortraitUpsideDown - UIInterfaceOrientationLandscapeLeft - UIInterfaceOrientationLandscapeRight - - - - NSCameraUsageDescription - Your camera usage description - - - RevenueCatAPIKey - $(REVENUECAT_API_KEY) - - -``` - -##### Step 3: Configure Xcode Project - -1. **Set Build Configurations to use xcconfig files:** - - Project → Info → Configurations - - Set Debug to use `Debug.xcconfig` - - Set Release to use `Release.xcconfig` - -2. **Update Build Settings for the app target:** - - Set `GENERATE_INFOPLIST_FILE = NO` - - Set `INFOPLIST_FILE = Info.plist` (path relative to project root) - -##### Step 4: Update PremiumManager to Read from Info.plist - -```swift -private static var apiKey: String { - let key = (Bundle.main.object(forInfoDictionaryKey: "RevenueCatAPIKey") as? String) ?? "" - let placeholders = [ - "", - "YOUR_REVENUECAT_API_KEY_HERE", - "test_YOUR_TEST_KEY_HERE", - "appl_YOUR_PRODUCTION_KEY_HERE" - ] - - #if DEBUG - let prefix = key.split(separator: "_").first.map(String.init) ?? "missing" - let keyStatus = key.isEmpty ? "empty" : "present" - print("ℹ️ [PremiumManager] RevenueCatAPIKey \(keyStatus), prefix=\(prefix)") - #endif - - guard !placeholders.contains(key) else { - #if DEBUG - print("⚠️ [PremiumManager] RevenueCat API key not configured. Check Secrets.debug.xcconfig / Secrets.release.xcconfig") - #endif - return "" - } - return key -} -``` - -##### Common Pitfalls - -**1. INFOPLIST_KEY_ prefix doesn't work for custom keys** - -The `INFOPLIST_KEY_` build setting prefix (e.g., `INFOPLIST_KEY_RevenueCatAPIKey`) only works for Apple's predefined Info.plist keys. Custom keys like `RevenueCatAPIKey` will NOT be added to the generated Info.plist. - -❌ **Does NOT work:** -``` -// In xcconfig - custom keys are ignored -INFOPLIST_KEY_RevenueCatAPIKey = $(REVENUECAT_API_KEY) -``` - -✅ **Works:** Use a custom Info.plist with build setting substitution: -```xml -RevenueCatAPIKey -$(REVENUECAT_API_KEY) -``` - -**2. Info.plist in synced folder causes "Multiple commands produce Info.plist"** - -If your project uses `fileSystemSynchronizedGroups` (Xcode 15+ default for new projects), placing Info.plist inside the app folder causes Xcode to automatically add it to Copy Bundle Resources, resulting in a build error. - -❌ **Causes error:** `YourApp/YourApp/Info.plist` - -✅ **Correct location:** `YourApp/Info.plist` (at project root, outside the synced folder) - -**3. Wrong xcconfig include path** - -The `#include` path in xcconfig files is relative to the xcconfig file itself. - -❌ **Wrong (if files are in same directory):** -``` -#include "YourApp/Configuration/Secrets.debug.xcconfig" -``` - -✅ **Correct:** -``` -#include "Secrets.debug.xcconfig" -``` - -**4. Verify the key is in the built app** - -After building, verify the key was properly substituted: -```bash -plutil -p ~/Library/Developer/Xcode/DerivedData/YourApp-*/Build/Products/Debug-iphonesimulator/Your\ App.app/Info.plist | grep RevenueCat -``` - -Expected output: -``` -"RevenueCatAPIKey" => "test_your_actual_key" -``` - ---- - -## PremiumManager Implementation - -Create a centralized manager for all RevenueCat interactions. - -### Complete Implementation - -```swift -import RevenueCat -import SwiftUI - -@MainActor -@Observable -final class PremiumManager { - - // MARK: - Published State - - /// Available packages for purchase - var availablePackages: [Package] = [] - - // MARK: - Configuration - - /// Entitlement identifier - must match RevenueCat dashboard - private let entitlementIdentifier = "pro" - - /// Task for listening to customer info updates - @ObservationIgnored private var customerInfoTask: Task? - - /// API key from secrets - private static var apiKey: String { - let key = Secrets.revenueCatAPIKey - guard !key.isEmpty, key != "YOUR_REVENUECAT_API_KEY_HERE" else { - #if DEBUG - print("⚠️ [PremiumManager] RevenueCat API key not configured") - #endif - return "" - } - return key - } - - // MARK: - Debug Override (Optional) - - #if DEBUG - @AppStorage("debugPremiumEnabled") - @ObservationIgnored private var debugPremiumEnabled = false - - private var isDebugPremiumEnabled: Bool { - debugPremiumEnabled || ProcessInfo.processInfo.environment["ENABLE_DEBUG_PREMIUM"] == "1" - } - - var isDebugPremiumToggleEnabled: Bool { - get { debugPremiumEnabled } - set { debugPremiumEnabled = newValue } - } - #endif - - // MARK: - Premium Status - - var isPremium: Bool { - #if DEBUG - if isDebugPremiumEnabled { return true } - #endif - - guard !Self.apiKey.isEmpty else { return false } - - return Purchases.shared.cachedCustomerInfo? - .entitlements[entitlementIdentifier]?.isActive == true - } - - /// Alias for compatibility - var isPremiumUnlocked: Bool { isPremium } - - // MARK: - Initialization - - init() { - guard !Self.apiKey.isEmpty else { - #if DEBUG - print("⚠️ [PremiumManager] Skipping RevenueCat configuration - no API key") - #endif - return - } - - #if DEBUG - Purchases.logLevel = .debug - #endif - - Purchases.configure(withAPIKey: Self.apiKey) - - Task { - try? await loadProducts() - } - } - - // MARK: - Products - - func loadProducts() async throws { - guard !Self.apiKey.isEmpty else { return } - - let offerings = try await Purchases.shared.offerings() - if let current = offerings.current { - availablePackages = current.availablePackages - } - } - - // MARK: - Purchase - - func purchase(_ package: Package) async throws -> Bool { - #if DEBUG - if isDebugPremiumEnabled { - return true // Simulate success - } - #endif - - let result = try await Purchases.shared.purchase(package: package) - return result.customerInfo.entitlements[entitlementIdentifier]?.isActive == true - } - - func purchase(productId: String) async throws { - guard let package = availablePackages.first(where: { - $0.storeProduct.productIdentifier == productId - }) else { - throw PurchaseError.productNotFound - } - _ = try await purchase(package) - } - - // MARK: - Restore - - func restorePurchases() async throws { - #if DEBUG - if isDebugPremiumEnabled { return } - #endif - - _ = try await Purchases.shared.restorePurchases() - } - - // MARK: - Subscription Status - - /// Fetch fresh customer info (call on app launch) - func checkSubscriptionStatus() async { - guard !Self.apiKey.isEmpty else { return } - - do { - _ = try await Purchases.shared.customerInfo() - } catch { - #if DEBUG - print("⚠️ [PremiumManager] Failed to fetch customer info: \(error)") - #endif - } - } - - // MARK: - Real-time Updates - - /// Start listening for subscription changes - func startListeningForCustomerInfoUpdates() { - guard !Self.apiKey.isEmpty else { return } - - customerInfoTask?.cancel() - - customerInfoTask = Task { - for await customerInfo in Purchases.shared.customerInfoStream { - let isActive = customerInfo.entitlements[entitlementIdentifier]?.isActive == true - #if DEBUG - print("📱 [PremiumManager] Customer info updated. Premium: \(isActive)") - #endif - } - } - } - - func stopListeningForCustomerInfoUpdates() { - customerInfoTask?.cancel() - customerInfoTask = nil - } -} - -// MARK: - Errors - -enum PurchaseError: LocalizedError { - case productNotFound - - var errorDescription: String? { - switch self { - case .productNotFound: - return "Product not found" - } - } -} -``` - -### App Entry Point Integration - -```swift -@main -struct YourApp: App { - @State private var premiumManager = PremiumManager() - - var body: some Scene { - WindowGroup { - ContentView() - .environment(premiumManager) - .task { - await premiumManager.checkSubscriptionStatus() - premiumManager.startListeningForCustomerInfoUpdates() - } - } - } -} -``` - ---- - -## Paywall Implementation - -### PaywallPresenter with Fallback - -Use RevenueCat's native PaywallView with a custom fallback for offline scenarios. - -```swift -import SwiftUI -import RevenueCat -import RevenueCatUI - -struct PaywallPresenter: View { - /// Called on successful purchase or restore - var onPurchaseSuccess: (() -> Void)? - - @Environment(\.dismiss) private var dismiss - @State private var offering: Offering? - @State private var isLoading = true - @State private var useFallback = false - @State private var errorMessage: String? - @State private var showError = false - - init(onPurchaseSuccess: (() -> Void)? = nil) { - self.onPurchaseSuccess = onPurchaseSuccess - } - - var body: some View { - Group { - if isLoading { - loadingView - } else if useFallback { - CustomPaywallView(onPurchaseSuccess: onPurchaseSuccess) - } else if let offering { - paywallView(for: offering) - } else { - CustomPaywallView(onPurchaseSuccess: onPurchaseSuccess) - } - } - .task { - await loadOffering() - } - .alert("Purchase Error", isPresented: $showError, presenting: errorMessage) { _ in - Button("OK", role: .cancel) { errorMessage = nil } - } message: { message in - Text(message) - } - } - - private var loadingView: some View { - VStack { - ProgressView() - .scaleEffect(1.5) - Text("Loading...") - .padding(.top, 16) - } - .frame(maxWidth: .infinity, maxHeight: .infinity) - } - - private func paywallView(for offering: Offering) -> some View { - PaywallView(offering: offering) - .onPurchaseCompleted { _ in - onPurchaseSuccess?() - dismiss() - } - .onPurchaseCancelled { - // User cancelled - keep paywall open - } - .onPurchaseFailure { error in - errorMessage = error.localizedDescription - showError = true - } - .onRestoreCompleted { customerInfo in - if !customerInfo.entitlements.active.isEmpty { - onPurchaseSuccess?() - dismiss() - } - } - .onRestoreFailure { error in - errorMessage = error.localizedDescription - showError = true - } - } - - private func loadOffering() async { - do { - let offerings = try await Purchases.shared.offerings() - if let current = offerings.current { - offering = current - } else { - useFallback = true - } - } catch { - useFallback = true - } - isLoading = false - } -} -``` - -### Paywall Integration Patterns - -There are two primary contexts for presenting paywalls, each requiring different handling. - -#### Use Case 1: Onboarding Flow - -During onboarding, a successful purchase should complete the onboarding and transition to the main app. - -```swift -struct RootView: View { - @AppStorage("hasCompletedOnboarding") private var hasCompletedOnboarding = false - @State private var onboardingViewModel = OnboardingViewModel() - @State private var settingsViewModel = SettingsViewModel() - @State private var showPaywall = false - - var body: some View { - ZStack { - if hasCompletedOnboarding { - MainAppView() - } else { - OnboardingView( - viewModel: onboardingViewModel, - showPaywall: $showPaywall, - onComplete: { - withAnimation { - hasCompletedOnboarding = true - } - } - ) - } - } - .sheet(isPresented: $showPaywall) { - PaywallPresenter { - // Purchase successful during onboarding - complete it - if !hasCompletedOnboarding { - onboardingViewModel.completeOnboarding(settings: settingsViewModel) - withAnimation { - hasCompletedOnboarding = true - } - } - } - } - } -} -``` - -**Key points for onboarding:** -- Pass a success callback that completes onboarding -- Transition directly to main app after successful purchase -- User skipping the paywall continues onboarding normally - -#### Use Case 2: In-App Purchase (Settings, Feature Gates) - -When users trigger the paywall from within the app (e.g., tapping a premium feature in Settings), the UI must refresh to reflect the new premium status after purchase. - -```swift -struct MainContentView: View { - @State private var settings = SettingsViewModel() - @State private var showSettings = false - @State private var showPaywall = false - - var body: some View { - // Main app content - YourMainView() - .sheet(isPresented: $showSettings) { - SettingsView(viewModel: settings, showPaywall: $showPaywall) - } - .sheet(isPresented: $showPaywall, onDismiss: { - // CRITICAL: Force UI to refresh premium status after paywall closes - settings.refreshPremiumStatus() - }) { - PaywallPresenter() - } - } -} -``` - -**Key points for in-app purchases:** -- Use `onDismiss` to trigger a premium status refresh -- No success callback needed (UI refreshes via observation) -- Settings dismisses before showing paywall, then user returns to main view - -#### Combined Pattern - -For apps with both onboarding and in-app paywalls, handle both cases: - -```swift -.sheet(isPresented: $showPaywall, onDismiss: { - // Always refresh premium status when paywall closes - settings.refreshPremiumStatus() -}) { - PaywallPresenter { - // Only used during onboarding - if !hasCompletedOnboarding { - completeOnboarding() - } - // For in-app purchases, the onDismiss handles the refresh - } -} -``` - ---- - -## Event Handling - -### Available RevenueCat PaywallView Callbacks - -| Modifier | When Called | -|----------|------------| -| `.onPurchaseStarted { package in }` | Purchase initiated for a package | -| `.onPurchaseCompleted { customerInfo in }` | Purchase successful | -| `.onPurchaseCancelled { }` | User cancelled purchase | -| `.onPurchaseFailure { error in }` | Purchase failed | -| `.onRestoreStarted { }` | Restore initiated | -| `.onRestoreCompleted { customerInfo in }` | Restore successful | -| `.onRestoreFailure { error in }` | Restore failed | -| `.onRequestedDismissal { }` | Paywall requests to close | - -### Error Handling Best Practices - -```swift -.onPurchaseFailure { error in - let nsError = error as NSError - - // Don't show error for user cancellation - if nsError.code == 2 { // SKError.paymentCancelled - return - } - - // Handle specific error types - switch nsError.code { - case 0: // SKError.unknown - errorMessage = "An unknown error occurred. Please try again." - case 1: // SKError.clientInvalid - errorMessage = "You are not authorized to make purchases." - case 3: // SKError.paymentNotAllowed - errorMessage = "Payments are not allowed on this device." - default: - errorMessage = error.localizedDescription - } - showError = true -} -``` - ---- - -## SwiftUI Observation and Premium Status Updates - -### The Problem - -When a user completes a purchase, RevenueCat updates `Purchases.shared.cachedCustomerInfo` with the new subscription status. However, SwiftUI's `@Observable` macro doesn't automatically detect changes to this shared singleton. - -**This affects the in-app purchase flow (Use Case 2), not onboarding (Use Case 1):** - -| Use Case | Affected? | Why | -|----------|-----------|-----| -| Onboarding | No | Success callback explicitly completes onboarding and transitions to main app | -| In-App (Settings) | **Yes** | UI must detect the change to show unlocked features | - -### Why In-App Purchases Don't Update the UI - -1. User opens Settings (which has a `SettingsViewModel` with its own `PremiumManager`) -2. User taps a premium feature, triggering the paywall -3. User completes purchase successfully -4. Paywall dismisses, returning to Settings -5. `isPremiumUnlocked` still returns `false` in the UI even though purchase succeeded - -**Technical reason:** -- `isPremiumUnlocked` reads from `Purchases.shared.cachedCustomerInfo` -- The cached customer info IS updated after purchase -- But SwiftUI doesn't re-render because no `@Observable` property changed - -### Solution: Refresh Token Pattern - -Add a refresh mechanism that forces SwiftUI to re-evaluate the premium status: - -```swift -@MainActor -@Observable -final class SettingsViewModel { - @ObservationIgnored let premiumManager = PremiumManager() - - // Refresh token that forces re-evaluation when incremented - private var premiumRefreshToken: Int = 0 - - /// Premium status - always reads current value from RevenueCat - var isPremiumUnlocked: Bool { - // Access refresh token to create observation dependency - _ = premiumRefreshToken - return premiumManager.isPremiumUnlocked - } - - /// Force SwiftUI to re-evaluate premium status - /// Call this after paywall dismisses - func refreshPremiumStatus() { - premiumRefreshToken += 1 - } -} -``` - -### Triggering the Refresh - -Always call `refreshPremiumStatus()` when the paywall sheet dismisses: - -```swift -.sheet(isPresented: $showPaywall, onDismiss: { - // Force UI to re-check premium status after paywall closes - // This handles both successful purchases and user cancellations - settings.refreshPremiumStatus() -}) { - PaywallPresenter() -} -``` - -**Why use `onDismiss` instead of the success callback?** -- `onDismiss` is called for all dismissal reasons (purchase, cancel, swipe down) -- It ensures the UI always reflects the current state -- Works for both onboarding and in-app contexts - -### Complete Integration Example - -Handling both onboarding and in-app purchase flows: - -```swift -struct RootView: View { - @AppStorage("hasCompletedOnboarding") private var hasCompletedOnboarding = false - @State private var settings = SettingsViewModel() - @State private var showPaywall = false - - var body: some View { - Group { - if hasCompletedOnboarding { - MainAppView(settings: settings, showPaywall: $showPaywall) - } else { - OnboardingView(showPaywall: $showPaywall, onComplete: completeOnboarding) - } - } - .sheet(isPresented: $showPaywall, onDismiss: { - // ALWAYS refresh after paywall closes (for in-app purchases) - settings.refreshPremiumStatus() - }) { - PaywallPresenter { - // Only for onboarding: complete it on successful purchase - if !hasCompletedOnboarding { - completeOnboarding() - } - } - } - } - - private func completeOnboarding() { - withAnimation { - hasCompletedOnboarding = true - } - } -} -``` - -### Alternative: Shared PremiumManager via Environment - -Instead of each view model having its own `PremiumManager`, use a single shared instance: - -```swift -@main -struct YourApp: App { - @State private var premiumManager = PremiumManager() - - var body: some Scene { - WindowGroup { - RootView() - .environment(premiumManager) - .task { - await premiumManager.checkSubscriptionStatus() - premiumManager.startListeningForCustomerInfoUpdates() - } - } - } -} - -// In any view: -struct SettingsView: View { - @Environment(PremiumManager.self) private var premiumManager - - var body: some View { - if premiumManager.isPremiumUnlocked { - // Premium content - } - } -} -``` - -This approach ensures all views observe the same instance. - -### Testing Checklist - -Test both purchase flows to ensure they work correctly: - -**Onboarding Flow:** -- [ ] Skip to paywall step in onboarding -- [ ] Complete a purchase -- [ ] Verify: App transitions to main content immediately -- [ ] Verify: Premium features are unlocked - -**In-App Purchase Flow:** -- [ ] Complete onboarding WITHOUT purchasing (tap "Maybe Later") -- [ ] Open Settings -- [ ] Tap a premium feature to trigger paywall -- [ ] Complete a purchase -- [ ] Verify: Paywall dismisses -- [ ] Verify: Settings shows premium features as unlocked -- [ ] Verify: No need to restart app or reopen Settings - -**Restore Purchases:** -- [ ] Test restore from onboarding soft paywall -- [ ] Test restore from in-app paywall -- [ ] Verify: UI updates correctly after restore - ---- - -## App Store Connect Setup - -### 1. Create Your App - -1. Go to [App Store Connect](https://appstoreconnect.apple.com) -2. **My Apps** → **+** → **New App** -3. Fill in bundle ID (must match Xcode exactly) - -### 2. Create Subscription Group - -1. In your app → **Subscriptions** -2. Click **+** next to "Subscription Groups" -3. Name it (e.g., "Pro Access") - -### 3. Create Products - -**Auto-Renewable Subscriptions** (monthly, yearly): - -| Field | Example Value | -|-------|--------------| -| Reference Name | Pro Monthly | -| Product ID | `com.company.app.pro.monthly` | -| Duration | 1 Month | -| Price | $2.99 | - -**Non-Consumable** (lifetime): - -| Field | Example Value | -|-------|--------------| -| Reference Name | Pro Lifetime | -| Product ID | `com.company.app.pro.lifetime` | -| Price | $39.99 | - -### 4. Agreements - -1. **Agreements, Tax, and Banking** → Accept **Paid Applications** -2. Add bank account and tax information - ---- - -## RevenueCat Dashboard Setup - -### 1. Create Project and App - -1. Create project at [RevenueCat](https://app.revenuecat.com) -2. Add iOS app with your bundle ID - -### 2. Connect to App Store - -1. Get App-Specific Shared Secret from App Store Connect -2. Add to RevenueCat: **Project Settings** → **Apps** → your app - -### 3. Create Products - -Add each product with IDs matching App Store Connect exactly. - -### 4. Create Entitlement - -1. **Entitlements** → **+ New** -2. Name: `pro` (or your identifier) -3. Attach all products that grant this entitlement - -### 5. Create Offering - -1. **Offerings** → Edit **default** +1. Go to **Offerings** → Edit **default** offering 2. Add packages: - - `$rc_monthly` → monthly product - - `$rc_annual` → yearly product - - `$rc_lifetime` → lifetime product + - `$rc_monthly` → your monthly product + - `$rc_annual` → your yearly product + - `$rc_lifetime` → your lifetime product -### 6. Design Paywall (Optional) +#### Step 6: Design Paywall (Optional) 1. In your offering, click **Add Paywall** 2. Use the visual editor to design -3. Configure colors, text, layout +3. Configure colors, text, layout to match SelfieCam branding -### 7. Get API Keys +#### Step 7: Get API Keys -- **Test Key** (starts with `test_`): For development, free purchases -- **Production Key** (starts with `appl_`): For App Store builds +Go to **Project Settings** → **API Keys**: +- **Test Key** (starts with `test_`): Already configured in `Secrets.debug.xcconfig` +- **Production Key** (starts with `appl_`): Copy this to `Secrets.release.xcconfig` --- -## Testing Strategies +## Testing -### 1. Debug Premium Toggle (Fastest) +### Debug Premium Toggle -For UI testing without purchase flow: +In debug builds, you can enable premium without purchasing: +1. Go to Settings in the app +2. Toggle "Debug Premium" (only visible in DEBUG builds) -```swift -#if DEBUG -Toggle("Debug Premium", isOn: $premiumManager.isDebugPremiumToggleEnabled) -#endif -``` - -### 2. StoreKit Configuration File (Local) - -1. **File** → **New** → **StoreKit Configuration File** -2. Add products matching your IDs -3. **Edit Scheme** → **Run** → **Options** → Set StoreKit Configuration -4. Purchases are instant and free - -### 3. RevenueCat Test Mode (Integration) - -Use the test API key (`test_`): -- Purchases are free -- Transactions appear in RevenueCat dashboard -- Restore not available (returns cached info) - -### 4. Sandbox Testing (Full) +### Sandbox Testing 1. Create Sandbox Tester in App Store Connect 2. Sign out of App Store on device 3. Make purchase, sign in with sandbox credentials 4. Verify in RevenueCat dashboard -**Sandbox Renewal Times:** - -| Real | Sandbox | -|------|---------| -| 1 week | 3 min | -| 1 month | 5 min | -| 1 year | 1 hour | - ---- - -## Production Checklist - -### Code - -- [ ] PremiumManager configured with production API key -- [ ] Secrets file is gitignored -- [ ] Error handling for all purchase scenarios -- [ ] Loading states during purchases -- [ ] Restore purchases functionality -- [ ] Real-time subscription status updates - -### App Store Connect - -- [ ] App created with correct bundle ID -- [ ] All products created with localizations -- [ ] Subscription group configured -- [ ] Paid Apps agreement accepted -- [ ] Bank and tax info submitted - -### RevenueCat Dashboard - -- [ ] Production app created with bundle ID -- [ ] Shared secret configured -- [ ] All products added (IDs match exactly) -- [ ] Entitlement created with products attached -- [ ] Offering configured with packages -- [ ] (Optional) Paywall designed - -### Testing - -- [ ] Tested with StoreKit Configuration -- [ ] Tested with sandbox account -- [ ] Verified transactions in RevenueCat dashboard -- [ ] Tested restore purchases -- [ ] Tested subscription expiration/renewal - --- ## Troubleshooting +### "RevenueCat API key not configured" + +1. Clean build: `rm -rf ~/Library/Developer/Xcode/DerivedData/SelfieCam-*` +2. Verify xcconfig includes are correct (relative paths) +3. Check `Info.plist` contains `RevenueCatAPIKey$(REVENUECAT_API_KEY)` +4. Verify with: `plutil -p ~/Library/Developer/Xcode/DerivedData/SelfieCam-*/Build/Products/Debug-*/Selfie\ Cam.app/Info.plist | grep Revenue` + ### Products Not Loading 1. Verify product IDs match exactly (case-sensitive) -2. Check API key is correct -3. Ensure shared secret is configured -4. Wait a few minutes after creating products - -### "Purchases has not been configured" - -- `Purchases.configure(withAPIKey:)` must be called before any other SDK methods -- Ensure it's called early in app lifecycle (App init or `@main`) - -### Sandbox Purchase Fails - -1. Sign out of regular App Store -2. Use sandbox credentials (not real Apple ID) -3. Check Paid Apps agreement is accepted -4. Ensure products have prices set - -### Entitlements Not Granting Access - -1. Verify entitlement identifier matches code exactly -2. Check products are attached to entitlement -3. Confirm packages are in the offering - -### RevenueCat Dashboard Empty - -1. Using test key shows in sandbox environment -2. Check bundle ID matches exactly -3. Wait 1-2 minutes for transactions to appear - -### API Key Shows in Build Settings But Not in App (xcconfig) - -**Symptom:** `xcodebuild -showBuildSettings` shows `REVENUECAT_API_KEY = test_...` but the app logs show "RevenueCatAPIKey empty". - -**Cause:** The `INFOPLIST_KEY_` prefix only works for Apple's predefined keys, not custom keys. - -**Solution:** -1. Create a custom `Info.plist` file at the project root (NOT inside the synced app folder) -2. Add the key with build setting substitution: `$(REVENUECAT_API_KEY)` -3. Set `GENERATE_INFOPLIST_FILE = NO` in build settings -4. Set `INFOPLIST_FILE = Info.plist` - -See [Option C: xcconfig + Info.plist](#option-c-xcconfig--infoplist-recommended-for-xcode-15-projects) for complete instructions. - -### "Multiple commands produce Info.plist" Build Error - -**Cause:** The Info.plist file is inside a `fileSystemSynchronizedGroups` folder (Xcode 15+ default), causing Xcode to automatically add it to Copy Bundle Resources. - -**Solution:** Move Info.plist to the project root directory (same level as `.xcodeproj`), NOT inside the app source folder. - -``` -YourProject/ -├── YourProject.xcodeproj -├── Info.plist ← Correct location -└── YourProject/ - └── (source files) ← NOT here -``` - -### xcconfig Include Path Errors - -**Symptom:** Build settings show empty or placeholder values even though the Secrets xcconfig files exist. - -**Cause:** The `#include` path is relative to the xcconfig file itself, not the project root. - -**Fix:** If `Debug.xcconfig` and `Secrets.debug.xcconfig` are in the same directory: - -``` -// Wrong -#include "YourApp/Configuration/Secrets.debug.xcconfig" - -// Correct -#include "Secrets.debug.xcconfig" -``` - -### Verifying xcconfig Setup - -Run these commands to debug your xcconfig setup: - -```bash -# Check if REVENUECAT_API_KEY is in build settings -xcodebuild -showBuildSettings -scheme "YourScheme" -configuration Debug | grep REVENUECAT - -# Check if key is in the built Info.plist -plutil -p ~/Library/Developer/Xcode/DerivedData/YourApp-*/Build/Products/Debug-iphonesimulator/Your\ App.app/Info.plist | grep -i revenue - -# Clean and rebuild after xcconfig changes -rm -rf ~/Library/Developer/Xcode/DerivedData/YourApp-* -xcodebuild clean build -scheme "YourScheme" -configuration Debug -destination "platform=iOS Simulator,name=iPhone 16 Pro" -``` +2. Check API key is correct for environment +3. Ensure shared secret is configured in RevenueCat +4. Wait a few minutes after creating new products --- -## Resources +## Related Documentation -- [RevenueCat Documentation](https://docs.revenuecat.com) -- [RevenueCat iOS SDK Reference](https://sdk.revenuecat.com/ios/index.html) -- [App Store Connect Help](https://help.apple.com/app-store-connect/) -- [StoreKit Documentation](https://developer.apple.com/documentation/storekit) +- [IN_APP_PURCHASE_SETUP.md](IN_APP_PURCHASE_SETUP.md) - Detailed App Store Connect setup +- [RevenueCat Docs](https://docs.revenuecat.com) - Official documentation