SelfieCam/docs/IN_APP_PURCHASE_SETUP.md

# In-App Purchase Setup Guide

This guide walks through setting up Monthly, Yearly, and Lifetime in-app purchases for SelfieCam using RevenueCat.

## Prerequisites

- Apple Developer Program membership ($99/year)
- RevenueCat account (free tier available)
- Xcode with SelfieCam project

---

## Part 1: App Store Connect Setup

### Step 1: Create Your App

1. Go to [App Store Connect](https://appstoreconnect.apple.com)
2. Click **My Apps** → **+** → **New App**
3. Fill in:
   - **Platform**: iOS
   - **Name**: SelfieCam (or your app name)
   - **Primary Language**: English (US)
   - **Bundle ID**: Select your app's bundle ID (must match Xcode)
   - **SKU**: A unique identifier (e.g., `selfiecam2026`)
4. Click **Create**

### Step 2: Create a Subscription Group

Subscriptions must belong to a group. Users can only have one active subscription per group.

1. In your app, go to **Subscriptions** (left sidebar under "In-App Purchases")
2. Click **+** next to "Subscription Groups"
3. Enter group name: `SelfieCam Pro`
4. Click **Create**

### Step 3: Create Monthly Subscription

1. In your subscription group, click **+** next to "Subscriptions"
2. Fill in:
   - **Reference Name**: Pro Monthly (internal only)
   - **Product ID**: `com.mbrucedogs.SelfieCam.pro.monthly`
     - Replace `yourcompany` with your actual company/developer name
     - This ID is permanent and cannot be changed
3. Click **Create**
4. On the subscription page:
   - **Subscription Duration**: 1 Month
   - **Subscription Prices**: Click **+**, select your base country, enter price (e.g., $2.99/month)
   - **App Store Localization**: Click **+**, add English (US):
     - **Display Name**: Pro Monthly
     - **Description**: Unlock all premium features with monthly access
5. Click **Save**

### Step 4: Create Yearly Subscription

1. In your subscription group, click **+** next to "Subscriptions"
2. Fill in:
   - **Reference Name**: Pro Yearly
   - **Product ID**: `com.mbrucedogs.SelfieCam.pro.yearly`
3. Click **Create**
4. On the subscription page:
   - **Subscription Duration**: 1 Year
   - **Subscription Prices**: Enter price (e.g., $19.99/year - ~33% savings vs monthly)
   - **App Store Localization**:
     - **Display Name**: Pro Yearly
     - **Description**: Best value! Unlock all premium features for a full year
5. Click **Save**

### Step 5: Create Lifetime (Non-Consumable)

Lifetime purchases are NOT subscriptions - they're non-consumable in-app purchases.

1. Go to **In-App Purchases** (left sidebar, separate from Subscriptions)
2. Click **+** → **Non-Consumable**
3. Fill in:
   - **Reference Name**: Pro Lifetime
   - **Product ID**: `com.brumcedogs.SelfieCam.pro.lifetime`
4. Click **Create**
5. On the product page:
   - **Price Schedule**: Click **+**, select base country, enter price (e.g., $39.99)
   - **App Store Localization**: Click **+**, add English (US):
     - **Display Name**: Pro Lifetime
     - **Description**: Pay once, own forever. All premium features unlocked permanently.
6. Click **Save**

### Step 6: Agreements and Tax Setup

Before you can sell, you must accept agreements:

1. Go to [Agreements, Tax, and Banking](https://appstoreconnect.apple.com/agreements)
2. Accept the **Paid Applications** agreement
3. Fill in your **Bank Account** information
4. Fill in your **Tax Forms** (varies by country)

> **Note**: Products will show "Missing Metadata" until your app is submitted. This is normal.

---

## Part 2: RevenueCat Setup

### Step 1: Create RevenueCat Account

1. Go to [RevenueCat](https://www.revenuecat.com)
2. Click **Get Started** → **Sign up**
3. Choose the free tier (covers up to $2,500/month in revenue)

### Step 2: Create a Project

1. After signup, click **Create New Project**
2. Enter project name: `SelfieCam`
3. Click **Create Project**

### Step 3: Add Your iOS App

1. In your project, go to **Project Settings** (gear icon) → **Apps**
2. Click **+ New App**
3. Select **App Store** (iOS)
4. Fill in:
   - **App Name**: SelfieCam
   - **Bundle ID**: Your exact bundle ID from Xcode (e.g., `com.mbrucedogs.SelfieCam`)
5. Click **Save Changes**

### Step 4: Connect to App Store Connect

RevenueCat needs your App Store Connect shared secret to validate receipts:

1. In App Store Connect, go to your app → **App Information** (left sidebar)
2. Scroll to **App-Specific Shared Secret** → Click **Manage**
3. Click **Generate** if you don't have one
4. Copy the shared secret
5. Back in RevenueCat, go to **Project Settings** → **Apps** → your iOS app
6. Paste the shared secret in **App Store Connect App-Specific Shared Secret**
7. Click **Save Changes**

### Step 5: Create Products in RevenueCat

1. Go to **Products** (left sidebar)
2. Click **+ New Product** for each:

**Product 1 - Monthly:**
- **Identifier**: `com.mbrucedogs.SelfieCam.pro.monthly` (must match App Store Connect exactly)
- **App**: SelfieCam (iOS)
- Click **Add**

**Product 2 - Yearly:**
- **Identifier**: `com.mbrucedogs.SelfieCam.pro.yearly`
- **App**: SelfieCam (iOS)
- Click **Add**

**Product 3 - Lifetime:**
- **Identifier**: `com.mbrucedogs.SelfieCam.pro.lifetime`
- **App**: SelfieCam (iOS)
- Click **Add**

### Step 6: Create an Entitlement

Entitlements represent what the user "gets" - your code checks for this.

1. Go to **Entitlements** (left sidebar)
2. Click **+ New Entitlement**
3. Enter identifier: `Selfie Cam by TopDog Pro` (this matches the code in `PremiumManager.swift`)
4. Click **Add**
5. Now attach all 3 products:
   - Click on the `Selfie Cam by TopDog Pro` entitlement
   - Click **Attach Products**
   - Select all 3 products (monthly, yearly, lifetime)
   - Click **Attach**

### Step 7: Create an Offering

Offerings group products for display in your paywall.

1. Go to **Offerings** (left sidebar)
2. You'll see a default offering already exists
3. Click on **default** offering
4. Click **+ New Package** for each:

**Package 1:**
- **Identifier**: Select `$rc_monthly` from dropdown
- **Product**: Select your monthly product
- Click **Add**

**Package 2:**
- **Identifier**: Select `$rc_annual` from dropdown
- **Product**: Select your yearly product
- Click **Add**

**Package 3:**
- **Identifier**: Select `$rc_lifetime` from dropdown
- **Product**: Select your lifetime product
- Click **Add**

### Step 8: Get Your API Key

1. Go to **Project Settings** (gear icon) → **API Keys**
2. Copy your **Public App-Specific API Key** (starts with `appl_`)
3. In your Xcode project, add this to `Configuration/Secrets.xcconfig`:

```
REVENUECAT_API_KEY = appl_your_api_key_here
```

> **Important**: Never commit `Secrets.xcconfig` to git. It should be in your `.gitignore`.

---

## Part 3: Testing Purchases

There are three ways to test purchases without paying real money.

### Option A: Debug Premium Toggle (Fastest - No Setup Required)

Use the built-in debug toggle to bypass premium checks entirely:

1. Run the app in DEBUG mode
2. Go to **Settings** → scroll to **Debug** section
3. Toggle **Enable Debug Premium** on
4. All premium features are now unlocked

This is useful for testing the UI but doesn't test the actual purchase flow.

### Option B: StoreKit Configuration File (Local Testing)

Test purchases locally without App Store Connect:

1. **Create a StoreKit Configuration File**
   - In Xcode: File → New → File → **StoreKit Configuration File**
   - Name it `Products.storekit`
   - Save it in the SelfieCam project folder

2. **Add Your Products**
   Click **+** in the editor and add:

   | Type | Reference Name | Product ID |
   |------|---------------|------------|
   | Auto-Renewable Subscription | Pro Monthly | `com.mbrucedogs.SelfieCam.pro.monthly` |
   | Auto-Renewable Subscription | Pro Yearly | `com.mbrucedogs.SelfieCam.pro.yearly` |
   | Non-Consumable | Pro Lifetime | `com.mbrucedogs.SelfieCam.pro.lifetime` |

   For subscriptions, create a subscription group called "SelfieCam Pro" first.

3. **Enable It in Your Scheme**
   - Product → Scheme → Edit Scheme (or ⌘<)
   - Select **Run** → **Options** tab
   - Set **StoreKit Configuration** to your `Products.storekit` file

4. **Test Purchases**
   - Run the app in Simulator or on device
   - Purchases are instant and free
   - Manage transactions: Debug → StoreKit → Manage Transactions

> **Note**: StoreKit Configuration testing works with RevenueCat but transactions won't appear in the RevenueCat dashboard.

### Option C: Sandbox Testing (Full Integration Test)

Test the complete flow with App Store Connect and RevenueCat:

1. **Create a Sandbox Tester Account**
   - Go to [App Store Connect](https://appstoreconnect.apple.com) → **Users and Access** → **Sandbox** → **Testers**
   - Click **+** to add a new tester
   - Use a fake email you control (not a real Apple ID)
   - Set a password you'll remember

2. **Sign Out of App Store on Your Test Device**
   - Settings → App Store → Tap your Apple ID → Sign Out
   - **Don't sign back in yet**

3. **Run Your App and Make a Purchase**
   - Run the app on a physical device (recommended) or simulator
   - Tap a purchase button
   - When prompted to sign in, use your sandbox tester credentials
   - Complete the purchase - it's free!

4. **Verify in RevenueCat**
   - Go to RevenueCat dashboard → **Customers**
   - Search for your sandbox user
   - You should see their entitlement and transaction

**Sandbox Subscription Renewal Times:**

| Real Duration | Sandbox Duration |
|--------------|------------------|
| 1 week | 3 minutes |
| 1 month | 5 minutes |
| 2 months | 10 minutes |
| 3 months | 15 minutes |
| 6 months | 30 minutes |
| 1 year | 1 hour |

Subscriptions auto-renew up to 6 times in sandbox, then expire.

---

## Setup Checklist

### App Store Connect
- [ ] App created with correct bundle ID
- [ ] Subscription group created (`SelfieCam Pro`)
- [ ] Monthly subscription created with price and localization
- [ ] Yearly subscription created with price and localization
- [ ] Lifetime non-consumable created with price and localization
- [ ] Paid Apps agreement accepted
- [ ] Bank and tax info submitted
- [ ] Sandbox tester account created

### RevenueCat
- [ ] Account created
- [ ] Project created
- [ ] iOS app added with bundle ID
- [ ] Shared secret from App Store Connect added
- [ ] 3 products created (matching App Store Connect IDs exactly)
- [ ] `pro` entitlement created
- [ ] All 3 products attached to `pro` entitlement
- [ ] Default offering has 3 packages (monthly, annual, lifetime)
- [ ] API key copied to `Secrets.xcconfig`

### Xcode
- [ ] `Secrets.xcconfig` contains `REVENUECAT_API_KEY`
- [ ] `Secrets.xcconfig` is in `.gitignore`
- [ ] (Optional) StoreKit Configuration file created for local testing

---

## Troubleshooting

### Products Not Loading

- Verify product IDs match exactly between App Store Connect and RevenueCat
- Check that the RevenueCat API key is correctly set in `Secrets.xcconfig`
- Ensure the shared secret is added in RevenueCat
- Products may take a few minutes to propagate after creation

### Sandbox Purchases Failing

- Make sure you're signed out of the regular App Store
- Use sandbox credentials, not your real Apple ID
- Check that agreements are accepted in App Store Connect
- Verify the device isn't in a restricted region

### RevenueCat Not Showing Transactions

- Sandbox transactions can take a minute to appear
- Verify the bundle ID matches exactly
- Check that products are attached to the entitlement
- Look at RevenueCat's debug logs in Xcode console

### "Missing Metadata" in App Store Connect

This is normal until you submit your app for review. Products will work in sandbox despite this warning.

---

## Code Reference

The following files handle in-app purchases:

| File | Purpose |
|------|---------|
| `Shared/Premium/PremiumManager.swift` | RevenueCat integration, purchase logic, customer info listener |
| `Shared/Premium/PaywallPresenter.swift` | RevenueCat native Paywall with custom fallback |
| `Features/Paywall/Views/ProPaywallView.swift` | Custom fallback paywall UI |
| `Features/Onboarding/Views/OnboardingSoftPaywallView.swift` | Onboarding soft paywall |
| `Features/Settings/Views/SettingsView.swift` | Pro section with Customer Center |
| `Configuration/Secrets.xcconfig` | RevenueCat API key (not committed to git) |

The code checks for a single entitlement called `"Selfie Cam by TopDog Pro"`. All three products (monthly, yearly, lifetime) grant this same entitlement, so the app doesn't need to know which one the user purchased.

### RevenueCat Features Used

- **RevenueCat SDK** - Core purchase and subscription management
- **RevenueCatUI** - Native paywalls and Customer Center
- **PaywallView** - Remote-configurable paywall designed in RevenueCat dashboard
- **Customer Center** - Subscription management UI (view plan, cancel, request refund)