DEV Community: Pragathi Jayaram

What Apple actually checks: an App Store submission checklist for a health app

Pragathi Jayaram — Mon, 12 Oct 2026 15:30:58 +0000

Most App Store submission checklists are flat lists. They tell you what has to be true, in roughly the order Apple numbers its guidelines, which is not the order you can do the work in.

This one is ordered by dependency. First the items with multi-week clocks that block everything downstream, then the things that live in the build, then the things that live in the listing, then the things that can only be checked on the build you are actually going to ship. If you follow it top to bottom, you should not find yourself blocked by something you could have started a month earlier.

It comes out of getting a nutrition app with subscriptions, health data and a third-party AI path through review on the first submission. That account is the story version. This is the part that generalises: every requirement below links to Apple's own published rule, so you can check me. Where something is my judgment rather than Apple's requirement, it says so.

It is written Apple-first, for a small team or one person, and it assumes you are shipping something with an account, a subscription and some data you would rather not get wrong.

The clocks you cannot compress

Almost everything else on this list is work you control. These are not. Start them first, because no amount of effort later makes them go faster.

Developer Program enrollment, and which kind. Individual or Organization. Organization requires a D-U-N-S number and verification of the legal entity, which takes time and can stall if your business is not registered in a form the process expects. Individual enrollment is immediate by comparison. The visible difference to users is the developer name on the listing. If you are a sole trader, Individual may also be the honest description of the legal reality. You can transfer later.

Paid Apps Agreement, plus tax and banking. This is the one that catches people, because it does not only gate getting paid. Apple's guidance is explicit that the Paid Apps Agreement must be signed and Active before in-app purchase products are available in the sandbox, which means you cannot test your purchase flow at all until it is done. Behind it sit a bank account and tax forms, and behind those, in most countries, a business registration and a tax number that arrive on somebody else's timetable.

Chain it out and the sequence for a new business is roughly: register the business, file for a tax number, wait weeks, open a business bank account, complete Agreements Tax and Banking, wait for Active, and only then run your first sandbox purchase. Plan for that to be the longest pole in the whole project.

The top row sets your date. The bottom row is the part most people think of as the work.

If your app has subscriptions, the date you can first test a purchase is set by paperwork, not by engineering. Find that date early and work backwards from it.

Toolchain minimums. Apple publishes SDK minimum requirements with hard dates. Since 28 April 2026, uploads must be built with Xcode 26 or later against an iOS 26 SDK or later. These deadlines arrive without a grace period, so check the current requirement before you plan a release, not after a failed upload.

Age rating questionnaire. Apple replaced the age rating system in 2025. The tiers are 4+, 9+, 13+, 16+ and 18+; the old 12+ and 17+ are gone. The questionnaire added required questions on in-app controls, app capabilities, medical or wellness topics, and violent themes, and apps that had not answered it by 31 January 2026 were blocked from submitting new apps or updates. If you are returning to an app you have not touched in a while, check this before anything else, because it silently blocks submission.

Why one checklist for everything stalls

This is method rather than requirement, and it is the single change that made the rest tractable.

A single list stalls because it is usually ordered by guideline number, and guideline order has nothing to do with what you can do today. You reach an item that needs a build you have not made, or a store agreement that is not active yet, and the list stops there while a dozen items you could have finished sit below it.

Submission work splits into three kinds, separated by what unblocks them and by what makes a finished result worthless again.

Kind	Example	Unblocked by	Invalidated by
Verify state	No debug logging in release; every permission string localised; no secrets in the package	Nothing. Start today with only the repository open	The next commit
Device tests	Cold launch on a real device; purchase, cancel, expire, restore	A build. Anything involving purchases also needs an active Paid Apps Agreement	A new build
Form filling	Listing copy, screenshots, privacy labels, age rating	The console. Some fields will not accept anything until a build is uploaded	Nothing. It persists

Write them as three documents, because they have three different lifecycles. Keep them in one and you will either redo work that did not need redoing, or trust a check whose build no longer exists.

One warning from experience: your audit will go stale. Apple's guidelines are a living document and rules move. Re-read the actual guideline text before you trust your own summary of it.

What has to be true in the build

Privacy manifest. Apps must include a privacy manifest, a PrivacyInfo.xcprivacy file declaring the data types your app collects and your reasons for calling certain APIs that could otherwise be used to fingerprint users. Third-party SDKs ship their own manifests and Xcode consolidates them.

The practical point: find out what your toolchain generates for you before you hand-write anything. If you are on a managed framework, the SDK-contributed portion may already be handled, and the piece you actually have to declare is your own first-party data collection and tracking status. Check the merged file in a real build once rather than assuming either way.

Permission strings. Every permission you request needs a usage description that explains why, and it needs to exist in every language you ship. A string that says "This app needs camera access" is worse than useless; say what the camera is for. Also confirm you are not requesting permissions you no longer use, which happens quietly when a feature gets cut but its dependency does not.

Release hygiene. Console logging stripped. Developer-only switches compiled out rather than merely hidden. No environment or secrets files inside the shipped package. Confirm all of these on a release build, because every one of them behaves differently in debug.

What has to be true in the listing

Apple's accurate metadata rules under 2.3 are more prescriptive than most people expect.

