capacitor-app-store

Files (5)

• SKILL.md
• metadata.json
• android-submission.md · references/
• assets-and-metadata.md · references/
• ios-submission.md · references/

SKILL.md (first lines)

# Publishing Capacitor Apps to the Stores

Get a Capacitor build from "runs on my device" to "live in both stores" without avoidable upload or review failures.

## When to Use

TRIGGER when:
- The user is preparing a first release or an update to App Store Connect or Google Play Console.
- Upload or processing fails (ITMS errors, Play Console version/target API errors).
- The user needs screenshot sizes, icon requirements, listing fields, privacy forms, or rollout options.
- The user asks which Xcode/SDK or target API level the stores require right now.

Do not use for:
- Auditing an app against App Review Guidelines or answering a rejection -> `capacitor-apple-review-preflight`.
- Writing GitHub Actions/GitLab/Fastlane pipelines -> `capacitor-ci-cd`.
- Building/signing in Capgo Cloud -> `capgo-native-builds`.
- Shipping web-only fixes after approval -> `capgo-live-updates`.

## Live Project Snapshot

Capacitor packages and version:
!`node -e "const fs=require('fs');if(!fs.existsSync('package.json'))process.exit(0);const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));const out=['version='+(pkg.version||'')];for(const section of ['dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name.startsWith('@capacitor/')||name==='@capgo/capacitor-updater'||name==='@capacitor/assets')out.push(section+'.'+name+'='+version)}}console.log(out.join('\n'))"`

Native release files:
!`find . -maxdepth 5 -not -path '*/node_modules/*' \( -name 'Info.plist' -o -name 'PrivacyInfo.xcprivacy' -o -name '*.entitlements' -o -name 'SceneDelegate.swift' -o -name 'variables.gradle' -o -name 'build.gradle' -o -name 'ExportOptions.plist' -o -path './fastlane' \)`

## Current Store Requirements (October 2026)

| Requirement | Detail | Capacitor impact |
|---|---|---|
| Apple SDK minimum | Since April 28, 2026: built with Xcode 26+ and iOS 26 SDK. Starting April 2027: iOS 27 SDK (Xcode 27) | Capacitor 8 builds with Xcode 26; Xcode 27 needs Capacitor 8.5+ project changes |
| UIScene lifecycle | Xcode 27 / iOS 27 SDK builds require the scene lifecycle | Capacitor 8.5+: add `SceneDelegate.swift`, `UIApplicationSceneManifest`, AppDelegate `configurationForConnecting` (see `capacitor-app-upgrades`) |
| Privacy manifest | Required-reason APIs must be declared; listed third-party SDKs must ship their own signed manifests | Capacitor core and maintained plugins ship manifests; your app still needs its own `PrivacyInfo.xcprivacy` |
| Apple age rating | New questionnaire with 13+, 16+, 18+ tiers; answers were due Jan 31, 2026 or updates are blocked | Answer in App Store Connect -> App Information -> Age Ratings |
| Play target API | Since Aug 31, 2026 new apps and updates must target API 36 (extension to Nov 1, 2026 on request); existing apps below API 35 stop reaching new users on newer devices | Capacitor 8 templates use compile/target 36; Capacitor 9 uses 37 |
| Play format | New apps must upload AAB with Play App Signing | `./gradlew bundleRelease` |
| 16 KB page size | Apps targeting Android 15+ with native `.so` libraries must be 16 KB aligned | Check SQLCipher, ML, media, and analytics SDKs |
| Play closed testing | Personal accounts created after Nov 13, 2023: closed test with 12+ opted-in testers for 14 consecutive days before production | Start the test early |

Re-verify dates when the user is close to a deadline: Apple posts at developer.apple.com/news/upcoming-requirements, Google at developer.android.com/google/play/requirements/target-sdk.

## Procedure

