git:20260501.ed3e92e to git:20261011.86834d4

70 added, 408 removed. Audit A to A.

---

name: capacitor-app-store

- description: Complete guide to publishing Capacitor apps to Apple App Store and Google Play Store. Covers app preparation, screenshots, metadata, review guidelines, and submission process. Use this skill when users are ready to publish their app.

+ description: Ships a Capacitor app to the Apple App Store and Google Play. Use for release prep and submission - version/build numbers (CFBundleVersion, versionCode), signing, archiving and uploading the IPA/AAB, TestFlight, Play tracks and closed testing, icons and screenshots, listing metadata, App Privacy and Data safety forms, age ratings, export compliance, phased rollout, and current platform deadlines (iOS 26 SDK since April 28 2026, iOS 27 SDK from April 2027, UIScene lifecycle for Xcode 27, Play target API 36 from Aug 31 2026, 16 KB page size). Also for upload errors like ITMS-90725, ITMS-91053, ITMS-91061, ITMS-4238 redundant binary, or "Version code has already been used". Do not use for a guideline-by-guideline Apple rejection audit (capacitor-apple-review-preflight), CI pipeline authoring (capacitor-ci-cd), Capgo Cloud Build setup (capgo-native-builds), or converting a website into an app (webapp-to-capacitor).

+ allowed-tools:

+ - Bash(node -e *)

+ - Bash(find *)

---

- # Publishing to App Stores

- Guide to submitting Capacitor apps to Apple App Store and Google Play Store.

- ## When to Use This Skill

- - User is ready to publish app

- - User asks about app store submission

- - User needs app store screenshots

- - User has app rejection issues

- - User needs to update app listing

- ## Pre-Submission Checklist

- ### Universal Requirements

- - [ ] App icon in all required sizes

- - [ ] Splash screen configured

- - [ ] App name and bundle ID set

- - [ ] Version and build numbers set

- - [ ] Privacy policy URL

- - [ ] Terms of service URL

- - [ ] Support email/URL

- - [ ] Age rating content questionnaire

- - [ ] App description (short and long)

- - [ ] Keywords/tags

- - [ ] Screenshots for all device sizes

- - [ ] Feature graphic (Android)

- - [ ] App preview video (optional)

- ### iOS-Specific

- - [ ] Apple Developer Program membership ($99/year)

- - [ ] App Store Connect app created

- - [ ] Signing certificates and profiles

- - [ ] Info.plist usage descriptions

- - [ ] App Tracking Transparency (if applicable)

- - [ ] Sign in with Apple (if social login used)

- - [ ] Export compliance (encryption)

- ### Android-Specific

- - [ ] Google Play Developer account ($25 one-time)

- - [ ] App signed with release keystore

- - [ ] Target SDK level (API 34+)

- - [ ] 64-bit support

- - [ ] Permissions declared in manifest

- - [ ] Data safety form completed

- - [ ] Content rating questionnaire

- ## App Store Configuration

- ### Version and Build Numbers

- ```typescript

- // capacitor.config.ts - Not stored here, just for reference

- // iOS: Info.plist

- // CFBundleShortVersionString = "1.2.3" (user-visible)

- // CFBundleVersion = "45" (build number, increment each upload)

- // Android: build.gradle

- // versionName = "1.2.3" (user-visible)

- // versionCode = 45 (must increment each upload)

- ```

- ### iOS Info.plist

- ```xml

-

- <key>CFBundleDisplayName</key>

- <string>My App</string>

- <key>CFBundleShortVersionString</key>

- <string>1.0.0</string>

- <key>CFBundleVersion</key>

- <string>1</string>

-

- <key>NSCameraUsageDescription</key>

- <string>Take photos for your profile</string>

- <key>NSPhotoLibraryUsageDescription</key>

- <string>Select photos from your library</string>

- <key>NSLocationWhenInUseUsageDescription</key>

- <string>Find nearby locations</string>

- <key>NSFaceIDUsageDescription</key>

- <string>Secure login with Face ID</string>

- <key>NSMicrophoneUsageDescription</key>

- <string>Record voice messages</string>

-

- <key>NSUserTrackingUsageDescription</key>

- <string>Allow tracking for personalized ads</string>

-

- <key>ITSAppUsesNonExemptEncryption</key>

- <false/>

- ```