App names are limited to 30 characters (2.3.7), and metadata must not be packed with trademarked terms, popular app names, pricing information or irrelevant phrases.
Every localization is a complete listing. If you add a language, you owe it its own name, subtitle, keywords, description, screenshots. This roughly doubles the work per language, and it is not a place to paste machine translation, particularly if your app makes any claim about health.
Field limits are enforced by the form, not documented in one place. Apple publishes the 30-character name limit in the guidelines but does not publish every field's ceiling there. The description limit was 4,000 characters when I submitted. Treat the form as the authority, write to the limit deliberately, and leave yourself headroom, because a translation that fits today may not fit after an edit.
Legal URLs must be live at submission, and if you ship more than one language, make them locale-explicit rather than relying on a single URL to guess. A privacy policy URL that 404s is an instant rejection and an easy one to avoid.
Subscription terms belong in the description. Guideline 3.1.2(c) requires that before asking someone to subscribe you clearly describe what they get for the price. In the EU, price-indication law wants the same information, so write it once and satisfy both.
Encoding surprises are real. App Store Connect rejected ✓ (U+2713) in my description as an invalid character while accepting German umlauts without complaint. If the form refuses your text and does not say why, suspect a non-ASCII decoration before you suspect anything clever.

Age rating. Answer the questionnaire against what your app actually does. One trap worth naming: if there is a mitigation checkbox about social media being disabled for under-13s, do not tick it reflexively. It asserts an integration you may not have, and it only applies if you declared a social surface in the first place.

App privacy details. The nutrition label is required to submit, must cover data collected by third-party code you integrate, and you are responsible for its accuracy. Inaccurate disclosures can get an app rejected or removed.

Do this from a written inventory rather than from memory, and reconcile it against your privacy manifest so the two cannot contradict each other later. Working out what your analytics, crash reporting and payment SDKs each collect is the actual task; filling the form afterwards takes an hour.

Assets fail on spec, not on taste

The most mechanical section, and the one where rejections feel most stupid.

No alpha channel. Apple's screenshot specifications state that images cannot include alpha channels or transparency. The check is per-pixel, so an image that looks completely opaque but was exported with an alpha channel still fails. The same applies to the 1024×1024 App Store icon. Design tools export with alpha by default, so flatten deliberately.

Screenshots must show the app in use. Guideline 2.3.3 says they should not be merely title art, a login page or a splash screen. Overlaid text and images are allowed. My own opinion, not Apple's rule: use real screens rather than marketing renders, because a reviewer comparing your screenshots to your app is doing exactly the comparison you want to survive.

Metadata must suit a 4+ audience regardless of your app's rating (2.3.8), which constrains screenshots as well as text.

Do not reference other platforms in your app or metadata (2.3.10). Scrub mentions of Android or other marketplaces from screenshots and copy.

The same section as a checklist:

Asset	Requirement	Stated in
App icon, 1024×1024	Flattened, no alpha channel, no transparency	Screenshot specifications
Screenshots	No alpha channel or transparency, checked per pixel	Screenshot specifications
Screenshots	Show the app in use, not title art, a login page or a splash screen	Guideline 2.3.3
App name	30 characters	Guideline 2.3.7
All metadata	Suitable for a 4+ audience regardless of the app's own rating	Guideline 2.3.8
App and metadata	No names, icons or imagery of other mobile platforms or marketplaces	Guideline 2.3.10
Description, keywords, review notes	Ceilings enforced by the form and not published in the guidelines; read them off App Store Connect	—

What the reviewer needs in order to do the job

Guideline 2.1(a) is direct about this:

Make sure your app has been tested on-device for bugs and stability before you submit it, and include demo account info (and turn on your back-end service!) if your app includes a login.

Read past the obvious. What it asks for is an account through which the reviewer can see the whole app.

One account per state you gate on. If your app has free and paid tiers, a free account alone will not show a reviewer the paid features. Provision one per state, and seed each one with realistic data, because empty states demonstrate nothing.
Seed the data. A reviewer opening a populated app can evaluate it. A reviewer opening an empty one is evaluating your empty states.
Review notes must be specific. Guideline 2.3.1 requires new features and changes to be described with specificity in the Notes for Review, and states plainly that generic descriptions will be rejected. Write the notes as a route map: where each gated feature is, which account reaches it, what to tap. Check every label in the notes against the actual strings in the build, because a note describing a screen that does not exist costs a review cycle.
In-app purchases must be visible and functional to the reviewer, and 2.1(b) says that if a configured purchase cannot be found or reviewed in your app, you must explain why in the notes.
Freeze once submitted. Editing an item that is in review pulls it out of the queue. Decide what is going in, put it in, then leave it alone. That includes the demo accounts: do not sign into them, do not change their state.

The rules that bite health and wellness apps

Third-party AI consent. Apple revised 5.1.2(i) on 13 November 2025 to say you must clearly disclose where personal data will be shared with third parties, including with third-party AI, and obtain explicit permission before doing so.

Three things follow that people get wrong. Disclosure in a privacy policy is not permission; the permission has to exist in the product, before the first transmission. Name the provider rather than saying "third parties". And do not bundle it into your terms acceptance, because that is not explicit permission for this specific purpose.

My own design position, not a rule: build the decline path so that declining costs the user the AI feature and nothing else. Consent that costs you the app is not meaningfully a choice, and under the GDPR it is unlikely to be freely given.

If you process health data in the EU, there is a second layer. Health data is Article 9 special-category data under the GDPR and needs explicit consent in its own right, and the existence of a decline path may move your lawful basis for that feature from contract to consent, with document consequences. That is a separate piece of work from the Apple rule and it does not go away if you satisfy Apple.

No medical claims. Guideline 1.4.1 says medical apps that could provide inaccurate information, or be used to diagnose or treat, may be reviewed with greater scrutiny, that accuracy claims about health measurements must be supported by disclosed data and methodology, and that apps should remind users to check with a doctor. If you are wellness rather than medical, the posture has to be visible in the product and not only in your terms: disclaimers on generated output, no diagnostic language, no claim you cannot substantiate.

