Overview: The Screenshot Pipeline from Simulator to Storefront
When preparing your iOS or macOS application for its initial App Store launch, visual screenshots represent your most influential storefront asset. According to Apple Developer specifications, your product page must feature localized screenshot sets for every supported device family.
For first-time developers and AI-assisted "vibe coders," navigating screenshot requirements can be daunting:
- Strict Pixel Dimensions: Apple enforces precise pixel dimensions for each device tier (such as
1320 x 2868for 6.9-inch iPhones or2064 x 2752for 13-inch iPads). Images that deviate by even a single pixel are rejected during upload. - Color Profile & Alpha Invariants: Screenshots must use 24-bit RGB PNG or high-quality JPEG format. Including transparency or alpha channels triggers immediate ingestion errors.
- Multiple Device Tiers: Supplying assets across multiple iPhone and iPad display sizes requires an orderly capture and upload process.
This guide provides an end-to-end beginner pipeline: capturing clean screenshots from booted iOS simulators via CLI, validating image formatting, and automating the upload into App Store Connect using FlightDeck MCP.
┌────────────────────────────────────────────────────────────────────────┐
│ LOCAL WORKSPACE (SIMULATOR & ASSETS) │
│ │
│ iOS Simulator ──► [ xcrun simctl io booted screenshot ] │
│ │ │
│ ▼ │
│ Raw Asset ──► [ Validate Dimensions & Strip Alpha ] │
│ │ │
│ ▼ │
│ Local File ──► screenshots/en-US/iphone_6_9/screen_01.png │
└───────────────────────────┬────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────────────┐
│ FLIGHTDECK MCP STAGING & UPLOAD │
│ │
│ AI Assistant Calls: [ app_screenshot_upload_plan ] (Read-Only) │
│ │ │
│ ▼ │
│ Desktop Approval Center ──► Human Inspects Thumbnail & Approves │
│ │ │
│ ▼ │
│ AI Assistant Calls: [ app_screenshot_upload_execute ] │
│ │ │
│ ▼ │
│ Direct Apple Storage ──► Uploaded via TLS 1.3 to Presigned S3/CDN │
│ │ │
│ ▼ │
│ Authoritative Polling ──► Waits until assetDeliveryState = COMPLETE │
└────────────────────────────────────────────────────────────────────────┘
Understanding Planning vs. Execution: In FlightDeck MCP, screenshot uploads follow a strict two-phase security model:
1. app_screenshot_upload_plan is 100% Read-Only and Local: It inspects your local image file (validating pixel dimensions, color profile, and alpha presence) and checks existing sets in App Store Connect. It makes zero mutations on Apple's servers, creates no screenshot containers, reserves no assets, and requires no desktop approval.
2. app_screenshot_upload_execute is the Mutating Step: It triggers the end-to-end upload workflow, prompting the developer for physical confirmation in the Desktop Approval Center. Once approved, FlightDeck creates the container set if needed, reserves the asset with Apple (POST /v1/appScreenshots), streams bytes directly to Apple's presigned upload URLs over HTTPS, commits the upload (PATCH /v1/appScreenshots/{id}), and polls Apple's backend until processing is COMPLETE.
Quick Answer: The 4-Step Screenshot Publishing Process
To publish screenshots to App Store Connect using your AI assistant and FlightDeck:
- Boot Target Simulator: Launch an iPhone 16 Pro Max simulator (for 6.9-inch display) or iPhone 15 Pro Max (for 6.7-inch display) in Xcode.
- Capture Clean Frames: Run
xcrun simctl io booted screenshot screen1.pngto capture native-resolution PNGs without simulator chrome. - Verify Dimensions and Alpha: Confirm the image matches Apple's required dimensions (e.g.,
1320 x 2868) and contains no 32-bit alpha channel. - Plan and Upload via FlightDeck: Ask your AI assistant to plan and stage the screenshot upload into your active App Store version draft, then click Approve in the FlightDeck Desktop Approval Center.
Copyable Prompts for Your AI Coding Assistant
1. Capture and Validate Simulator Screenshots
Use this prompt to have your assistant check booted simulators and inspect your local screenshots:
I need to prepare App Store screenshots for our upcoming iOS release:
1. Check the booted iOS simulator using `xcrun simctl list devices | grep Booted`.
2. Provide the shell command to capture a clean screenshot from the booted simulator to `screenshots/en-US/screen_01.png`.
3. Inspect the captured PNG using macOS `sips` to verify its width, height, and color profile.
4. Confirm whether the dimensions match Apple's required specifications for iPhone 6.9-inch (1320x2868) or 6.7-inch (1290x2796), and verify that there is no alpha channel.
2. Plan and Stage Screenshot Upload via FlightDeck
Once your screenshot images are captured and verified locally, use this prompt to stage the upload:
Please inspect our active App Store Connect draft version using FlightDeck:
1. Locate our English (U.S.) version localization and check its existing screenshot sets.
2. Prepare an upload plan for `screenshots/en-US/screen_01.png` targeting the iPhone 6.9-inch display set.
3. Show me the upload plan details (target version, display family, position, and local file path).
4. When ready, stage the execution so I can review the thumbnail in the Desktop Approval Center before transmitting to Apple.
3. Readback Verification of Uploaded Screenshots
After approving the upload in FlightDeck Desktop:
Please query App Store Connect via FlightDeck to perform an authoritative readback of our screenshot sets for English (U.S.). Confirm that Apple has accepted the new screenshot, report its asset delivery state, and show the total number of screenshots currently in the set.
Required App Store Screenshot Dimensions
Apple requires developers to provide screenshots for the primary screen sizes of supported devices. Up to 10 screenshots may be uploaded per display set. At minimum, an iPhone app requires screenshots for the largest current iPhone tier; Apple automatically scales these images down for smaller screen sizes in the App Store.
| Device Tier | Target Devices | Portrait Dimensions | Landscape Dimensions | Display Type Enum |
|---|---|---|---|---|
| 6.9-inch Super Retina | iPhone 16 Pro Max | 1320 x 2868 px |
2868 x 1320 px |
APP_IPHONE_69 |
| 6.7-inch Super Retina | iPhone 15 Pro Max, 14 Pro Max | 1290 x 2796 px |
2796 x 1290 px |
APP_IPHONE_67 |
| 6.5-inch Super Retina | iPhone 11 Pro Max, XS Max | 1242 x 2688 px |
2688 x 1242 px |
APP_IPHONE_65 |
| 5.5-inch Retina | iPhone 8 Plus, 7 Plus | 1242 x 2208 px |
2208 x 1242 px |
APP_IPHONE_55 |
| 13-inch Liquid Retina | iPad Pro (M4) | 2064 x 2752 px |
2752 x 2064 px |
APP_IPAD_PRO_3GEN_129 |
| 12.9-inch Liquid Retina | iPad Pro 12.9-inch (3rd–6th gen) | 2048 x 2732 px |
2732 x 2048 px |
APP_IPAD_PRO_3GEN_129 |
For a comprehensive reference of all supported iPad, Apple Watch, Apple TV, and Mac screenshot sizes, see our dedicated guide: App Store Screenshot Sizes and Dimensions: Complete Guide.
Step-by-Step Implementation Workflow
sequenceDiagram
autonumber
actor Dev as Developer
participant Sim as iOS Simulator
participant AI as AI Assistant (IDE)
participant FD as FlightDeck MCP
participant Apple as Apple App Store Connect
Dev->>Sim: Launches App in iPhone 16 Pro Max
Dev->>AI: "Capture screenshot and upload to App Store Connect"
AI->>Sim: xcrun simctl io booted screenshot screen1.png
Sim-->>AI: Captures 1320x2868 PNG
AI->>AI: Validates 24-bit RGB (zero alpha)
AI->>FD: app_screenshot_upload_plan(filePath: "...")
Note over FD: Inspects local file (read-only)<br/>Validates dimensions & format
FD-->>AI: Upload Plan generated (Zero mutations)
AI-->>Dev: "Plan valid. Ready to execute upload."
Dev->>AI: "Execute upload"
AI->>FD: app_screenshot_upload_execute(...)
Note over FD: Desktop Approval Center prompts developer
Dev->>FD: Reviews image preview in Desktop GUI & clicks [Approve]
FD->>Apple: POST /v1/appScreenshots (Reserves asset)
Apple-->>FD: Returns presigned upload operations
FD->>Apple: Streams image chunks directly via HTTPS
FD->>Apple: PATCH /v1/appScreenshots/{id} (uploaded: true)
FD->>Apple: Polls assetDeliveryState until COMPLETE
Apple-->>FD: Processing COMPLETE
FD-->>Dev: Screenshot upload complete
Step 1: Booting the Target Simulator and Capturing
Open your terminal or ask your assistant to identify booted simulators:
# Check running simulator devices
xcrun simctl list devices | grep "(Booted)"
# Capture full-resolution screenshot without window borders
xcrun simctl io booted screenshot screenshots/screen_01.png
Step 2: Validating Image Specifications with macOS sips
Before attempting upload, verify the pixel dimensions and transparency:
# Query image width and height
sips -g pixelWidth -g pixelHeight screenshots/screen_01.png
# Query alpha channel presence
sips -g hasAlpha screenshots/screen_01.png
If hasAlpha returns yes, strip the alpha channel using ImageMagick:
magick screenshots/screen_01.png -background white -alpha remove -alpha off png24:screenshots/screen_01_noalpha.png
Or convert to high-quality JPEG using native macOS sips:
sips -s format jpeg -s formatOptions 95 screenshots/screen_01.png --out screenshots/screen_01_clean.jpg
Step 3: Planning the Upload in FlightDeck MCP
Your AI assistant calls app_screenshot_upload_plan:
{
"appId": "6812899314",
"versionId": "ver_draft_12345",
"localizationId": "loc_en_us_67890",
"screenshotDisplayType": "APP_IPHONE_69",
"filePath": "/Users/developer/project/screenshots/screen_01_noalpha.png",
"desiredPosition": 1,
"why": "Uploading primary onboarding screen for English storefront"
}
FlightDeck evaluates local file existence, verifies that pixel dimensions match APP_IPHONE_69 rules, confirms that the target App Store version is in an editable draft state, and returns a verified upload plan without performing any mutations on Apple's servers.
Step 4: Physical Approval and Execution in FlightDeck Desktop
When the assistant calls app_screenshot_upload_execute:
- The Approval Center in FlightDeck Desktop surfaces an App Screenshot Upload card showing the rendered thumbnail, target device family, target locale, file size, and intended position.
- Click Approve. FlightDeck creates the asset reservation with Apple, streams the image chunks directly to Apple's storage endpoint over TLS 1.3, commits the asset, and polls Apple's backend until processing is
COMPLETE.
Authoritative Readback Verification
To verify that Apple has received and processed your screenshot:
Please inspect our English (U.S.) screenshot set for the iPhone 6.9-inch display type using FlightDeck. Confirm that the screenshot is in the set and report Apple's asset delivery status.
The assistant calls app_screenshots_list(localizationId: "...") and displays the live list of screenshot records:
Screenshot Set: APP_IPHONE_69 (English U.S.)
Total Screenshots: 1 / 10
Screenshot 1:
- ID: scr_abc123xyz
- File Name: screen_01_noalpha.png
- Dimensions: 1320 x 2868
- Asset Delivery State: COMPLETE
Troubleshooting Common Screenshot Upload Errors
1. "The image dimensions are not valid for this display type"
- Cause: Uploading an image whose pixel width or height differs from Apple's strict requirements (e.g., uploading a
1170 x 2532image to anAPP_IPHONE_69set). - Fix: Check simulator resolution before capturing. If capturing on a physical device with Display Zoom enabled, the captured pixels may not match standard specifications. Use an official Xcode simulator for clean native resolutions.
2. "Screenshots cannot contain alpha channels"
- Cause: The PNG file contains an uncompressed 32-bit RGBA channel, even if all pixels are fully opaque.
- Fix: Strip the alpha channel using
magick input.png -background white -alpha remove -alpha off png24:output.pngor save as high-quality baseline JPEG. See our detailed guide: Fixing 'Screenshots Cannot Contain Alpha Channels' Error in App Store Connect.
3. "Maximum number of screenshots exceeded"
- Cause: Apple limits each screenshot set to exactly 10 screenshots.
- Fix: Check current screenshot count with
app_screenshots_list. Delete outdated screenshots before uploading replacements. See Deleting App Store Screenshots Safely via MCP Tooling.
Security & Verification Safeguards
- Direct Storage Streaming: Image binary bytes stream directly between your local Mac and Apple's presigned storage endpoint. FlightDeck runs no intermediate cloud proxy or media storage servers.
- Path Traversal Protection: FlightDeck strictly validates local file paths passed to
app_screenshot_upload_plan, rejecting relative paths or directory traversal attempts (../). - Human-in-the-Loop Confirmation: No image asset is uploaded to Apple without an explicit physical click on the Desktop Approval Center card.
- Automated Compensation Cleanup: If byte streaming or asset commitment fails halfway through, FlightDeck automatically cleans up the orphaned Apple reservation so incomplete assets never corrupt the screenshot set.
Official Documentation & Related Guides
Official Apple Documentation
- App Store Connect Help: Screenshot Specifications
- App Store Product Page: Screenshots and App Previews
- App Store Connect API: App Screenshots