erberkk/review-readiness

Review readiness

Purpose

Submit once and pass. Most rejections are not about the app's idea; they are a reviewer who could not sign in, could not buy, saw a placeholder, or found a contradiction between metadata and app.

Prerequisites

• The exact build to submit is on TestFlight / a Play testing track.
• subscriptions-and-payments Checkpoint passed (a real purchase unlocked premium on both platforms).
• privacy-and-declarations completed; listing-and-aso validator clean; screenshots uploaded.

Think like a zero-knowledge reviewer

Assume the reviewer installs a clean build on a device you did not test (an iPhone-only app can be reviewed on an iPad in compatibility mode), with a fresh store account, and has limited time. They read your notes, try the sign-in, look for the purchase, and compare screenshots with the app. A single rejection can combine several layers: account state, backend behaviour and metadata.

Procedure

1. Demo account

• Credentials go into App Store Connect › App Review Information ("Sign-in required") and Play › App content › App access. Never in the repo.
• The account signs in with email + password. If your normal sign-in is an email one-time code or magic link, the reviewer cannot receive it. Add a password path for the review address only (server-side allow-list) or a fixed test code that only works for that address.
• Filled with data: profile complete, a few days of history, every main screen populated. An empty account hides features and invites "we could not locate feature X".
• Premium unlocked via a server-side manual entitlement (no expiry during review), so reviewers see paid features without buying.
• Separately, make sure a new user can reach the paywall and buy with the reviewer's sandbox account (they will test the purchase too).
• Do not change, delete or re-seed this account while a review is open.

2. Purchases (2.1(b) and 3.1.x)

• First-version subscriptions are attached to the version in App Store Connect ("In-App Purchases and Subscriptions" section) and have a review screenshot and notes. In the newer App Store Connect UI there may be no such section on the version page: open the subscription group and each subscription and use Add for Review → Draft Submission; the version itself is added from its own page. The draft must list the version, the group and every subscription before you press Submit for Review.
• Each subscription needs at least one display name + description localization and a review screenshot; without them "Add for Review" fails ("You must add at least one subscription localization / a Review Information screenshot").
• The review screenshot must show the real paywall with real prices and the right store wording. If you render it from a widget/UI test, force the iOS platform (otherwise it says "Google Play") and feed realistic store prices; a "prices unavailable" state is not acceptable.
• The App Store version string must equal the builds' marketing version (CFBundleShortVersionString). A version named 1.0 will not offer builds uploaded as 1.0.0; the Build section just says "Upload your builds" with no Add Build button. Rename the version to match.
• On TestFlight with a fresh sandbox Apple Account (not linked to any of your app accounts): products load, purchase works, restore works.
• Paywall error state shows retry, never a disabled "Coming soon".
• If an IAP cannot be reached in the app (e.g. only for a region), explain why in the review notes.
• Restore Purchases, Terms and Privacy links, manage-subscription link present.

3. Devices and builds

• Cold start with no network, slow network, and airplane mode toggled: no crash, no infinite spinner.
• iPad: even an iPhone-only app runs on iPad in compatibility mode and may be reviewed there. Run the full flow on an iPad simulator: sign-in (including Sign in with Apple), paywall scrolling, purchase sheet, keyboard over forms, permission prompts, rotation. If HealthKit or another API is unavailable there, show a polite message, not a crash.
• Smallest supported phone and largest text size: no clipped buttons on the paywall or consent screens.
• Release build, not debug: no debug banner, no test menus, analytics/crash reporting on in production configuration.
• Walk the full account lifecycle on a physical device with the exact build you submit: install, sign up, main features, sandbox purchase, account deletion, and what the app shows after deletion.

4. Content and metadata

• Search the app's strings and listings for: TODO, lorem, coming soon, beta, test, [PRICE], placeholder images. None may render.
• iOS build and metadata contain no Android / Google Play wording; Play contains no Apple-only wording (2.3.10). Includes in-app strings such as "Cancel in App Store or Google Play" — pick the platform's text at runtime.
• Every screenshot matches the current UI; every number in the description matches the app.
• Privacy policy, terms, support and account-deletion URLs load without login, mention the app, and match the privacy forms.
• Age rating consistent with Terms.

5. Backend

• Backend is up and on a plan that will not hit limits during review (free tiers pausing or throttling = rejection).
• No deploys of breaking changes during review. Backward-compatible API for the build in review.
• Alerts are on (post-launch-ops) so you notice an outage during review.

6. Review notes

Fill in templates/review-notes.md. Keep it factual: where features are, how to sign in, how to test the purchase, how AI and health data are handled, where account deletion is.

Apple may respond with Guideline 2.1 "Information Needed" instead of reviewing. In one observed case it asked for the six items below; answering them up front in the first submission avoids a round trip:

1. A screen recording from a physical device on the latest OS, starting at app launch and showing the typical flow: registration, login, account deletion, any user-generated content with reporting/blocking, and access to paid content. Record it with the submitted build; attach the file to the reply in the submission's Messages (or link it) and mention it in Notes. Never use the demo review account for the deletion part: create a fresh account in the recording.
2. The app's purpose and target audience: the problem it solves and its value.
3. Setup and access instructions for the main features, with demo credentials and menu paths.
4. Every external service behind core features: auth/database, payments (StoreKit + any wrapper), AI providers, data sources (e.g. map APIs), email, health frameworks.
5. Regional differences, or a statement that features are the same everywhere.
6. For regulated areas or third-party protected content: documentation or a statement that none applies (e.g. "general wellness, not a medical device").

7. Go/no-go report

Fill in templates/go-no-go-report.md with evidence for each line (screenshot, build number, command output). Any No on a blocking line means no submission.

8. Submit (APPROVAL)

Ask the account holder for explicit approval with the report attached. On iOS choose manual release so approval does not publish immediately. On Play, production access (new personal accounts) needs the completed 14-day closed test and the production access application first.

After a rejection

See references/rejection-playbook.md: read the exact guideline, reproduce, fix the root cause (often more than one layer), reply in Resolution Center with specifics, resubmit; appeal only when the reviewer misread a fact you can prove.

Decision points needing human approval

Submitting, choosing release method, replying to a rejection (tone and commitments), filing an appeal, granting premium to the review account.

Verification

The go/no-go report is complete with evidence, and someone who did not build the feature walked the review notes on a clean device and succeeded.

Common pitfalls

• Demo account depends on an email code the reviewer cannot read.
• Demo account empty, frozen, or deleted by a cleanup job.
• Products in "Missing Metadata" (no review screenshot), so they never load in review.
• Removing a version from review ("Developer Rejected") also drops the subscriptions from the draft; re-add the group and each subscription before resubmitting, or the version goes alone.
• Product-page assets are locked while the version is "Waiting for Review" (e.g. the newer Header asset). Add everything before submitting; otherwise you must remove the version from review, edit, and resubmit (you lose your place in the queue).
• Apple's own "Add for Review" check passing does not mean optional assets are set: an empty Header asset is allowed, so decide about it before you submit.
• A reviewer's fresh Apple Account collides with your restore/transfer rules and the purchase "fails".
• Backend on a plan that pauses after inactivity or rate-limits the reviewer.
• "Coming soon" anywhere in the build.
• In-app text mentioning the other store.
• Review notes that only explain the demo login (no recording, purpose, services or regions).