`XCODE_AND_APPSTORE_GUIDE.md`

302 lines

# Xcode and App Store Deployment Guide for Boomer Calc

This guide will walk you through opening your app in Xcode and deploying it to the App Store.

## Prerequisites

- **Mac computer** with macOS (required for Xcode)
- **Xcode** installed (download from Mac App Store)
- **Apple Developer Account** ($99/year - https://developer.apple.com)
- **CocoaPods** installed (run `sudo gem install cocoapods` if needed)

## Step 1: Prepare Your Project

1. **Rebuild the app** to ensure latest changes are synced:
```bash
npm run build
npx cap sync ios
```

2. **Install iOS dependencies**:
```bash
cd ios/App
pod install
cd ../..
```

## Step 2: Open Project in Xcode

1. Open the Xcode workspace (NOT the .xcodeproj file):
```bash
open ios/App/App.xcworkspace
```

Or from Xcode: File → Open → Navigate to `ios/App/App.xcworkspace`

## Step 3: Configure Your App in Xcode

### 3.1 Select Your Project Target

1. Click on "App" in the left sidebar (project navigator)
2. Select the "App" target under TARGETS

### 3.2 Set Bundle Identifier

1. Go to the "Signing & Capabilities" tab
2. **Bundle Identifier**: Currently set to `com.boomercalc.app`
- You can change this to your own domain (e.g., `com.yourcompany.boomercalc`)
- Must be unique across the App Store
- Note: If you change it here, also update `capacitor.config.ts` in the root

### 3.3 Configure Signing

1. Under "Signing & Capabilities" tab:
- Check "Automatically manage signing"
- Select your **Team** (your Apple Developer Account)
- Xcode will automatically create provisioning profiles

### 3.4 Set Version and Build Number

1. Go to the "General" tab
2. **Version**: Set to your app version (e.g., `1.0.0`)
3. **Build**: Set to a build number (e.g., `1`)
- Increment this for each submission to App Store

### 3.5 Set Deployment Target

1. Still in "General" tab
2. **Minimum Deployments**: Recommended iOS 13.0 or higher
3. **Supported Destinations**: Check iPhone and iPad as needed

## Step 4: Configure App Icons

Your app icons are located in `ios/App/App/Assets.xcassets/AppIcon.appiconset/`

**Current Status**: You have a 1024x1024 icon ready to use.

### To update icons:

1. In Xcode, click on `Assets.xcassets` in the project navigator
2. Click on `AppIcon`
3. Drag and drop your 1024x1024 PNG icon into the "App Store iOS" slot
4. Xcode can generate other sizes automatically, or you can provide specific sizes

### Icon Requirements:
- Must be PNG format
- Must be square (1:1 aspect ratio)
- No transparency
- Main icon: 1024x1024 pixels

## Step 5: Configure Info.plist Settings

Already configured in your project:
- ✓ App Display Name: "Boomer Calc"
- ✓ Privacy descriptions (required by App Store)
- ✓ Encryption settings
- ✓ Supported orientations

## Step 6: Test on Simulator

1. Select a simulator from the device dropdown (top left in Xcode)
- Example: "iPhone 15 Pro"
2. Click the Play button (▶) or press `Cmd + R`
3. The app should build and launch in the simulator

## Step 7: Test on Physical Device

1. Connect your iPhone/iPad via USB
2. Select your device from the device dropdown
3. Trust your device if prompted
4. Click Play (▶) to build and run on device
5. On your device: Settings → General → VPN & Device Management → Trust your developer certificate

## Step 8: Prepare for App Store Submission

### 8.1 Create App Store Listing in App Store Connect

1. Go to https://appstoreconnect.apple.com
2. Click "My Apps" → "+" → "New App"
3. Fill in:
- **Platform**: iOS
- **Name**: Boomer Calc (or your desired name)
- **Primary Language**: English
- **Bundle ID**: Select `com.boomercalc.app` (or your custom one)
- **SKU**: Unique identifier (e.g., `boomercalc001`)
- **User Access**: Full Access

### 8.2 Prepare App Metadata

You'll need to provide:

**Required Screenshots** (use iPhone/iPad simulators):
- 6.7" iPhone (iPhone 15 Pro Max): Minimum 1-10 screenshots
- 12.9" iPad Pro (if supporting iPad): Minimum 1-10 screenshots
- Take screenshots: Cmd + S in simulator

**App Information**:
- **Name**: Boomer Calc
- **Subtitle**: Simple calculator for quick math
- **Description**:
```
Boomer Calc is a clean, no-frills calculator designed for simplicity and ease of use.

Features:
• Clean, minimal interface
• Basic arithmetic operations
• Large, easy-to-read buttons
• Instant calculations
• No ads, no tracking

Perfect for quick calculations without unnecessary complexity.
```

- **Keywords**: calculator, math, simple, basic, arithmetic
- **Support URL**: Your website or support page
- **Marketing URL**: (optional)
- **Privacy Policy URL**: Required if you collect data (you can create a simple one stating you don't collect data)

**Pricing**:
- Free or Paid (you choose)

**App Review Information**:
- Contact information
- Demo account (if login required - not applicable for this app)
- Notes for reviewer (e.g., "Simple calculator app, no special features to test")

### 8.3 Prepare Privacy Nutrition Label

App Store requires privacy details:
- For this app: Select "No, this app does not collect data" (since it's a simple calculator)

## Step 9: Archive and Upload to App Store

### 9.1 Create Archive

1. In Xcode, select "Any iOS Device (arm64)" from device dropdown
2. Menu: Product → Archive
3. Wait for build to complete (may take several minutes)
4. Xcode Organizer will open showing your archive

### 9.2 Validate Archive

1. In Organizer, select your archive
2. Click "Validate App"
3. Select your distribution certificate and provisioning profile
4. Fix any errors that appear
5. Wait for validation to complete

### 9.3 Upload to App Store Connect

1. In Organizer, select your archive
2. Click "Distribute App"
3. Select "App Store Connect"
4. Click "Upload"
5. Select automatic signing
6. Review information and click "Upload"
7. Wait for upload to complete (may take 10-30 minutes)

### 9.4 Submit for Review

1. Go back to App Store Connect
2. Select your app → Version → Build
3. Click the "+" next to Build and select your uploaded build
4. Fill in "What's New in This Version" (e.g., "Initial release")
5. Complete all required metadata
6. Click "Save"
7. Click "Submit for Review"

### 9.5 Export Compliance

When submitting, you'll be asked about encryption:
- Answer "No" if your app doesn't use encryption beyond HTTPS
- Your Info.plist already has `ITSAppUsesNonExemptEncryption: false` configured

## Step 10: After Submission

1. **Review Time**: Usually 24-48 hours, can take up to 7 days
2. **Status Updates**: You'll receive emails about status changes
3. **Possible Outcomes**:
- ✅ Approved: Your app is live!
- ❌ Rejected: Review feedback and resubmit
- ⚠️ Metadata Rejected: Fix app details and resubmit
- ⏸️ Developer Action Needed: Respond to reviewer questions

## Step 11: After Approval

Once approved:
- Your app goes live automatically (or at scheduled time if you set one)
- You can download it from the App Store
- Share the App Store link with users

## Updating Your App

When you need to release an update:

1. Make your code changes
2. Increment version/build number in Xcode
3. Rebuild and sync: `npm run build && npx cap sync ios`
4. Archive and upload new build
5. In App Store Connect, create a new version
6. Add "What's New" description
7. Submit for review

## Troubleshooting

### Common Issues:

**"No accounts with App Store Connect access"**
- Solution: Add your Apple Developer account in Xcode → Settings → Accounts

**"Failed to create provisioning profile"**
- Solution: Ensure Bundle ID is unique and registered in your Apple Developer account

**"Missing compliance information"**
- Solution: Answer export compliance questions in App Store Connect

**"Missing required icon"**
- Solution: Ensure 1024x1024 icon is in AppIcon asset catalog

**Build fails with CocoaPods errors**
- Solution: Run `cd ios/App && pod deintegrate && pod install`

**"Code signing error"**
- Solution: Clean build folder (Cmd + Shift + K) and rebuild

## Additional Resources

- **Apple Developer Documentation**: https://developer.apple.com/documentation/
- **App Store Review Guidelines**: https://developer.apple.com/app-store/review/guidelines/
- **App Store Connect Help**: https://developer.apple.com/help/app-store-connect/
- **Human Interface Guidelines**: https://developer.apple.com/design/human-interface-guidelines/

## Your App Configuration Summary

- **App Name**: Boomer Calc
- **Bundle ID**: com.boomercalc.app
- **Version**: 1.0.0 (set in Xcode)
- **Icons**: ✓ Configured
- **Privacy Settings**: ✓ Configured
- **Capacitor**: ✓ Configured
- **Web Directory**: out/

## Quick Commands Reference

```bash
# Rebuild and sync to iOS
npm run build && npx cap sync ios

# Open in Xcode
open ios/App/App.xcworkspace

# Update iOS dependencies
cd ios/App && pod install && cd ../..

# Update Capacitor
npm install @capacitor/cli@latest @capacitor/core@latest @capacitor/ios@latest
npx cap sync ios
```

---

**Ready to submit?** Follow the steps above in order, and you'll have your app in the App Store! Good luck! 🚀