storebound/skills/appstore-first-release/SKILL.md

67 lines
5.6 KiB
Markdown

---
name: appstore-first-release
description: Step-by-step first (and later) App Store release of a mobile game - App Store Connect API key, bundle id, app record, signing and xcodebuild archive/upload with the API key, TestFlight, version + listing text in many locales, screenshots, age rating, App Privacy, review details, in-app purchases with the first version, and submitting for review. Use when the user wants to publish, release, upload or set up an iOS game/app on the App Store or TestFlight, or hits App Store Connect API errors.
---
# App Store: first release
The CLI is `crt-ship` (on PATH while this plugin is enabled; otherwise `bun ${CLAUDE_PLUGIN_ROOT}/cli/index.ts`).
Config: `crt-ship.config.ts`; credentials: `ASC_KEY_ID`, `ASC_ISSUER_ID`, `ASC_P8` (env or
`.crt-ship/credentials.json`, gitignored). All commands are idempotent and have `--dry`. Run `crt-ship check` first.
**Ask the owner before submitting for review, releasing, or canceling a submission.** The final "Submit for Review"
of a first version is the owner's click.
## Steps (API = crt-ship, UI = App Store Connect / Xcode by hand)
1. **UI · API key.** App Store Connect > Users and Access > Integrations > App Store Connect API > Team Keys > +
(Admin or App Manager). Download `AuthKey_<KEYID>.p8` once, keep it in `~/.appstoreconnect/private_keys/`, note the
Key ID and Issuer ID. The same key signs builds (`-allowProvisioningUpdates`).
2. **API · Bundle id.** `crt-ship apple bundle` registers it (Certificates, Identifiers & Profiles).
3. **UI · App record.** Apps > + > New App: iOS, name, primary language, the bundle id, SKU. **No API for this.**
Then `crt-ship apple status` finds it (put the Apple ID in `apple.appId` to skip the lookup).
4. **Local · Info.plist.** `ITSAppUsesNonExemptEncryption = NO` (HTTPS only) so builds skip export compliance;
`NSUserTrackingUsageDescription` if ads use the IDFA; privacy policy reachable inside the app (guideline 5.1.1).
5. **Local · Build + upload** (Mac, no Xcode account login needed, the API key does signing):
```sh
K="-allowProvisioningUpdates -authenticationKeyPath $ASC_P8 -authenticationKeyID $ASC_KEY_ID -authenticationKeyIssuerID $ASC_ISSUER_ID"
xcodebuild -project ios/App/App.xcodeproj -scheme App -configuration Release -destination generic/platform=iOS \
-archivePath build/App.xcarchive MARKETING_VERSION=1.0.0 CURRENT_PROJECT_VERSION=3 $K archive
xcodebuild -exportArchive -archivePath build/App.xcarchive -exportOptionsPlist ExportOptions.plist -exportPath build/export $K
```
ExportOptions.plist: `method` app-store-connect, `destination` upload, `teamID` <your team>, `signingStyle`
automatic. `MARKETING_VERSION` / `CURRENT_PROJECT_VERSION` overrides beat the project values; the build number must
grow per version. Processing takes 5-30 min (`crt-ship apple status` shows VALID).
6. **UI · TestFlight.** Create an internal group with "access to all builds" (hasAccessToAllBuilds) once: every new
build reaches the testers automatically. Sandbox testers: Users and Access > Sandbox.
7. **API · Version + text.** Fill `store/appstore.md`, then `crt-ship apple listing --version 1.0.0 --build 3`
(version, copyright, MANUAL release, build, name / subtitle / privacy URL, description / keywords / promo / URLs).
8. **API · Screenshots.** `store-screenshots` skill, then
`crt-ship apple screenshots > .crt-ship/asc-shots.log 2>&1 &` (6.9" + 6.5" per locale, MD5-idempotent).
9. **API · App info.** `crt-ship apple appinfo`: categories, age rating declaration, content rights, Free price,
all territories.
10. **API · Review details.** `crt-ship apple review-details` (contact from `.crt-ship/credentials.json`
`reviewContact`, or `--contact-from <Apple ID of another app of the team>`; notes from the config).
11. **API + UI · In-app purchases.** `store-iap-setup` skill. First IAPs go to review **with** this version.
12. **UI · App Privacy.** `store-declarations` skill (nutrition labels), then **Publish**.
13. **UI · Submit.** Version page > Add for Review (with the IAPs in the same draft submission) > Submit for Review
(owner). Release type MANUAL means the owner presses "Release" after approval.
14. **Verify.** `crt-ship apple status`: version WAITING_FOR_REVIEW, IAPs WAITING_FOR_REVIEW, one review submission.
## Gotchas
- The app record cannot be created via API; the bundle id can.
- First consumable / non-consumable IAPs must be submitted together with an app version, only from the IAP page
("Add for Review" puts them into the draft submission). The API (`inAppPurchaseSubmissions`) answers
`FIRST_*_MUST_BE_SUBMITTED_ON_VERSION`. If the version was already submitted without them: cancel the review
submission (`crt-ship apple status --cancel-submission <id>`, PATCH canceled: true), wait a minute, add the IAPs
from their page, then resubmit.
- App Privacy (data types, purposes, linked, tracking) is UI-only and must be **published**, not just saved.
- Screenshot sizes: 6.9" 1320 x 2868 (`APP_IPHONE_67`) is required; 6.5" 1284 x 2778 (`APP_IPHONE_65`) recommended.
PNG without alpha. Up to 10 per set. Apple processes uploads async; failures show as FAILED later.
- App Store icon (1024) must have **no alpha channel** (`crt-ship icons` writes rgb24).
- Limits: name 30, subtitle 30, promotional text 170, keywords 100 bytes (UTF-8, no spaces after commas),
description 4000. No "What's New" on a first version.
- Guideline 5.1.1: the privacy policy link must be inside the app too (Settings > Privacy), not only in the listing.
- `xcodebuild` with Capacitor needs a UTF-8 locale (`export LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8`).
- 500 / 503 from the API happen; crt-ship retries with backoff.