- ### Android build.gradle

- ```groovy

- // android/app/build.gradle

- android {

- defaultConfig {

- applicationId "com.yourcompany.yourapp"

- minSdkVersion 22

- targetSdkVersion 34

- versionCode 1

- versionName "1.0.0"

- // 64-bit support

- ndk {

- abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'

- }

- buildTypes {

- release {

- minifyEnabled true

- shrinkResources true

- proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'

- }

- bundle {

- language {

- enableSplit = true

- }

- density {

- enableSplit = true

- }

- abi {

- enableSplit = true

- }

- ```

- ## App Icons

- ### iOS App Icons

- Required sizes (place in Assets.xcassets):

- | Size | Scale | Usage |

- |------|-------|-------|

- | 20pt | 2x, 3x | Notification |

- | 29pt | 2x, 3x | Settings |

- | 40pt | 2x, 3x | Spotlight |

- | 60pt | 2x, 3x | App Icon |

- | 76pt | 1x, 2x | iPad |

- | 83.5pt | 2x | iPad Pro |

- | 1024pt | 1x | App Store |

- ### Android App Icons

- Required sizes (place in res/mipmap-*):

- | Density | Size | Folder |

- |---------|------|--------|

- | mdpi | 48x48 | mipmap-mdpi |

- | hdpi | 72x72 | mipmap-hdpi |

- | xhdpi | 96x96 | mipmap-xhdpi |

- | xxhdpi | 144x144 | mipmap-xxhdpi |

- | xxxhdpi | 192x192 | mipmap-xxxhdpi |

- Also needed:

- - Adaptive icon (foreground + background layers)

- - Play Store icon: 512x512

- ### Generate Icons

- ```bash

- # Use capacitor-assets

- npm install -D @capacitor/assets

- npx capacitor-assets generate --iconBackgroundColor '#ffffff'

- ```

- ## Screenshots

- ### iOS Screenshot Sizes

- | Device | Size | Required |

- |--------|------|----------|

- | iPhone 6.7" | 1290x2796 | Yes |

- | iPhone 6.5" | 1284x2778 | Yes |

- | iPhone 5.5" | 1242x2208 | Yes |

- | iPad Pro 12.9" | 2048x2732 | If supporting iPad |

- | iPad Pro 11" | 1668x2388 | If supporting iPad |

- ### Android Screenshot Sizes

- | Type | Size | Required |

- |------|------|----------|

- | Phone | 1080x1920 to 1080x2400 | Yes (2-8) |

- | 7" Tablet | 1200x1920 | If supporting |

- | 10" Tablet | 1600x2560 | If supporting |

- ### Feature Graphic (Android)

- - Size: 1024x500

- - Required for Play Store listing

- ### Generating Screenshots

- ```typescript

- // Use Playwright for automated screenshots

- import { test } from '@playwright/test';

- const devices = [

- { name: 'iPhone 14 Pro Max', viewport: { width: 430, height: 932 } },

- { name: 'iPhone 14', viewport: { width: 390, height: 844 } },

- { name: 'Pixel 7', viewport: { width: 412, height: 915 } },

- ];

- test('generate screenshots', async ({ page }) => {

- for (const device of devices) {

- await page.setViewportSize(device.viewport);

- // Screenshot 1: Home

- await page.goto('/');

- await page.screenshot({

- path: `screenshots/${device.name}-home.png`,

- fullPage: false,

- });

- // Screenshot 2: Feature

- await page.goto('/feature');

- await page.screenshot({

- path: `screenshots/${device.name}-feature.png`,

- });

- }

- });

- ```

- ## App Store Connect Submission

- ### 1. Create App

- 1. Go to https://appstoreconnect.apple.com

- 2. My Apps > + > New App

- 3. Fill in:

- - Platform: iOS

- - Name: Your App Name

- - Primary Language

- - Bundle ID

- - SKU (unique identifier)

- ### 2. App Information

- - Category (primary and secondary)

- - Content Rights

- - Age Rating (complete questionnaire)

- ### 3. Pricing and Availability

- - Price (Free or paid tier)

- - Availability (countries)

- ### 4. App Privacy

- - Privacy Policy URL (required)

- - Data collection types:

- - Contact Info

- - Health & Fitness

