Google Play staged rollouts: percentages, halting and when to go to 100%

Shipping an Android update to every user at once is a bet that nothing slipped through testing. A staged rollout lets you make that bet with a small share of your users first, look at what happens, and only then go wider. This guide covers the Google Play tracks a release passes through, how staged rollouts work, what to watch before raising the percentage, what halting really does, and how to drive all of it from the Play Developer API.

The Google Play tracks

Every release in Play Console lives on a track. There are four standard ones:

• Internal testing. Up to 100 testers you add by email list. Releases reach them within minutes and may skip Google's usual policy and security review, which makes it the place for a quick QA round.
• Closed testing. Testers you choose through email lists, Google Groups or, for some accounts, organizations. You can create extra closed tracks for different groups, and run several closed tests at the same time. In the API the default closed track is called alpha.
• Open testing. Anyone can join from the app's Play listing, with no limit by default. In the API it is beta. Only one open test runs at a time.
• Production. Everyone who can find and install the app.

Apps for Wear OS, Android TV, Android Automotive, Android XR or Google Play Games on PC also get form factor tracks. In the API they carry a prefix, such as wear:production or tv:beta, and each one has its own releases and rollout.

One rule shapes the first release of many apps: a personal developer account created after 13 November 2023 must run a closed test with at least 12 testers opted in for 14 days in a row before it can apply for production access. Organization accounts are exempt.

What a staged rollout is

A staged rollout sends a production update to a percentage of users instead of everyone. In Play Console you enter the percentage when you roll out the release; in the API it is the release's userFraction, a number between 0 and 1, so 0.05 means 5%. While the release is partly rolled out its status is inProgress. The rest of your users keep getting the previous completed release.

Google picks the users at random for each release, from both new and existing users. You do not choose who gets it, and there is no way to put your own team at the front of the queue, which is what the testing tracks are for. If you limit the rollout to certain countries, only users with Play accounts in those countries are eligible, and countries cannot be removed once the rollout has started.

Staged rollouts apply to updates. The very first production release of an app goes to everyone who installs it.

Sensible percentage steps

There is no required schedule. A common pattern for an app with a steady user base is 1% or 2%, then 5%, 10% or 20%, 50% and finally 100%, holding each step for one to two days. Small apps often skip the lowest steps, because 1% of a few thousand users is too few people to tell you anything. The question at each step is simple: have enough people used this version for the numbers to mean something, and do they look as good as the last release?

What to check before raising the percentage

• Android vitals. Filter vitals by the new version code and compare the user perceived crash rate and ANR rate against the previous release. Google's bad behavior thresholds are 1.09% for crashes and 0.47% for ANRs across all devices, and 8% on any single phone model. Crossing them can lower your app's visibility on Play, so a new version that moves toward them is a reason to stop.
• Crash clusters. A crash rate that looks fine overall can hide a new crash on one Android version or one manufacturer. Look at the top new clusters, not only the total.
• Reviews. Filter reviews by app version. A few new one star reviews mentioning the same screen are often the first sign of a bug that does not crash.
• Your own signals. Backend error rates, sign in success, payments, and support email. Play cannot see a broken API call or a checkout that silently fails.

Data takes time to arrive. Vitals and reviews from the first few hours of a 1% rollout are thin, so give each step long enough to collect real use before you decide.

Halting a rollout

If something is wrong, halt the release. In Play Console that is Halt rollout; in the API you set the release status to halted. From then on, no more users receive that version. Users who already updated keep it: halting does not uninstall the update or move anyone back to the previous version, and Android has no way to do that for an app from Play. New and remaining users get the previous completed release.

So the real fix for a bad release is a new one. Build the fix with a higher version code, ship it as its own staged rollout, and the users stuck on the bad version update to it like any other update. That is also why it pays to keep the first steps small.

Google also lets you halt a release that is already at 100%, on any track except internal testing. The halted version stops being served and the previous fully rolled out release takes its place for new and eligible users, provided that release has no policy problems. The release that steps in is called the serving fallback release, and it cannot itself be halted.

