---
name: ios-app-store-submission
description: Complete workflow for submitting iOS apps to the Apple App Store. Use when preparing an Xcode project for App Store submission, resolving code signing issues, creating Apple Developer certificates, configuring provisioning profiles, capturing App Store screenshots, or navigating App Store Connect. Covers the full process from development certificate setup through final submission.
---

# iOS App Store Submission

## Prerequisites

- **Apple Developer Program membership** ($99/year) - verify at developer.apple.com/account
- **Xcode** installed from Mac App Store
- **Completed iOS app** in an Xcode project (.xcodeproj)
- **App Icon**: 1024x1024 PNG image (no transparency)
- **Privacy Policy URL**: Hosted webpage (can use GitHub Pages)

## Step 1: Verify Apple Developer Account

1. Go to [developer.apple.com/account](https://developer.apple.com/account)
2. Sign in with your Apple ID
3. Confirm membership is active (check expiration date)
4. Note your **Team ID** (format: 10 alphanumeric characters, e.g., RFNE8Z89E4)

## Step 2: Create Development Certificate

**This step is critical** - Xcode often fails to retrieve team information without a manually-created certificate. Simply signing into Xcode with your Apple ID is often not enough.

### Create Certificate Signing Request (CSR)

1. Open **Keychain Access** (Cmd+Space, type "Keychain Access")
2. If prompted about Passwords app, click **Open Keychain Access**
3. Menu: **Keychain Access > Certificate Assistant > Request a Certificate From a Certificate Authority**
4. Fill in:
   - User Email Address: your Apple ID email
   - Common Name: your name
   - CA Email Address: leave blank
   - Request is: select **Saved to disk**
5. Click **Continue** and save the .certSigningRequest file

### Upload CSR to Apple

1. Go to [developer.apple.com/account/resources/certificates/list](https://developer.apple.com/account/resources/certificates/list)
2. Click **+** to create new certificate
3. Select **Apple Development** (universal development certificate for iOS/iPadOS/macOS/etc.)
4. Click **Continue**
5. Click **Choose File** and upload your .certSigningRequest file
6. Click **Continue**
7. Click **Download** to get the .cer file (named `development.cer`)
8. **Double-click** the downloaded .cer file to install in Keychain
9. When prompted, select **login** keychain and click **Add**

## Step 3: Create Distribution Certificate

Repeat the process above, but select **Apple Distribution** instead of Apple Development. You can reuse the same CSR file. This certificate is required for App Store uploads.

## Step 4: Configure Xcode Signing

### Add Apple Account to Xcode

1. Open Xcode
2. Menu: **Xcode > Settings > Accounts** (or Cmd+,)
3. Click **+** in bottom left
4. Select **Apple ID**
5. Sign in with your Apple Developer account
6. Your team should appear under "Teams" with "Admin" role

### Configure Project Signing

1. Open your .xcodeproj file
2. Select your project in the navigator (blue icon at top)
3. Select your app target
4. Go to **Signing & Capabilities** tab
5. Check **Automatically manage signing**
6. Click **Team** dropdown and select your team name
7. Verify:
   - Provisioning Profile shows "Xcode Managed Profile"
   - Signing Certificate shows "Apple Development: Your Name"
   - No errors in Status

### Troubleshooting: Team Not Appearing

If "Add Account..." button appears instead of your team dropdown:

1. **First**: Ensure you completed Step 2 (certificate creation and installation)
2. Go to **Xcode > Settings > Accounts**
3. Remove your account (select it, click **-**)
4. Re-add your account (click **+**, sign in)
5. Return to Signing & Capabilities - team should now appear

Alternative: Toggle "Automatically manage signing" off, wait 5 seconds, then on again (may need multiple attempts).

## Step 5: Configure App Identity

### Bundle Identifier

In **Signing & Capabilities**:
- Set Bundle Identifier to: `com.yourname.YourAppName`
- Use reverse domain notation
- No spaces, use camelCase or hyphens
- Example: `com.duncancarlsmith.NewtonsCradleUnbound`

### Display Name

In **General** tab:
- Set Display Name to your app name (can include spaces, apostrophes, commas)
- Example: `Newton's Cradle, Unbound`

## Step 6: Add App Icon

Your app **must** have an icon or upload will fail with "Missing required icon file" errors.

### Required Size
- **1024x1024 pixels**, PNG format, no transparency

### Adding Icon to Xcode

1. In Xcode Project Navigator (left sidebar), click **Assets** (or Assets.xcassets)
2. Select **AppIcon**
3. Drag your 1024x1024 PNG onto the icon slot
4. Modern Xcode uses a single 1024x1024 image and generates all sizes automatically

### Creating an Icon from SVG

If you have an SVG logo (e.g., from your website), convert to 1024x1024 PNG:
- Scale up the SVG viewBox proportionally to 1024x1024
- Add a solid background color (no transparency allowed for App Store)
- Use Python with cairosvg: `cairosvg.svg2png(url='icon.svg', write_to='AppIcon.png', output_width=1024, output_height=1024)`
- Or use online tools like [appicon.co](https://appicon.co)

## Step 7: Capture App Store Screenshots

### Required Sizes (2024+)

| Device | Resolution | Simulator to Use |
|--------|------------|------------------|
| iPhone 6.9" | 1320 x 2868 | iPhone 17 Pro Max |
| iPhone 6.5" | 1242 x 2688 | iPhone 11 Pro Max (older iOS runtime) |
| iPad 13" | 2064 x 2752 | iPad Pro 13-inch (M5) |

**Note**: App Store Connect's Media Manager lets you choose which size to upload. Use 6.9" for iPhones if your Xcode only has newer simulators.

### Clean Status Bar Before Screenshots

Run in Terminal while simulator is active:

```bash
xcrun simctl status_bar booted override --time "9:41" --batteryState charged --batteryLevel 100 --wifiMode active --wifiBars 3 --cellularMode active --cellularBars 4
```

If you get an error about command line tools:
```bash
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
```

### Capture Screenshots

1. Run your app in the simulator
2. Navigate to the screen you want to capture
3. Press **Cmd+S** in Simulator
4. Screenshots save to Desktop as PNG files
5. Capture 3-10 screenshots per device size (first 3 appear on install sheets)

## Step 8: Register App ID

Before creating the App Store listing, register your Bundle ID:

1. Go to [developer.apple.com/account/resources/identifiers/list](https://developer.apple.com/account/resources/identifiers/list)
2. Click **+** to register new identifier
3. Select **App IDs**, click Continue
4. Select **App**, click Continue
5. Fill in:
   - **Description**: Your app name (no special characters like apostrophes or commas)
   - **Bundle ID**: Select "Explicit", enter your bundle ID (e.g., `com.duncancarlsmith.NewtonsCradleUnbound`)
6. **Capabilities**: Leave all unchecked for simple apps
7. Click **Continue**, then **Register**

## Step 9: Create App Store Connect Listing

1. Go to [appstoreconnect.apple.com](https://appstoreconnect.apple.com)
2. Click **Apps**
3. Click **+** and select **New App**
4. Fill in:
   - **Platform**: iOS
   - **Name**: Your app name (30 chars max, must be unique on App Store)
   - **Primary Language**: English (U.S.)
   - **Bundle ID**: Select from dropdown (your registered ID from Step 8)
   - **SKU**: Unique identifier (e.g., `newtons-cradle-unbound-001`)
   - **User Access**: Full Access
5. Click **Create**

## Step 10: Complete App Store Metadata

### Version Information (scroll down on main page)

**Previews and Screenshots**:
- Click **iPhone** tab, upload iPhone screenshots
- Click **iPad** tab, upload iPad screenshots
- Use **View All Sizes in Media Manager** to select 6.9" display if needed

**Promotional Text** (170 chars, optional, can update anytime):
```
Experience Newton's Cradle without constraints - watch balls collide and transfer momentum in any direction on a 2D plane.
```

**Description** (4000 chars max, required):
```
Explore the physics of Newton's Cradle in a whole new way. Unlike traditional cradles where balls swing in a single line, this simulation lets them move freely in any direction on a horizontal plane.

Watch momentum and energy transfer through collisions as you experiment with different configurations. Pull balls to any position and release them to see the physics unfold.

Features:
- Realistic physics simulation with adjustable parameters
- Multiple ball configurations and lattice arrangements
- Real-time statistics showing energy and momentum
- Simple, intuitive touch controls

Perfect for physics students, educators, or anyone curious about classical mechanics.
```

**Keywords** (100 chars max, comma-separated):
```
physics,newton,cradle,simulation,momentum,energy,collision,pendulum,education,science
```

**Support URL**: Your privacy policy URL (e.g., `https://yourusername.github.io/your-app-privacy/`)

**Marketing URL**: Optional, leave blank

**Version**: `1.0`

**Copyright**: `2025 Your Name`

### App Information (left sidebar > General > App Information)

**Category**:
- Primary: `Education` (or `Entertainment`)
- Secondary: Optional

**Content Rights**: Click "Set Up Content Rights Information"
- Select **No** (your app doesn't contain third-party content)
- Click **Save**

**Age Rating**: Click "Edit" and answer questionnaire
- For a simple physics simulation, answer **None** to all violence/mature content questions
- Answer **No** to all capabilities (web access, user content, messaging, ads)
- Result should be **4+** rating

### App Review (left sidebar > General > App Review)

**Contact Information**:
- First Name, Last Name, Phone, Email

**Notes for Reviewer**:
```
No login required. Launch the app and tap any ball to drag it, then release to see the physics simulation.
```

**Sign-in Required**: No (leave unchecked)

### App Privacy (left sidebar > App Store > App Privacy)

**IMPORTANT**: This section has TWO parts that must both be completed:

1. **Privacy Policy URL**: Enter your privacy policy URL
2. **Data Collection Questionnaire**: 
   - Click **Get Started** or **Edit**
   - Select **No, we do not collect data from this app**
   - Complete the questionnaire
   - **Click "Publish" button** in top right to save (this is easy to miss!)

The "Publish" button must be clicked or your privacy settings won't be saved.

### Pricing and Availability (left sidebar)

- **Price**: Free (or select price tier)
- **Availability**: All countries (default)

## Step 11: Build and Upload

### Archive the App

1. In Xcode, select **Any iOS Device (arm64)** as build target (not a simulator)
2. Menu: **Product > Archive**
3. When prompted about Xcode Cloud, click **Remind Me Later** (not needed for simple submissions)
4. When prompted for keychain access ("codesign wants to sign..."), enter your Mac password and click **Always Allow**
5. Wait for build to complete
6. Organizer window opens automatically

### Upload to App Store Connect

1. In Organizer, select your archive (newest one by timestamp)
2. Click **Distribute App**
3. Select **App Store Connect**
4. Click **Distribute**
5. Keep default options, click **Next**/**Upload**
6. Wait for upload to complete (shows green checkmark when done)
7. Click **Done**

### Common Upload Errors

**Missing app icon**: 
- Error: "Missing required icon file. The bundle does not contain an app icon..."
- Solution: Add 1024x1024 PNG to Assets.xcassets > AppIcon, then archive again

**Missing CFBundleIconName**:
- Error: "Missing Info.plist value for CFBundleIconName"
- Solution: Same fix - add icon to asset catalog and re-archive

**Signing errors**: Ensure both Development and Distribution certificates are installed in Keychain.

## Step 12: Select Build and Submit

### Wait for Processing

After upload, wait 15-30 minutes for Apple to process your build.

### Add Build to Release

1. Go to [appstoreconnect.apple.com](https://appstoreconnect.apple.com)
2. Select your app
3. Click **iOS App** > **1.0 Prepare for Submission** in left sidebar
4. Scroll to **Build** section
5. Click **Add Build** button
6. Select your build (will show your app icon and "Missing Compliance" warning)
7. Click **Done**

### Handle Export Compliance

1. Click **Manage** next to "Missing Compliance"
2. Answer: "Does your app use encryption?" - **No** (for simple apps without custom encryption or networking)
3. Click **Save**

### Submit for Review

1. Click **Save** in top right
2. Click **Add for Review**
3. If you see "Unable to Add for Review" errors, complete any missing items:
   - Content Rights in App Information
   - Privacy Policy URL in App Privacy
   - Data collection questionnaire in App Privacy (must click **Publish**)
   - Primary category in App Information
4. Once all items complete, click **Add for Review** again
5. In the "Draft Submission" dialog, click **Submit for Review**

## Post-Submission

- Status changes to "Waiting for Review"
- Review typically takes 24-48 hours (can be faster)
- You'll receive email notifications about status changes:
  - "Waiting for Review" → "In Review" → "Ready for Distribution"
- If rejected, you'll get specific feedback on what to fix
- Once approved, app goes live automatically (or on date you specify)

## Apple Trademark Guidelines

When marketing your app:

- **Do NOT use** Apple logos without written permission
- **Allowed**: Apple word marks in text (iPhone, iPad, iOS) for compatibility statements
- **Official badge**: After publication, use Apple's official "Download on the App Store" badge only
- Download official assets: [developer.apple.com/app-store/marketing/guidelines/](https://developer.apple.com/app-store/marketing/guidelines/)

## File Locations Reference

- Certificates: **Keychain Access** app > login keychain > My Certificates
- CSR file: Saved where you chose during creation (e.g., Desktop or Documents)
- Downloaded .cer files: Usually in Downloads folder
- Provisioning Profiles: `~/Library/MobileDevice/Provisioning Profiles/`
- Archives: `~/Library/Developer/Xcode/Archives/`
- Derived Data: `~/Library/Developer/Xcode/DerivedData/`

## Useful URLs

| Resource | URL |
|----------|-----|
| Apple Developer Account | developer.apple.com/account |
| App Store Connect | appstoreconnect.apple.com |
| Certificates Portal | developer.apple.com/account/resources/certificates |
| Identifiers Portal | developer.apple.com/account/resources/identifiers |
| Screenshot Specs | developer.apple.com/help/app-store-connect/reference/screenshot-specifications |
| Marketing Guidelines | developer.apple.com/app-store/marketing/guidelines |
| System Status | developer.apple.com/system-status |

## Checklist Summary

Before submitting, verify:

- [ ] Development certificate created and installed
- [ ] Distribution certificate created and installed
- [ ] Xcode signing configured (team selected, no errors)
- [ ] App icon added (1024x1024 PNG in Assets.xcassets)
- [ ] Bundle ID registered at developer.apple.com
- [ ] App created in App Store Connect
- [ ] Screenshots uploaded (iPhone and iPad)
- [ ] Description, keywords, URLs entered
- [ ] Content Rights set (App Information)
- [ ] Category selected (App Information)
- [ ] Age rating completed
- [ ] App Review contact info provided
- [ ] Privacy Policy URL entered (App Privacy)
- [ ] Data collection questionnaire completed AND **Published** (App Privacy)
- [ ] Build uploaded from Xcode
- [ ] Build selected in App Store Connect
- [ ] Export compliance answered

## Glossary

- **Bundle ID**: Unique identifier for your app (e.g., com.yourname.appname)
- **SKU**: Stock Keeping Unit - your internal reference number for the app
- **Team ID**: Your Apple Developer account identifier (10 characters)
- **CSR**: Certificate Signing Request - file generated by Keychain Access
- **Provisioning Profile**: Links your app, certificates, and devices
- **Archive**: Compiled, signed version of your app ready for distribution
- **Export Compliance**: US government requirement about encryption in software