1. Read the snapshot. Confirm Capacitor version, iOS scene lifecycle (look for `SceneDelegate.swift`), `variables.gradle` SDK values, and whether a privacy manifest exists.
2. Decide the release path with the user: manual (Xcode Organizer + Play Console), CLI/CI (`capacitor-ci-cd`), or Capgo Cloud Build (`capgo-native-builds`).
3. Bump versions. User-visible version must match on both platforms; build numbers must strictly increase per upload:
   - iOS: `MARKETING_VERSION` (CFBundleShortVersionString) and `CURRENT_PROJECT_VERSION` (CFBundleVersion) in the Xcode target build settings. `Info.plist` normally references `$(MARKETING_VERSION)`/`$(CURRENT_PROJECT_VERSION)`; edit build settings, not the plist literal.
   - Android: `versionName` and `versionCode` in `android/app/build.gradle` (`versionCode` max 2100000000).
4. Build web assets and sync: `npm run build && npx cap sync`.
5. Load the platform reference and follow it: `references/ios-submission.md`, `references/android-submission.md`.
6. Prepare listing assets with `references/assets-and-metadata.md`.
7. Before pressing submit on iOS, run `capacitor-apple-review-preflight` for anything beyond a trivial update.
8. Roll out: iOS phased release (7 days, pausable) or Play staged rollout percentages; watch crash rates before widening.

## Verification

- iOS: Archive validates in Xcode Organizer ("Validate App") with no errors; build appears in TestFlight after processing; install from TestFlight on a real device and run the critical flows.
- Android: `bundletool` or Play internal testing install works; Play Console pre-launch report has no crashes; `aapt2 dump badging app-release.aab` or the Play Console shows the expected `versionCode` and `targetSdkVersion`.
- Both: the app launches cold from the store build (not a debug build), login with the reviewer demo account works, deep links and push work in release signing.

## Error Handling

| Error | Fix |
|---|---|
| ITMS-4238 "Redundant Binary Upload" (build number already used) | Increase `CURRENT_PROJECT_VERSION` |
| ITMS-90062 `CFBundleShortVersionString` must be higher than the previously approved version | Increase `MARKETING_VERSION` |
| ITMS-90186 "Invalid Pre-Release Train" (version train closed) | The marketing version was already released; increase `MARKETING_VERSION` |
| ITMS-90725 "SDK Version Issue" (built with an older SDK) | Build with the required Xcode/SDK (Xcode 26+ now, Xcode 27 from April 2027) |
| ITMS-91053 "Missing API declaration" | Add the required-reason API category and reason code to `PrivacyInfo.xcprivacy` |
| ITMS-91061 "Missing privacy manifest" for a named SDK | Update that SDK/plugin to a version that bundles a privacy manifest; do not copy the SDK's practices into the app manifest |
| ITMS-90683 "Missing purpose string in Info.plist" | Add the named `NS...UsageDescription` with a specific purpose |
| App launches to a black screen or not at all when built with Xcode 27 | UIScene lifecycle not adopted; upgrade to Capacitor 8.5+ and apply the 8.5 project changes |
| Play: `Version code 45 has already been used. Try another version code.` | Increase `versionCode` |
| Play: target API level error on upload | Raise `targetSdkVersion`/`compileSdkVersion` in `variables.gradle` to the required level |
| Play: `You uploaded an APK or Android App Bundle that was signed in debug mode` | Build `bundleRelease` with the upload key |
| Play: `Your Android App Bundle is signed with the wrong key` | Sign with the registered upload key, or request an upload key reset in Play Console |
| Play: production track unavailable | Complete the 12-tester / 14-day closed test (personal accounts) |

## References

- `references/ios-submission.md` - signing, archive, upload options, TestFlight, App Privacy, export compliance, review notes, phased release.
- `references/android-submission.md` - release signing, AAB, Play App Signing, tracks, Data safety, target API and 16 KB checks, staged rollout.
- `references/assets-and-metadata.md` - icon generation, screenshot sizes, text field limits for both stores.

Related skills: `capacitor-apple-review-preflight`, `capacitor-ci-cd`, `capgo-native-builds`, `capacitor-app-upgrades`, `capgo-live-updates`.

From Cap-go/capgo-skills, MIT.

More from Cap-go/capgo-skills