| name | app-store-submission |
| description | Apple App Store submission - review guidelines, metadata, privacy nutrition labels, encryption compliance, and common rejection patterns. Use when preparing a first or recurring submission. |
App Store Submission
Instructions
App Store review is a gate every iOS app crosses. Most rejections are avoidable by knowing the rules and preparing metadata deliberately. Plan submissions; do not discover review at the end.
1. Accounts and Signing
- Apple Developer Program membership (paid) and an enrolled team.
- App ID registered with the bundle identifier that matches the Xcode project.
- Distribution certificate and provisioning profile for App Store distribution.
- App Store Connect app record created with matching bundle ID before the first upload.
- Use automatic signing for small teams; manual signing with profiles checked into secure storage for larger ones. Do not commit
.p12 files to the repo.
2. App Store Connect Metadata
Required for every locale you list:
- App name (30 chars) and subtitle (30 chars).
- Promotional text (170 chars), editable without review.
- Description (4000 chars).
- Keywords (100 chars, comma-separated).
- Support URL and marketing URL.
- Screenshots for required display sizes (6.7", 6.5", 5.5", iPad 12.9" as applicable). One display size can cover others via up-scaling rules, but provide at least the 6.7" and iPad sizes explicitly.
- App preview videos (optional, 15-30s).
- Category (primary + optional secondary).
- Age rating via questionnaire.
- App icon 1024x1024 PNG, no transparency, no rounded corners.
Keep screenshots in a Figma/Sketch file under version control; update per release.
3. Privacy Nutrition Label
Since iOS 14.3, every app declares data collection in the "App Privacy" section. Inventory every SDK and backend:
| Data type | Collected? | Linked to user? | Tracking? | Purpose |
|---|
| Email | Yes | Yes | No | Auth, account |
| Device ID | Yes | No | No | Analytics |
| Crash data | Yes | No | No | App functionality |
Rules:
- Every SDK counts. Analytics, crash reporters, and ads in third-party SDKs add to your disclosures.
- "Linked to user" means it can be tied to identity post-transmission.
- "Tracking" specifically means combining with data for advertising or sharing with data brokers. Tracking requires App Tracking Transparency (ATT) prompt under
NSUserTrackingUsageDescription.
- Update the label when you add/remove SDKs. Discrepancies are a rejection reason and a regulatory risk.
4. Permission Purpose Strings
Every sensitive permission needs a clear purpose string in Info.plist:
<key>NSCameraUsageDescription</key>
<string>Used to scan barcodes when adding an item to your pantry.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Used to find stores near you while you browse.</string>
<key>NSUserTrackingUsageDescription</key>
<string>Allows us to show more relevant ads.</string>
Be specific, user-centered, and honest. Generic strings ("for features") are rejected.
5. Export Compliance
Answer the encryption questions accurately:
- Standard HTTPS use typically qualifies for the exemption (
ITSAppUsesNonExemptEncryption = false).
- Using custom crypto or proprietary protocols requires an ERN (Encryption Registration Number) and potentially US BIS filings.
- Declare in
Info.plist to skip the Connect questionnaire per build.
6. Common Rejection Reasons
- Guideline 2.1 (App Completeness): broken features, crashes on launch, placeholder text.
- Guideline 2.3 (Accurate Metadata): screenshots that do not match the app, misleading promotional text.
- Guideline 3.1.1 (In-App Purchase): unlocking digital features through external payment. Must use IAP unless a reader-app or alt-payments exception applies.
- Guideline 4.0 (Design): poor UX, broken layouts, not respecting platform conventions.
- Guideline 5.1.1 (Data Collection): mandatory sign-up with no option to use app first, missing privacy policy URL.
- Guideline 5.1.5 (Location): collecting location not needed for declared features.
- Sign in with Apple: required when you offer third-party sign-in providers that are primarily social/identity (Google, Facebook).
Write a short reviewer notes text with test credentials and reproduction steps for features behind auth.
7. Build Submission Flow
- Archive in Xcode or CI (
xcodebuild -archive -exportArchive) producing a signed .ipa.
- Upload with
altool, xcrun notarytool, or Transporter. Automated CI: GitHub Actions + fastlane pilot.
- Wait for processing (minutes to an hour) in TestFlight.
- Distribute to internal testers, validate smoke.
- Submit for review via App Store Connect. Attach release notes.
- Review typically under 24 hours; complex apps longer.
8. Phased Release
Use App Store Connect's Phased Release to deliver to 1% -> 2% -> 5% -> 10% -> 20% -> 50% -> 100% over seven days. Pair with server-side feature flags and crash monitoring; see staged-rollouts.
9. Post-Release Hygiene
- Respond to reviews within a few days. Public tone matters.
- Monitor crash-free sessions and escalate on breach.
- Keep TestFlight builds flowing for the next version; do not wait a month between submissions or store cadence skills atrophy.
10. Anti-Patterns
- Starting metadata the day of submission.
- SDKs added without privacy-label review.
- Permission strings that paraphrase the OS text ("Needs camera access").
- Submitting a build that has not been on TestFlight.
- Ignoring the phased release curve and pushing 100% on day one.
Checklist