In the EU there is a parallel constraint on what you may say about food and health at all. Permitted health claims are listed in Regulation (EU) No 432/2012, and wording outside that list is a regulatory problem independent of Apple.

Account deletion. Guideline 5.1.1(v) requires that if your app supports account creation, you must also offer account deletion within the app. Build it so it completes without contacting support, and test it end to end on a real account: authentication record gone, application data gone, and any external processor holding a record of that user cleaned up too. If the user has an active subscription, tell them deletion does not cancel it and where to cancel.

Minimum functionality and saturated categories. 4.2 asks for something more than a repackaged website. 4.3(b) says Apple will not accept new submissions in well-established categories unless they offer a meaningfully different or improved experience. If you are entering a crowded space, your listing has to make the difference legible.

Payments, and the requirement most people miss

Unlocking features inside the app means in-app purchase (3.1.1). Beyond that:

Restore has to work, and has to be reachable. 3.1.1 says you should make sure you have a restore mechanism for restorable purchases. The failure mode I hit, and the one worth checking today: restore that lives only on the paywall, which is the screen non-subscribers see. A subscribed user then has no route to it, including the paying demo account you gave the reviewer. Put restore somewhere reachable in every subscription state.
Prices and periods must match your configured products exactly, in every language and currency you display them in.
Describe what the subscription buys before asking for it (3.1.2(c)).
Test the whole lifecycle, not the happy path. Purchase, upgrade, downgrade, cancel, expire, confirm the app re-gates, restore while active, restore with nothing to restore, restore after signing out and back in. Every purchase bug I found lived in one of the paths that is not "buy it once and it works".

The last gate, and what happens after you pass it

Re-verify on the exact binary. Production signing and production purchase configuration are not the same as development. A test that passed on a development build is evidence about that build. At minimum, run a cold launch and a real sandbox purchase on the binary you are submitting, then tag that commit, so the tag records what was verified rather than what was intended.

Choose your release option deliberately. After approval you can have the version go live automatically, on a date, or manually. Manual leaves the approved version at Pending Developer Release until you click Release This Version, which decouples "Apple approved it" from "it is live". For a first launch I would take manual every time: it gives you a window to do go-live work with the approval already in hand. Releasing can take up to 24 hours to appear on the store, so released is not the same as findable.

For updates, consider phased release. App Store Connect can roll an update out over seven days to users with automatic updates on, while anyone can still download it manually, and you can release to everyone at any point. Useful for anything with a regression risk.

If it comes back. Rejections arrive in Resolution Center with the guideline cited. Answer the guideline you were given, in that thread, and resubmit; do not guess at what else might have been wrong.

Two things I would tell anyone starting this. The first is that the schedule is set by the clocks you cannot compress and nothing else, so find those dates before you plan anything. The second is that almost none of the outcome is decided during review. It is decided in the weeks before, which is entirely the part you control.

The account of doing all of the above for one app, including the bugs it turned up and what the reviewer actually touched, is here.

No checklist survives contact with a different app. This one is as general as I could make it, which means yours will still raise something it does not answer. When it does, write to me at hello@pragathijayaram.com and say what you are shipping and where the list runs out. I would rather work through one specific case than add another general bullet.

Approved on the first submission: what it took to get a wellness app through App Review

Pragathi Jayaram — Mon, 12 Oct 2026 15:19:56 +0000

Anovi went into App Review on 27 July and came out approved on 6 August. First submission, no rejection, nothing in Resolution Center.

It is a nutrition app, which means it carries three things App Review looks at closely and carries them at the same time: auto-renewing subscriptions, health data, and an AI path that sends what you ate to a model somebody else operates. After about a decade of shipping software through other channels, it was the first app I had put in front of a consumer app store.

The approval is not the interesting part. What produced it is. There was an audit written before submission was on the calendar, a test plan run against a real purchase on the first day that was legally possible, and a fortnight of metadata work where being careless and being wrong look identical from the outside.

This is the account of one submission. The companion piece is the same material in checklist form, where every requirement traces back to Apple's published rules rather than to one submission.

Markers are placed by actual date. The stretch to 27 July holds business registration, Apple's contract clocks, the build, the audit, the test pass and the listing, with waiting stacked between them. Everything that decided the outcome sits to the left of that date.

The audit came first, and then the audit needed auditing

I wrote the rejection-risk audit on 17 May: about 175 checks across Apple guidelines, Play guidelines, trust and data handling, functional resilience, app-specific risks, and release-build hygiene. It went in before submission had a date, which was deliberate. A checklist written under deadline pressure is a checklist written to pass.

The first useful thing executing it did was invalidate part of it. Apple's guidelines are not a fixed target, and neither is the EU regulation sitting underneath them. Three of the requirements this checklist depended on had changed, the most recent of them three weeks before I wrote it:

Apple had rewritten Guideline 5.1.2(i) on 13 November 2025 to cover third-party AI explicitly. A checklist written against the earlier text does not mention AI data sharing at all.
The age rating system had been replaced. The tiers are now 4+, 9+, 13+, 16+ and 18+, the old 12+ and 17+ are gone, and there is a new questionnaire covering in-app controls, app capabilities, violent themes and, relevant here, medical or wellness topics.
From 28 April 2026, uploads must be built with Xcode 26 and an iOS 26 SDK or later, per Apple's SDK minimum requirements.

So the first task was auditing the audit against what Apple actually publishes today, then extending it. That pass added the AI section, rewrote the age-rating items, added the SDK requirement, and added a section on health-app scrutiny under 1.4.1.

