App Store Review

App Store Review — what actually happens, and what to do about it

This is a working protocol, not Apple's documentation. Every rule in it was paid for by a real round trip on a real app (Radiant for iPhone, 2026-08 to 2026-09). Where a rule looks paranoid, the reference files say what it cost.

It is model- and harness-agnostic. "Open App Store Connect" means: drive a browser if you have one, and otherwise write the exact steps for the user. Only the account holder can press Submit, reply to App Review, or upload a build — prepare everything, then hand over, and never report a step as done that you did not see finish.

Rule zero: read App Store Connect before you trust anything

The status of a submission lives in exactly one place:

https://appstoreconnect.apple.com/apps/<app id>/distribution/reviewsubmissions

Not in your notes, not in the last commit message, not in the project file's build number, not in what the user remembers. Every one of those went stale on Radiant — a status doc said "Waiting for Review" for nine days while the app had been REJECTED, and a whole day of work was done on a build that was not in the queue at all. Reading the page costs one navigation. Do it first, every time the task touches the submission, and write what you saw (status, build number, date) into whatever record you keep, dated.

Corollary: a prediction of why Apple will reject is worth nothing. Radiant's notes predicted guideline 1.2 twice; Apple raised 2.1, then 5.0.0 + 5.2.5. Do not build a fix for a rejection that has not happened.

The workflow

1. Before the first submission — the checklist

Work through reference/checklist.md in full. The items that bite:

• The name must be unique across the whole store and can be held by an app that never shipped. Have a second name ready.
• Name and subtitle must not contain Apple trademarks (iPhone, iPad, Apple, Mac). The description may mention them; the subtitle reads as branding and is held to guideline 5.2.5.
• Say nothing that reads as another company's brand. "Open AI models" (meaning open-weight) was read as OpenAI and triggered China's deep-synthesis rule (5.0.0). Write "open-weight" or "open models".
• If the app can send anything to a third party — even optionally, even with the user's own API key — the app itself must disclose and ask first. Guidelines 5.1.1(i) and 5.1.2(i): before the first byte goes to a cloud AI service (or any third party), the app shows what is sent, to whom (by name), what it is used for, and gets an explicit Allow / Not now. A privacy policy saying the same thing does not count — Apple's own words: "only including this information in the app's Terms of Service or Privacy Policy is not sufficient." The policy must ALSO state what data, how it is collected, all uses, and that the third party protects it. Radiant lost a review cycle to this with a bring-your-own-key provider list; the sheet took an afternoon after the rejection and would have taken an hour before it. Build it before the first submission.
• Every claim in the metadata must be true when a reviewer pokes at it. "Fully offline" is false the moment the app accepts a cloud API key. A subtitle can be shorter than the truth; it cannot be bigger.
• App Privacy has a Publish button. Saving the answers is a draft. The submit button then refuses with "an Admin must provide information about the app's privacy practices", which does not sound like "you forgot to publish". Verifying a value reloads correctly is not verifying the section is done.
• Age rating: do not chase 4+ with an app that generates text. Answer as the closest shipped peer did (look them up on the store), plus whatever your app adds. A reviewer who types a rude question and gets a rude answer has caught a false declaration (2.3).
• Review notes are capped at 4,000 characters and a 4,151-character draft is refused with no useful message. Write them in a file, count, then paste.
• Fetch every URL you enter and check the title of what comes back. A site that answers 200 with its homepage for unknown paths makes a typo look fine.
• Run the app on a physical device before uploading if any code path cannot run in the Simulator (anything using Metal/GPU: MLX, Core ML on GPU, camera). "Verified in the Simulator" is not a claim you can make about it.

1b. The app has to survive being live, not just pass review

⚠️ THIS SECTION EXISTS BECAUSE THE SKILL DID NOT HAVE IT. Everything above gets a binary through review. None of it makes the app a product once it is on sale, and Radiant shipped 1.0 with no way to rate it — discovered a day after launch, by the owner, not by the checklist. His words: "not being able to rate the app is a crippling problem."

Review these before the first submission, because two of them cannot be fixed without another review cycle.

A rating prompt. Non-negotiable. Ratings are a ranking input, and a new app has none. No ratings means no ranking means no downloads means no ratings — the loop does not break on its own, and every week without the prompt is a week of installs that could have left one and did not. Implement AppStore.requestReview(in: scene) (iOS 18+), falling back to SKStoreReviewController.requestReview(in: scene), and:

• ask after a success the person can feel, never on launch, never mid-task. Radiant asks after a model finishes downloading AND the person has had a real conversation — they have seen it work twice, on their own device;
• ask once, and record that you asked before the call, so a slow or failing request cannot produce a second prompt. The system caps it at three a year, but "the system will stop me" is not a reason to ask twice;
• it must never block, branch or report failure. The system decides whether a prompt actually appears and never tells you;
• verify the class is in the shipped binary. A new plugin/source file that is not in the Xcode target's Sources phase compiles nothing, and the call is refused at runtime where a catch swallows it. strings -a <binary> | grep <ClassName> — do not trust BUILD SUCCEEDED.

Keywords, or nobody finds it. 100 characters, comma-separated, no spaces after the commas (a space costs a character and buys nothing). Do not repeat words already in the name or subtitle — those are indexed and a repeat wastes the budget. No competitor brand names and no other companies' model names: the description is held to a looser standard than keywords, so name the models there instead. A day after Radiant launched it was findable at #17 for one narrow phrase and nowhere in the top 40 for anything else, including its own name — indexed, but ranking nowhere, which is the normal state of an app with no ratings and empty keywords.

Promotional text. 170 characters, sits above the description, and is the only listing field that can be changed at any time with no review. Not indexed for search, so it is for what changes — a new feature, a moment — not for keywords. Radiant shipped with it empty.

Then look at the app the way a stranger will, before the reviewer does: first launch with no data, the empty states, what the first sixty seconds asks of someone who has never seen it, and whether anything a new user hits first is half-built. A reviewer opens the app cold; so does every download.

2. While it is in review — statuses and what they mean

"Missing Test Information" is a TestFlight warning, not an App Store one. It gates external TestFlight testing only and does not block review. It lives under TestFlight → Test Information, a different tab with its own fields. Fill it (it takes ten minutes; reference/checklist.md lists the fields), but do not read it as a problem with the submission.