Resuming, raising and completing

A halted release can be resumed. You set a rollout percentage again and the rollout carries on with the same set of users it was already reaching. If the halt was for a backend problem you have since fixed, resuming is fine. If the bug is in the app, ship a new version instead.

You can only raise a rollout percentage, never lower it. If 20% turns out to be too many, the answer is to halt, not to go back to 5%. Plan the steps with that in mind, because each one is a one way door.

Completing the rollout sends the release to 100% of users. In the API you set the status to completed and drop the userFraction. The completed release replaces the previous one as the version everybody gets, although Google notes the last stretch can still take several hours to reach all devices.

Promoting a release between tracks

You do not upload the same bundle again to move it from internal testing to closed testing, or from open testing to production. Play Console has a Promote release action on each track: it creates a release with the same app bundle on the track you pick, where you can edit the release notes and, on production, choose a rollout percentage. In the API the same thing is a tracks.update on the target track that lists the existing version codes. Promoting to a closed, open or production track goes through Google's review like any other release.

Release notes per language

Every release can have its own notes, shown under "What's new" on the Play listing. The limit is 500 characters per language, counted as characters, not bytes, so a second language gets its own 500. Notes can be updated on a release that is already live; they are one of the few changes that publish without waiting for managed publishing. Write them for users, not for your team, and say plainly what changed. The guide to building on GitHub Actions and uploading to Google Play shows where notes fit when a pipeline creates the release.

Managed publishing and review timing

Most changes, including new releases, rollouts and store listing edits, go to Google for review. Review usually takes a few hours but can take up to seven days, and longer in rare cases, so Google suggests leaving about a week before a date that matters.

With managed publishing turned on, approved changes wait in Changes ready to publish until someone presses Publish changes. That lets you send a release for review early and still pick the moment it goes live, and lets you group a release with a listing update. A few changes skip the wait and publish as soon as they are approved, among them price changes and release notes edits. You can turn managed publishing on or off at any time, even while a change is in review.

Automating with the Play Developer API

Everything above can be scripted with the Google Play Developer API, using a service account invited in Play Console with release permissions on the app. All release changes happen inside an edit:

1. edits.insert opens an edit, a working copy of the app's state.
2. edits.tracks.get reads a track and its releases.
3. edits.tracks.update writes the track's releases, each with versionCodes, status (draft, inProgress, halted or completed), userFraction for a staged release and releaseNotes per language.
4. edits.commit applies the whole edit at once and sends it for review.

Raising a rollout from 10% to 25% is a read, a change of userFraction from 0.1 to 0.25 and a commit. Halting is the same with status set to halted. Two warnings: committing an edit, or saving in Play Console, invalidates other open edits for the app, so two scripts acting at once will fail one of them; and an app that has never been published only accepts draft releases through the API.

A script that raises the percentage every day on a timer is easy to write and easy to regret. The point of a staged rollout is that a person looks at the numbers between steps. Automate the mechanics, keep the decision.

Managing Play releases in AppForShare

AppForShare's Google Play releases page puts every track of a shared Play app on one screen, with its releases, status, rollout percentage and release notes. It works through your workspace's own Google Play connection, and every change is made by an Admin of the workspace who ticks a confirmation before it goes to Google. AppForShare never changes a release on its own: it does not raise percentages on a schedule, does not watch vitals and does not halt anything by itself.

• Pro. Read every track and its releases, edit release notes per language on testing tracks (500 characters each), and promote a release between testing tracks, for example from internal testing to closed testing.
• Team. Everything in Pro, plus production: promote a release to production as a draft, a staged rollout at a percentage or a full release; raise the rollout percentage; halt, resume and complete a rollout; and set the Google Groups that may test on closed testing tracks. The page refuses a lower percentage, as Google does, and points you to halting instead.

Each change is one Play edit committed to Google, which reviews it as usual. The page keeps a history of who did what and when, and every Google call appears in the connection's activity log. See pricing for the rest of each plan.