A submission checklist is a live document, because Apple's guidelines keep moving and the EU's do too, and nobody tells you when. Re-read the source before you trust your summary of it.

Guideline 5.1.2(i): consent is not disclosure

The first finding was the one that mattered. Apple's App Review Guidelines now read, under 5.1.2(i):

You must clearly disclose where personal data will be shared with third parties, including with third-party AI, and obtain explicit permission before doing so.

Anovi hits this squarely. When you describe a meal in plain language, that text goes to Google Gemini for ingredient and nutrition estimation, with Anthropic as a fallback when Gemini is unavailable. Alongside the meal text goes any modification you made and, so the estimate does not poison you, your recorded food allergies.

The word doing the work in that guideline is permission. Naming Gemini and Anthropic in a privacy policy is disclosure, and disclosure is only half of what the rule asks for. The other half has to exist in the product, before the first transmission, as something the user actively passes through.

There is a second layer underneath, because allergy information is health data. Under the GDPR that is Article 9 special-category data, which needs explicit consent in its own right. And because a decline path exists, the AI feature is voluntary enrichment rather than something needed to deliver the contract, which moved its lawful basis from Article 6(1)(b) to Article 6(1)(a) and pulled a chain of documents along behind it.

What shipped:

A backend gate. The AI routes return 403 ai_consent_required before any model is called. The block is server-side, so it holds regardless of what the client does.
A just-in-time sheet on the client. An interceptor catches that specific 403, opens the consent sheet, and retries the original request if consent is granted, so the user's action is not lost.
Named providers and named data. The sheet says Google Gemini and Anthropic, and it says meal description, modifications and allergy information. Not "service providers", not "third parties".
No identity travelling with it. Nothing identifying the user is sent: no name, no email, no account. The allergy information goes on its own rather than attached to the rest, so what arrives at the provider is a constraint without a person behind it.
Withdrawal, in settings, with each grant and withdrawal written to an audit table.

The gate as it ships. Providers named, data types named, the decline path stated on the sheet itself rather than buried in a policy.

The part I would defend hardest is the decline path. Turning it down leaves manual logging, barcode scanning and the whole catalogue fully working, which the sheet says on its face rather than leaving the user to find out. That was a design constraint, not a courtesy: consent that costs you the app is not freely given, and an implementation that blocks the whole feature and calls the resulting shrug "consent" is doing the paperwork rather than the thing.

None of the rest of it was required either. The block could have sat on the client, where a modified build walks straight past it. The allergy list could have travelled attached to everything else, because sending one object is easier than sending two. The audit table of grants and withdrawals serves nobody except someone checking up on me. Each of those was a choice to do the more expensive thing, and the reason is what the data is. Someone tells you what they eat, and then tells you what will hurt them, so that the app does not hurt them. Forwarding that to a third party because a model performs better with it is a decision about a person, not about a payload.

Compliance tells you what you must not do. It does not tell you what you should not send.

The payment layer, tested on the first day that was possible

The RevenueCat integration shipped on 11 June: purchase flow on both entry points, webhook, tier sync, deletion cascade. It could not be tested against a real purchase, because sandbox purchases require an active Paid Apps Agreement, and that was waiting on a business bank account, which was waiting on a tax number.

The agreement went active on 17 June. That same day I ran the full subscription lifecycle in sandbox on the German storefront: buy monthly, buy yearly, manage, upgrade, downgrade, cancel, let it expire, confirm the app re-gates, restore while active, restore with nothing to restore, restore by logging out and back in.

It found four defects and one decision I had made and then disagreed with. All five were closed the same day.

The paywall that could not load. The RevenueCat App User ID was keyed off a field that arrives with the user-profile request, and that request does not fire until onboarding completes. So throughout onboarding, the payment SDK was never configured, offerings came back empty, and the onboarding paywall could not load. The fix took identity from the auth-session JWT instead, so the payment layer configures the moment authentication resolves rather than waiting on a profile that structurally does not exist yet.

The paying user stuck in onboarding. Buying from the paywall while inside onboarding only dismissed the paywall. Onboarding never completed, which left a user who had just paid stuck in a flow they could not exit. Onboarding and the paywall had been built separately, and when they were wired together the completion handoff was the join nobody made. A focus effect on the onboarding screen now completes it when the screen regains focus already subscribed.

The lapsed subscriber who could not re-subscribe. Nothing was listening for subscription changes made outside the app, so the flag went stale when a subscription expired elsewhere. The paywall would then read that stale value, tell a lapsed subscriber they were still subscribed, and disable the purchase button. Somebody whose subscription had genuinely ended could not start a new one. Adding the update listener keeps the flag live and re-syncs the server-side tier with it.

The restore button nobody who needed it could reach. The guideline says you should make sure you have a restore mechanism for restorable purchases. Anovi had one. It lived on the paywall, and the paywall is what you see when you are not subscribed. A subscribed user had no route to it anywhere. That includes the demo account App Review would use, which was provisioned as a paying account precisely so a reviewer could see the paid features. The fix was a Subscriptions screen under the profile tab exposing current plan, manage, upgrade and restore in every tier state.

The screen in the state that mattered. Restore is reachable here while subscribed, which is exactly where it was not reachable before.

The fifth was not a defect. The onboarding upgrade button had been deliberately wired to the annual plan, on the theory that fewer choices convert better. Seen in the sandbox, next to a monthly price the user was never offered, the theory did not survive looking at it. It now opens the full paywall and the plan choice belongs to the user.

Two things worth being precise about. Every one of these lived in the payment layer, which was six days old and had never been runnable against a real transaction until that morning. And the one with direct guideline exposure, the restore gap, was found by testing the reviewer's exact account state rather than by reading the guideline again.

