67 lines
5.6 KiB
Markdown
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.
|