Wjs Publishing Appstore

wjs-publishing-appstore

Take an iOS app that's already building to TestFlight and ship it to the App Store: prepare the screenshots + description/metadata, then use the existing fastlane to submit for review.

This is the App Store counterpart to wjs-publishing-testflight, which is a prerequisite — that skill owns build / signing (match) / CI / the beta lane. This skill assumes that's done and only adds the listing + a deliberate release lane. Reference implementations: VoiceDrop, Cathier.

Mental model

git push → main      → beta lane    → TestFlight        (unchanged, automatic)
fastlane release     → release lane → metadata + screenshots → submit for review

Submitting to review is high-stakes, so it is never triggered by a push — it is the explicit fastlane release command you run on purpose.

Prerequisites

• wjs-publishing-testflight already set up: match appstore certs, the ASC_API_* secrets, a working beta lane, and at least one build already uploaded to TestFlight (this also creates the App Store Connect app record).
• Apple credentials / ASC API key: see [[apple-developer-credentials]] and the prerequisites table in wjs-publishing-testflight — do not re-list secrets here (this skill auto-publishes to a public repo).
• If the App Store Connect app record does not exist yet, create it once: bundle exec fastlane produce -u jianshuo@hotmail.com -a <BUNDLE_ID> --app_name "<Name>".

Steps

1. Scaffold the metadata tree

scripts/scaffold-metadata.sh        # from this skill; run at the repo root

Creates fastlane/metadata/{zh-Hans,en-US}/*.txt + review_information/ + top-level category/copyright, seeded with editable VoiceDrop copy. Re-running never overwrites existing files.

2. Write the real copy

Edit every .txt. Watch the limits: name 30 · subtitle 30 · keywords 100 (comma-separated, no spaces) · promotional_text 170 · description 4000. Fill in review_information/ (phone, and a demo account only if login is required) and the privacy URL.

The App Store name is globally unique. A short common name ("VoiceDrop") is almost certainly already taken by another account — the submit then dies at upload_to_app_store with "The app name you entered is already being used." This is the display name only; the home-screen name (CFBundleDisplayName) is separate and can stay whatever you like. Pick a distinct string (e.g. add a word or a Chinese suffix — "VoiceDrop 口述"); longer = safer. It's per-locale and changeable in a later version, so it's not permanent.

3. Shoot screenshots

scripts/shoot.sh                    # default: iPhone 16 Pro Max (6.9"), zh-Hans
LOCALE=en-US scripts/shoot.sh       # second locale

Edit drive_screens() in shoot.sh to hit each marketing screen (3–6, named 01_*, 02_*…). It boots a sim, builds, installs, captures into fastlane/screenshots/<locale>/. FRAME=1 adds frameit framing.

Required size: only the 6.9" display (1320×2868) is mandatory and it covers iPhone-only apps. Add a 13" iPad pass only if TARGETED_DEVICE_FAMILY includes iPad (VoiceDrop is iPhone-only → one size).

Mic-permission gotcha: if the app requests microphone/record permission, iOS shows a dialog xcrun simctl privacy grant microphone does not suppress (a real iOS 26 sim limitation). Open Simulator.app, tap 允许/Allow once — the grant persists for the install, so re-running shoot.sh then captures a clean frame. (simctl has no tap; don't try to click it from the script — synthetic clicks via osascript need macOS Accessibility permission the runner lacks.)

Other iOS 26 sim screenshot gotchas:

• To screenshot a screen you can't reach without a tap, temporarily root the app into that view (env-gated DebugRoot), and seed its data via the app's own token (a sim regenerates its synchronizable-Keychain identity on every reinstall — no iCloud account — so injected data under an old identity won't show; on a real device the identity persists).
• The sim paints a faint ghost of TabView labels near the Dynamic Island even for a bare two-tab TabView — a sim-only Liquid Glass artifact, not in your app. Don't chase it; verify on device.

4. Add the release lane

Paste scripts/release_lane.rb into the existing fastlane/Fastfile inside platform :ios do … end. It uploads metadata + screenshots (the TestFlight lane sets skip_metadata/skip_screenshots: true; this lane sets them false), then submit_for_review: true with the encryption/IDFA compliance answers, guarded by guard_not_in_review.

5. Preview, then submit

# dry-run the listing without submitting (writes an HTML preview, no upload):
bundle exec fastlane deliver --skip_binary_upload true --submit_for_review false --force false

# real submit (uses the build already on TestFlight for this version):
bundle exec fastlane release skip_build:true     # reuse the TestFlight build
bundle exec fastlane release                      # or build a fresh one first

Run locally, or via the CI workflow_dispatch if your build.yml routes a appstore choice to fastlane release (see wjs-publishing-testflight Step 3).

Robust two-step ship (what actually worked): git push → the beta lane builds and uploads to TestFlight and waits for Apple to finish processing → then dispatch appstore → fastlane release skip_build:true reuses that already-processed build. Building a fresh binary inside the release lane risks submitting before the build is processed. CI checks out main, so metadata + screenshots must be committed to main before you dispatch.

Un-ignore the screenshots. The TestFlight-only setup often has fastlane/screenshots/ in .gitignore (that flow uses skip_screenshots). This lane uploads them, so they must be committed — remove that ignore line (keep ignoring only frameit extras) or CI uploads nothing.