Eighteen test areas, three of them not applicable

The rest of the plan ran over the following two days: fresh install and cold launch, onboarding end to end, every tab in both empty and populated states, session handling and cross-user leakage, network failure, offline degradation, loading and error and partial-failure states, crash and memory under sustained use, background and battery, subscription gating, AI quota exhaustion and provider failure, the consent gate, domain edge cases, and a German-language sweep across every legal, consent and disclaimer surface.

Three areas came back not applicable, and that is worth saying out loud. There is no Sign in with Apple, because there is no third-party login at all, so Guideline 4.8 is not triggered. Nothing routes into the app by deep link. There is no push token at launch. The temptation with a test plan is to write tests you can pass and mark the awkward ones green. Marking them not applicable, with the reason recorded, is the version that survives someone checking.

The worst things I found were not the ones Apple checks

Testing that hard turns up things the store does not care about, and several of them were worse than the ones it does.

The API client's retry policy did not distinguish reads from writes, so a network failure on a write could be retried and duplicated. Server errors still retry; network failures on writes no longer do. Offline requests now short-circuit to an offline state in about ten seconds, instead of spinning for a minute towards a timeout that was already certain. Error states had drifted into three different vocabularies across the app and were consolidated into one component and one label.

On the backend, a sweep turned up the standard FastAPI trap: handlers declared async while the database code inside them is synchronous, which blocks the event loop. Meal-plan generation was the worst case: one user generating a plan froze every other request for seconds. Converting them freed the event loop and surfaced two further bug classes during verification, including domain errors being re-wrapped as server errors, which the client then dutifully retried.

And two iOS rendering bugs got their own investigations, both of which are written up separately: a ScrollView that scrolled into empty space and traced to a framework-level view-recycling defect, and the keyboard-inset leak behind it.

None of this was on Apple's list. All of it is the difference between an app that passes review and an app that survives its first thousand users.

Metadata is where a good product gets rejected

This is the part I underestimated, and the part that took longest. Budget a fortnight rather than an afternoon, because the listing is not a form. It is two workstreams: a design deliverable with hard specifications, and a compliance surface where the rules are not only Apple's.

Every language you ship is a complete listing. Name, subtitle, keywords, description, screenshots, each one written rather than translated. Anovi ships English and German, so the German is written natively: informal register, German legal vocabulary, and the official phrasing for health claims under Regulation (EU) No 432/2012. Machine translation is not available to you if your app makes any claim about health, because the permitted wording is specified in law rather than chosen for tone.

Screenshots are a design job with a spec attached. Two device sizes across two languages is four sets, and every one has to survive rules that have nothing to do with how it looks:

No alpha channel, per Apple's screenshot specifications. The check is per pixel, so an image that looks entirely opaque but carries transparency still fails. Design tools export with alpha by default, so flatten deliberately. The same applies to the 1024×1024 icon. Mine carried one, and all four sets had to be re-exported.
They have to show the app in use (2.3.3), not title art, a login screen or a splash. Overlaid text is allowed.
Everything has to suit a 4+ audience (2.3.8) regardless of the app's own rating, which constrains the imagery as much as the copy.
No references to other platforms (2.3.10). Scrub mentions of Android from screenshots and copy both.

The compliance surfaces are the ones with dependencies you do not control.

Legal URLs have to be live at the moment of submission, and if you ship more than one language, make them locale-explicit rather than asking a single URL to guess at the reader.
Privacy labels have to agree with your privacy manifest. Build both from a written inventory of what your app and every SDK inside it actually send, so the two declarations cannot contradict each other later. Working out what your analytics, crash reporting and payment SDKs collect is the real task. The form itself takes an hour.
The age-rating questionnaire has to be answered against what the app does. One trap worth naming: the mitigation checkbox about social media being disabled for under-13s asserts an age-range integration you may not have, and it only applies if you declared a social surface in the first place.
The review notes are a product document, not a formality. Where each gated feature is, which account reaches it, what to tap, with every label checked against the actual strings in the build.
Availability is a decision. Anovi ships to twenty-nine EU and EEA countries with automatic addition of new territories switched off, which is a choice about which legal regimes you have agreed to operate under.

A good product gets rejected for reasons that have nothing to do with the product. Metadata is where that happens.

Account deletion is easy to claim and easy to half-build

Guideline 5.1.1(v) requires that an app supporting account creation must also offer account deletion within the app. That is easy to claim and easy to half build, particularly once a payment processor is holding a record of the user too.

So it was run for real before submission, on a live account, through the in-app flow rather than through a script. Afterwards: the authentication record gone, twenty user-scoped tables at zero rows for that user, and the RevenueCat subscriber deleted. The app also warns before deletion that removing the account does not cancel an Apple subscription, because it cannot, and tells the user where to do that.

Re-verified on the exact binary that ships

Production signing and production purchase configuration are not the same as development. A test that passed on a development build is evidence about that build and nothing else.

So the gate before submission was narrow and specific: cold launch, and a real sandbox purchase, on the exact binary going to Apple. Release hygiene was checked on that binary too, that console output is stripped, that the development-only tier switch is absent, that no environment file rides along inside the package. The git tag went on afterwards, not before, so the tag means the thing that was verified rather than the thing that was intended.

The bug I shipped while waiting, because a reviewer would hit it

Submission was 27 July at 17:09. Four items go into review together: the binary, the subscription group, and both subscription products. After that, hands off App Store Connect entirely, because editing a submitted item pulls it back out of the queue, and all three demo accounts frozen so nothing changes underneath a reviewer.