- - Financial Info

- - Location

- - Identifiers

- - Usage Data

- - etc.

- ### 5. Version Information

- - Screenshots (all sizes)

- - Promotional Text (170 chars)

- - Description (4000 chars)

- - Keywords (100 chars, comma-separated)

- - Support URL

- - Marketing URL (optional)

- - What's New (for updates)

- ### 6. Build Upload

- ```bash

- # Using Xcode

- # Product > Archive > Distribute App > App Store Connect

- # Using Fastlane

- fastlane ios release

- # Using xcrun

- xcrun altool --upload-app --type ios --file App.ipa \

- --apiKey KEY_ID --apiIssuer ISSUER_ID

- ```

- ### 7. Submit for Review

- - Answer export compliance questions

- - Add notes for reviewer (if needed)

- - Submit

- ## Google Play Console Submission

- ### 1. Create App

- 1. Go to https://play.google.com/console

- 2. All apps > Create app

- 3. Fill in:

- - App name

- - Default language

- - App or game

- - Free or paid

- ### 2. Store Listing

- - Short description (80 chars)

- - Full description (4000 chars)

- - Screenshots (2-8 per device type)

- - Feature graphic (1024x500)

- - App icon (512x512)

- - Video URL (optional, YouTube)

- ### 3. Content Rating

- Complete the questionnaire for IARC rating

- ### 4. Target Audience

- - Target age group

- - Ads declaration

- ### 5. Data Safety

- - Data collection

- - Data sharing

- - Security practices

- - Data deletion request handling

- ### 6. App Content

- - Ads (yes/no)

- - App category

- - Contact details

- - Privacy policy

- ### 7. Release

+ # Publishing Capacitor Apps to the Stores

- ```bash

- # Build AAB (required for new apps)

- cd android && ./gradlew bundleRelease

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

- # Upload via Play Console or API

- # Production > Create new release > Upload AAB

- ```

+ ## When to Use

- ### Release Tracks

+ 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.

- | Track | Purpose |

- |-------|---------|

- | Internal testing | Up to 100 testers, instant |

- | Closed testing | Invite-only, review |

- | Open testing | Public beta |

- | Production | Full release |

+ 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`.

- ## Common Rejection Reasons

+ ## Live Project Snapshot

- ### iOS Rejections

+ 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'))"`

- | Reason | Solution |

- |--------|----------|

- | Crashes | Test on real devices, fix bugs |

- | Broken links | Verify all URLs work |

- | Incomplete metadata | Fill all required fields |

- | Missing privacy info | Complete App Privacy section |

- | Login issues | Provide demo account |

- | Guideline 4.2 (Minimum Functionality) | Add meaningful features |

- | Guideline 5.1.1 (Data Collection) | Justify data usage |

+ 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' $`

- ### Android Rejections

+ ## Current Store Requirements (October 2026)

- | Reason | Solution |

- |--------|----------|

- | Crashes/ANRs | Fix stability issues |

- | Policy violation | Review Play policies |

- | Deceptive behavior | Be transparent about features |

- | Sensitive permissions | Justify in-app |

- | Target SDK too low | Update to API 34+ |

+ | 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 |

- ## Updates and Versioning

+ 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.

- ### Version Incrementing

+ ## Procedure

- ```bash

- # Increment patch (1.0.0 -> 1.0.1)

- npm version patch

+ 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.

- # Increment minor (1.0.0 -> 1.1.0)

- npm version minor

+ ## Verification

- # Increment major (1.0.0 -> 2.0.0)

- npm version major

- ```

+ - 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.

- ### Phased Rollout

+ ## Error Handling

- **iOS**:

- - Enable phased release in App Store Connect

- - 7-day gradual rollout (1%, 2%, 5%, 10%, 20%, 50%, 100%)

+ | 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) |

- **Android**:

- - Set rollout percentage in release

- - Monitor crash rate before increasing

+ ## References

- ## Resources

+ - `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.

- - App Store Review Guidelines: https://developer.apple.com/app-store/review/guidelines

- - Google Play Policy Center: https://play.google.com/about/developer-content-policy

- - App Store Connect: https://appstoreconnect.apple.com

- - Google Play Console: https://play.google.com/console

- - Capacitor Assets: https://github.com/ionic-team/capacitor-assets

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