Hands off the store is not hands off the work. The day after submitting, I finished root-causing a logout bug that had been surfacing intermittently. The cause was that signing out was revoking every session for that user rather than the one on the device, so a sign-out in one place logged the user out everywhere, including sessions that had nothing to do with it. The fix scopes the revocation to the calling session.

That went to production immediately rather than waiting for the verdict. A reviewer moving between a free demo account and a paid one is exactly the pattern that triggers it, and a reviewer being mysteriously signed out mid-review is not a thing you want to explain afterwards. A second contributing cause, a keychain accessibility setting that made tokens unreadable when the app launched into the background before first unlock, was fixed on the client shortly after.

One session, and an approval

The app sat in "Waiting for Review" for ten days, and for nine of them nothing happened at all.

On the morning of 6 August a reviewer signed in on the free demo account at 07:01 UTC and worked through the app in that single session. That it took one session is the part the preparation paid for: the accounts were seeded so every screen had real data in it, and the review notes routed a reader to each gated surface in turn, so there was no need to come back for a second look at something that had not been reachable the first time. The approval email arrived the same morning.

What I have is the server's view, not the reviewer's. I know when they signed in and that the verdict followed within hours, and the backend traced every endpoint that session called. What it cannot show is what happened on screen between those calls: what they tapped, what they lingered on, what they were trying to break. I would rather say that than turn request logs into an itinerary. Nothing came back through Resolution Center either: no rejection, no questions, no request for clarification, no second build.

Ten days of waiting, and a review that began and finished inside one morning. That ratio is the whole point. Almost none of the time an app spends in review is review, which means almost none of the outcome is decided there. It is decided in the weeks before, in a checklist you keep current, a purchase flow you test on the first day you are allowed to, and a listing you check character by character because the form will not tell you which of the four thousand is wrong.

If you want the same material as a working checklist rather than a story, the companion piece has it, sourced to Apple's rules rather than to mine.

If you are heading into a submission yourself, you can write to me at hello@pragathijayaram.com and describe what you are shipping. I am happy to go through it with you, whether you want a checklist of your own or a second pair of eyes before you submit.

The bug that survived being recycled: automaticallyAdjustKeyboardInsets and Fabric view recycling on iOS

Pragathi Jayaram — Wed, 05 Aug 2026 14:08:17 +0000

After logging a meal in Anovi, the nutrition app I build, the next screen opened normally. The content was there. Then the first scroll ran past the end of it, into empty space that should not have existed, and stopped.

Dragging in that space did nothing. Not a slow scroll, not a bounce. Nothing moved, because there was nothing under my finger. The content was somewhere above me and there was no way to reach it. The only way out was to kill the app.

It was not every screen and not every time, which is what kept it alive through earlier rounds of testing. It produced no crash, no error, and no failed request.

In short. On iOS with the New Architecture, a scroll view that opted into keyboard inset handling can leave that behaviour switched on when React Native recycles it. The next screen to inherit that view gets a phantom inset it never asked for. Filed as react-native#57755.

If you just want to check and fix your own app, that is a separate, shorter piece.

The evidence that was missing

Every request in the sequence returned what it should, in the time it should. Nothing failed, nothing timed out, nothing appeared in the logs at the moment things went wrong. The app had not crashed and was not in an error state.

Healthy logs are usually read as the absence of a finding. Here they were the finding, because they eliminated the entire category I had been searching in. That is what promoted the next detail from background noise to the only lead.

The next detail was the keyboard. On the broken screens it appeared, briefly, and went away again. On a screen with no text input on it and nothing focused.

A keyboard reacting where there is nothing to type into is not a rendering bug. Something was still listening.

The screen that broke was not the screen at fault

React Native's new architecture recycles native views. Rather than destroying a component's native view and building a fresh one, it resets the existing view and hands it to the next component that needs the same kind. On iOS, that reset happens in a method called prepareForRecycle.

Recycling is only safe if the reset is complete. Anything left behind belongs to whoever inherits the view next.

A scroll view can opt into having iOS adjust its insets when the keyboard moves, with a prop called automaticallyAdjustKeyboardInsets. Underneath, that sets a flag on the native view and gates a keyboard observer that lives for as long as the view does. prepareForRecycle does not clear that flag.

So the broken screen was innocent. It had no text input, no keyboard props, and nothing to do with any of this. It had simply been handed a view that came out of the pool still holding someone else's settings.

Where the keyboard came from

The view came from the meal logging modal, which does have a scroll view with the prop set and a search field that focuses itself.

The interesting part is what happened when I closed it. Tapping Done dismissed the keyboard, reset the modal's internal flow back to its search step, and hid the modal, all in the same render batch. Resetting the flow remounted the search field, its autoFocus fired, and the app opened a keyboard inside a modal that was already closing.

That is the flicker. Not a leftover from typing, but a keyboard my own code summoned into a dying screen. Its scroll view then went into the recycle pool while that keyboard was still up.

None of that is a bug. A keyboard being up while a screen goes away is ordinary, and the framework is meant to survive it. What it did instead was hand the next screen a view that was still holding the last one's settings.

Building something that fails on demand

An explanation that only reproduces inside a nutrition app is not much use to anyone, and it is not something a framework maintainer can act on. So the next step was the smallest thing that still fails: a modal with the prop and a focused input that kills itself mid-animation, then a plain scroll view that mounts straight afterwards and reports its own geometry.

The detector that cried wolf

Getting the measurement right took longer than finding the bug.

The first version reported failures that were not failures. A scroll view settling after a bounce moves on its own, and sampling at the wrong moment records that jitter as displacement. Several iterations went into separating "this view is still settling" from "this view has been moved by something else".

A detector that reports a bug which is not there is worse than no detector, because it makes the real signal unfalsifiable.

Everything downstream of it, including the controls, would have been noise interpreted as evidence.

Once it was honest, the numbers were unambiguous. A scroll view that never asked for keyboard insets, with the keyboard hidden, reporting a bottom inset of 217.3 points. Its content was 840 points tall in a 234 point window, so the furthest it should ever scroll is 606. It went to 823.

Physical iPhone, iOS 26.5.2, Release build, React Native 0.86.2, New Architecture. The victim sets no keyboard props of any kind.

The controls are the argument

A reproducer that fails is a claim. A reproducer that fails, and stops failing when you remove exactly one ingredient, is evidence.

Two controls, each from a freshly killed process. Turn off the inset prop: nothing. Dismiss the keyboard and let it settle before the modal closes: nothing. Each ingredient is necessary and neither is sufficient. The failure needs a view configured for keyboard insets to be recycled while its observer is still live.

Measuring it instead of reasoning about it

Everything so far was inference, from reading source and watching behaviour. The mechanism deserved a measurement, so I instrumented the framework itself: every keyboard delivery logged with the view's address and whether it was on screen or in the recycle pool.

rec-in  view=0x108118c00 ivar=1          entering prepareForRecycle
rec-out view=0x108118c00 ivar=1          leaving it, flag still set
kbd     view=0x108118c00 ivar=1 POOLED
write   view=0x108118c00 bottom=217.3 POOLED    ‚Üê inset written while pooled
props   view=0x108118c00 old=1 new=0 ivar=0     ‚Üê next screen mounts, flag cleared

The write lands while the view is sitting in the pool, 105ms before anything mounts on it. When a screen does mount, the flag is cleared immediately, so the screen you can see is never written to at all.

That ruled out the explanation I had been carrying. An earlier test, where a poisoned view's scroll position moved after I focused an unrelated text field, had looked like proof that the recycled view was still listening while mounted. It was not. The keyboard changed the layout, the window grew from 234 points to 299, the furthest legal scroll position dropped by 65, and iOS pulled the offset back to the new limit. Arithmetic, not a live listener.

What is actually happening

The pooled view keeps receiving keyboard notifications and keeps writing insets onto itself. It is not stale; it is current. It tracks the keyboard continuously, taking a real value when a keyboard rises and zero when it falls.

Whatever value it happens to be holding at the moment someone inherits it is what that screen is stuck with, because the inset is only reassigned when a component's props change it, and a component that never set the prop has nothing to reassign.

Which means the whole thing turns on timing. Sweeping the delay before the modal tears itself down, ten cycles each from a fresh process:

modal torn down after	corrupt readings	phantom inset
~120ms	36	217.3
~220ms	0	0.0
~320ms	0	0.0
~520ms	0	0.0
keyboard dismissed first	0	0.0

Only the earliest teardown reproduces. Wait longer and the keyboard's own disappearance reaches the pooled view first, zeroes the inset, and the pool quietly cleans itself. The bug needs a screen to mount during the narrow window while a keyboard is up.

That is also why it was intermittent in production, and why it survived earlier testing rounds. Most of the time nothing mounts inside that window.

Why it could not be scrolled back

The phantom inset extends the scrollable range past the end of the content, and that extra region has no view underneath it. So it takes no touches. A drag there produces no scroll events at all.

In the reproducer a sliver of the last row stays visible, so you can grab that and pull yourself back. In the app the scroll views were full screen. Once the content had left the viewport there was nothing to grab, and no gesture in the app could recover it.

A screen recording of the reproducer on a physical device is on the original article: several poison cycles, a scroll up into the space that should not exist, then taps on an unrelated input.

That is the difference between a layout glitch and a screen that is finished until you kill the process.

What happened after filing

I reproduced it unchanged on React Native 0.86.2, the latest release at the time, and filed it as react-native#57755 with a public reproducer.

Two pull requests followed, from people I have never met. The second carries a regression test covering the whole lifecycle, and a Meta engineer imported it for internal review the same morning it appeared.

Its two lines are small: clear the flag when the view is recycled, and stop guarding the assignment behind a props comparison so a recycled view can be re-armed properly. I applied them to the reproducer and ran it on the phone that found the bug in the first place. Baseline immediately before: 36 corrupt readings in 10 cycles. With the patch: 49 cycles, zero.

What I would take from this

The healthy logs were the finding. They eliminated a whole category, which is what turned a flicker into the only lead.

Controls before claims. Any bug can be explained by a plausible story. The question is which single ingredient you can remove to make it stop, and whether you have actually tried removing it.

A detector that lies is worse than no detector. Most of the reproducer work went into eliminating false positives, not into finding the failure.

Instrument the explanation, not just the bug. A story that fits every observation is not the same as a correct one. Mine was in the right place and the wrong moment, and only logging the framework showed the difference.

If you think your own app has this, the checks and the three ways to fix it are in a shorter companion piece.

The reproducer is at github.com/PragathiJ/rn-aaki-recycle-repro.

I write about production engineering and applied AI at pragathijayaram.com.

automaticallyAdjustKeyboardInsets is leaking into your other screens: how to check and fix it

Pragathi Jayaram — Wed, 05 Aug 2026 13:53:30 +0000

A screen opens normally, then scrolls past the end of its content into empty
space, and dragging in that space does nothing at all. Restarting the app is the
only way out.

If that sounds familiar, this is a React Native framework defect, not your code.
This page is the operational version: how to confirm it, how to find every source
in your project, and what to do. The investigation behind it, including why it
took a while to understand, is here.

Scope. iOS only, New Architecture only. The code involved is the Fabric iOS
scroll view, so the old architecture and Android take different paths.
Reproduced on React Native 0.81.4 and 0.86.2. Filed as
react-native#57755.

What is going wrong

A scroll view that sets automaticallyAdjustKeyboardInsets keeps that behaviour
switched on when React Native recycles its native view. While the view sits in the
recycle pool it carries on receiving keyboard notifications and writing insets
onto itself. The next component to be handed that view inherits whatever value was
there, and nothing puts it back, because a component that never set the prop has
no inset of its own to assign.

The result is a scroll view with extra scrollable space below its content. That
space has no view underneath it, so it takes no touches, which is why you cannot
drag your way back out of it.

Confirm it

The first sign is a keyboard appearing on a screen with nothing focused. That is
the tell, not the bug.

The test is to read the inset on a scroll view that should not have one. Put this
on a screen that sets no insets of its own, scroll it with the keyboard hidden,
and watch the console:

const reported = React.useRef(false);

<ScrollView
  scrollEventThrottle={16}
  onScroll={(e) => {
    // contentInset is iOS-only; on Android nativeEvent has no such field.
    const bottom = e.nativeEvent.contentInset?.bottom ?? 0;
    if (bottom > 0 && !reported.current) {
      reported.current = true;
      console.warn('phantom bottom inset', bottom);
    }
  }}
>
  <View style={{ height: 2000 }} />
</ScrollView>;

Two details decide whether this test is worth anything. The scroll view needs
content taller than itself, or it never scrolls, onScroll never fires, and you
will conclude you are clean without having tested anything. And the reading has to
be gated, because at a 16ms throttle an ungated console.warn buries your log.

A scroll view that never opted in should report zero. Anything else means it is
sitting on a view that came out of the pool still armed.

Find every source

grep -rn "automaticallyAdjustKeyboardInsets" src/
grep -rn "contentInset" src/   # also catches contentInsetAdjustmentBehavior

The second search matters more than it looks. Any prop that writes native insets
belongs to the native view, and therefore to the recycling pool, so a static
contentInset combined with an automatic contentInsetAdjustmentBehavior is the
same class of risk even though it has nothing to do with keyboards. In my own
sweep that turned up a grid component the first search had missed.

Then run both again against node_modules. The pool is per process, not per
module, so a scroll view inside a dependency arms it exactly as well as one of
yours. You can clean your own code completely and still be handed a poisoned view by a library you did not write.

Fix it

Option 1, remove the prop. Handle keyboard layout explicitly instead. This is
what I shipped.

// Before: the flag does the layout, and the native view keeps listening
<Modal visible={visible}>
  <ScrollView automaticallyAdjustKeyboardInsets>
    <TextInput autoFocus />
  </ScrollView>
</Modal>

// After: explicit layout, nothing left armed on the native view
<Modal visible={visible}>
  <KeyboardAvoidingView behavior="padding" style={{ flex: 1 }}>
    <ScrollView contentContainerStyle={{ paddingBottom: 24 }}>
      <TextInput autoFocus={visible} />
    </ScrollView>
  </KeyboardAvoidingView>
</Modal>

The autoFocus={visible} change matters more than it looks. Focusing on mount is
what starts a keyboard animation during modal presentation, which is exactly the
window the defect needs. Watch for the same shape anywhere a modal resets its
internal state as it closes: that can remount a focused field and open a keyboard
inside a screen that is already going away.

One caveat: KeyboardAvoidingView with behavior="padding" inside a Modal
behaves differently depending on presentation style and often wants a
keyboardVerticalOffset. Treat it as a shape to adapt, not a drop-in.

Option 2, keep the prop but dismiss the keyboard first. Dismiss it and let it
settle before the screen unmounts. This came back at zero in the reproducer. It is
narrower than option 1, because it depends on every exit path from that screen
doing the same thing.

Option 3, patch the framework locally. Until the upstream fix ships you can
carry it as a patch-package patch. In RCTScrollViewComponentView.mm, clear the
flag on recycle and assign it on every update instead of only when it changes:

// prepareForRecycle: disarm before the view goes back in the pool
_automaticallyAdjustKeyboardInsets = NO;

// updateProps: drop the old-vs-new condition around the assignment
_automaticallyAdjustKeyboardInsets = newScrollViewProps.automaticallyAdjustKeyboardInsets;

Both lines are needed. The first stops the leak. The second matters because
prepareForRecycle does not reset the stored props, so once the flag is cleared a
view being reused by another component that also wants keyboard insets would
skip the assignment and silently lose the behaviour.

This is the substance of react-native#57811, which a Meta engineer has imported for internal review. I verified those changes against the reproducer on a physical device: 49 cycles, zero failures, where the unpatched build produced 36 failures in 10 cycles.

If you are on 0.86.2 and patching the framework, note that React core ships
prebuilt, so edits to RCTScrollViewComponentView.mm in node_modules never
reach the binary. You need RCT_USE_PREBUILT_RNCORE=0 and a fresh pod install,
or the patch silently does nothing.

What does not work

Scrolling the screen back to the top when it opens. I shipped that early and it
does clear the wrong opening position, which is enough to make it look like a
cure. It does not remove the phantom inset, so the dead space is still waiting at
the bottom.

How to tell you have fixed it

Run the confirmation check again after the flow that used to break things. Zero
inset, and a scroll to the bottom that stops at the end of your content with
nothing beneath it.

The reproducer is at
github.com/PragathiJ/rn-aaki-recycle-repro.

I write about production engineering and applied AI at
pragathijayaram.com.