Release Your App Update in a Staged Rollout
With staged rollouts, you can release the upcoming version of your app in a gradual way, slowly incrementing the percentage of users who receive the update. In this way, you can limit the scope of any bugs or issues in your release, as well as test enhancements or other features in a controlled, measurable way.
- Staged Rollout Concepts
- Staged Rollout Tasks
- FAQ for Staged Rollouts
Staged Rollout Concepts
The following sections cover common concepts related to staged rollouts.
Advantages of Staged Rollouts
When you release an update to an existing app, you can publish your new version in a staged rollout. Staged rollouts let you limit your app's release to a subset of users (choosing between 1%, 5%, 10%, 20%, or 50%) to test the new APK. You can gradually ramp up the percentage of users until the release is available to all of your users. The following screen shows an app in staged rollout:
Staged rollouts provide a way to limit the scope of issues introduced with new versions of your APK. For example, if your release performs poorly on user systems, it's better if only 5% of users experience this rather than your entire user base. You can fix any issues in your app and push out a new version to the users, continuing to test each APK.
Note that the testing you perform in your staged rollout should be performance testing rather than functional testing. Since you're rolling out the app to a percentage of your entire user base, you should have already caught major issues such as frequent app crashes or other bugs.
In addition to performance testing, you can also use staged rollouts as a means of experimenting with new features, or as a way to do A/B testing. For example, suppose you have a new feature in your game app. You can include the new feature in an upcoming version and push the version out in a staged rollout to a subset of users. You can then evaluate the performance of your app with the new feature compared to the performance of your app without the feature.
In this way, you can see what's working with the audience in a controlled, measurable way rather than pushing releases out to every user at the same time. Staged rollouts lets you be more strategic with your app releases and enhancements.
Requirements and Limitations for Staged Rollouts
There are several requirements and limitations with staged rollouts:
- Limited to new versions for existing apps: Staged rollouts can be used only for upcoming releases of existing, live apps. You can't use staged rollouts for a new app that has never been published to the Amazon Appstore.
- Existing device support only: Staged rollout versions are pushed out only to the same devices that your existing, live app already supports. For example, if you create a staged rollout and add support for devices that your live app doesn't already support, those devices won't be able to discover the staged rollout. However, the Appstore ingestion team will test your staged rollout version against the new devices prior to approving your app.
- Only the APK file is included: Metadata from live app version will continue to be displayed to the staged rollout recipients (for example, the description, images and multimedia, availability and pricing, device support options, and more). Users will receive only the APK file in your staged rollout.
- Android APKs only: Staged rollouts is limited to Android APKs only and is not available for web apps.
- Live app must not be suppressed: If the live version of the app is suppressed or in the process of suppression, staged rollout is not available.
- 10,000 unique downloads minimum: Staged rollout is available only when the live version of your app has had at least 10,000 unique downloads ("unique app purchases") in the past three years. You can see your app downloads in the Reporting section of the Developer Console. (The 10,0000 minimum establishes enough volume for the staged rollout data to be meaningful.)
- Updates to price or IAP items not allowed: Updates to your app's price or in-app purchasing (IAP) items are not allowed in the staged rollout version.
- Content Rating cannot change: You can't change the Content Rating of your app in a staged rollout (options on this tab are locked). If your staged rollout version requires a more mature content rating than your existing, live app, your staged rollout version won't be approved.
How the Staged Rollout Audience Is Selected
When you start a staged rollout, you can select the percentage of users you want to be included. You select the rollout distribution by going to Staged Rollout > Increase staged rollout %, as shown in the following screenshot:
You then see a dialog box with rollout percentage options:
The rollout percentage is calculated based on the existing user base of your live app. For example, if your live app has 20,000 installs on user devices, when you select 10% as the rollout percentage, the 10% is calculated against your 20,000 users, which would mean 2,000 users will be included in the staged rollout distribution. Note the following about how users are selected:
- Users are randomly selected from (1) the existing base of users who already have the live version of your app and (2) prospective users who are eligible to install your app (eligible because their devices support your live app). The same device support options of your live app are used to define the potential audience for your staged rollout version (regardless of the device support options you select in your staged rollout). For example, suppose your currently published live app doesn't support Fire TV Gen 1, but your new app in staged rollout does support Fire TV Gen 1. The prospective customer base in the staged rollout will not include users with Fire TV Gen 1 devices.
- Users are selected randomly. You can't specify which particular users are included in the rollout (unlike Live App Testing, which lets you curate a list of specific testers).
- Users are selected from the same countries that you selected on the Availability & Pricing tab for your live app.
- If your app is available on multiple devices (such as on both tablets and TV devices), users are randomly selected related to the APK you're replacing. For example, if you're replacing the Fire TV app, users who installed the Fire TV APK (or who are eligible to install it) might receive the staged rollout version. Tablet users would not receive the new version unless you were also replacing the tablet APK.
- You cannot use staged rollouts to test on new devices. If you have multiple APKs for your app, users are selected among the users who have the APK you are replacing, or who are eligible to install the APK you are replacing. For example, if your app has APK1 and APK2, and your staged rollout replaces APK2, only users who already installed APK2 (or who are eligible to install it) will be included in the staged rollout distribution.
The Scope and Workflow with Staged Rollouts
When you create a new Upcoming Version for your app, you will see an option to submit your app as a Staged Rollout:
When you first create a staged rollout, you update the information on the metadata tabs (General Information, Availability & Pricing, Description, Images & Multimedia, and APK Files) as usual. (Content Rating is locked.) However, note that during the staged rollout, only the APK is pushed out to users, not any updates on the metadata tabs.
For example, suppose you create a staged rollout and edit the Description tab to explain a new feature in the release. Users who are included in the staged rollout won't see the updated description. They will receive only your updated APK file because only the APK is included in the staged rollout. However, updating these metadata tabs for your staged rollout will allow you to publish your app immediately when you finish with staged rollout, without having to undergo Appstore testing and approval again later.
When you initiate your staged rollout, the new version must be approved by the Appstore (as per compliance policies). It typically takes 1-2 days for the version in your staged rollout to be approved and go live. A date and time appear on the Staged Rollout tab indicating when your app will go live to the percentage of users you selected.
After your staged rollout is live, you can increment the percentage as desired (ramping up from 1% to a maximum of 50%). (Note that you cannot lower the rollout percentage.) No approval is needed for each incremental increase. The rollout percentage will go into effect immediately based on your selections.
After you begin your staged rollout, you'll notice that the submission tabs (such as Description, APK Files, etc.) become locked — the Edit button is grayed out.
When you increase the rollout percentage, you can't make any changes to information on the tabs, not even to the APK file. Once a staged rollout is underway, you can only increase the rollout percentage for the APK that has already been approved by the Appstore. (This is to ensure that only tested APKs are made available to customers.)
If you want to make changes to any of the tabs (including replacing the APK file on the APK Files tab), you must halt the staged rollout by selecting Halt staged rollout from the Staged Rollout menu, as shown in the following screenshot:
You then confirm that you want to halt the rollout:
After you halt the staged rollout, choose to Edit Staged Rollout from the same Staged Rollout drop-down menu. Then the tabs become editable.
Once the tabs are editable, you can update your APK file (perhaps replacing it with an APK that fixes some issue you detected). When you're ready to resume the staged rollout, you'll see an option to "Resubmit and resume staged rollout."
Your app will need to go through testing and approval with the Appstore again, just as with the first version of your staged rollout.
Users who have already downloaded the previous version of your APK will keep the version they downloaded. The Appstore never reverts versions of APKs that users already downloaded to their devices. However, these same users who were already targeted for the staged rollout (and who downloaded a previous APK) will get the new version of your APK when you resume your staged rollout.
You can increase the percentage of users included in your staged rollout to a maximum of 50%. When you're ready to publish your app to all of your users, click the default Submit App button (the option to publish to 100% is not available from the Staged Rollout dialog box). Then confirm the submission in the Submit app dialog box:
Once the publishing process finishes, your app will then exit the staged rollout and go live for all users. Your app will not need to be retested by the Appstore again before going live. (Retesting and approval are needed only if you halt and edit your staged rollout.)
Testing Performed on Staged Rollouts
During staged rollouts, Appstore testing is performed during two periods only:
- When you start a staged rollout: The Appstore tests and approves your app when you initially begin a staged rollout. (See Start a Staged Rollout for details.)
- If you halt, edit, and resubmit a staged rollout: If you halt and edit a staged rollout, and then republish your APK to resume the staged rollout, the Appstore will also test and approve your APK. (See Update the APK File During a Staged Rollout for details.)
When you increase your staged rollout percentage, such as from 1% to 5%, or from 5% to 10% or more, the Appstore does not need to test and approve your app.
Staged Rollout Tasks
The following sections cover common tasks related to staged rollouts.
Start a Staged Rollout
To start a staged rollout, you follow the same initial process for adding an upcoming version of your app. On the Upcoming Version tab, you will see a Staged Rollout button. To start a staged rollout:
- Sign in to the Developer Portal.
- From the Dashboard (the default homepage), under the Amazon Appstore section, click App List.
- Click the app you want to update. (You can use staged rollouts only with existing, live apps.)
Near the top of the page, in the area below the name of your app, click Add Upcoming Version. A confirmation message appears — click OK to proceed.
The portal creates a new set of tabs for you. The General Information, Availability & Pricing, Images & Multimedia, Content Rating, and APK Files tabs are shown with green checkmarks to indicate that the required fields have been pre-filled with the information associated with your live app. The Description tab doesn't have a green check mark because the Release Notes field must be completed. When you add release notes and save the information, the tab will also have a green check mark.
Update the information on all of the submission tabs to correspond with your new release.
At the very least, update the Release notes field on the Description tab. Make other updates as needed for your new APK. For example, you might want to update image assets on the Images & Multimedia tab to correspond with your new release.
Note that you cannot make updates to the Content Rating tab for a staged rollout.Understanding which tab updates are included in a staged rollout
Any updates you make to metadata tabs aren't included in the staged rollout. (Metadata tabs refer to all submission information other than the APK file on the APK Files tab.) For example, updates to the description of image assets (made on the Images & Multimedia tab) won't be included. Users who receive the staged rollout would see the same images and description as shown in your live app. Only the APK file is pushed out during the staged rollout.
Even though information on the metadata tabs isn't included, you should still update the information as appropriate when you first begin your staged rollout. Having complete information for your upcoming version can help the Appstore team identify any potential issues early on. Later, when you decide to publish your app to 100% of your users, your app won't need to undergo testing and approval again. When you do fully publish your app to all users, they will see the new description and images (and other details you might have changed).
For more information about completing any of the submission tabs, see the following:
On the APK Files tab, replace your existing APK with a new version of your APK. (See Upload APK Files for more information on how to upload your APK.)Note: Rather than deleting your existing APK, replace it instead. Replacing your APK retains the same device support selections. In contrast, if you delete your APK, you will need to reconfigure the same device support selections as before.Important: Be sure to give your APK a higher
android:versionCodevalue than your live APK. Users will receive the updated APK only if the
versionCodevalue is higher than the current APK they have installed. Also, make sure your package name stays the same as your previous APK. (When you upload your APK, the Developer Console will automatically reject an APK that doesn't meet these
versionCodeand package requirements.)
- Click Staged Rollout.
In the Staged rollout dialog box, select the percentage of users who should receive the update. Options are 1%, 5%, 10%, 20%, and 50%.
For more information about how users are selected, see How the Staged Rollout Audience Is Selected. Note that you cannot lower the percentage — you can only increase it.
Your app goes into the submission queue for Appstore testing and approval. Once your submission is approved by the Appstore, the staged rollout will be pushed out to the rollout percentage you selected. The following screen shows how your submitted app appears, with the promised initialization time and date shown at the top:
During the transition of your app from submitted to live, the Staged Rollout version can have several stages: Submitted, In Review, and Approved. (These statuses appear on the Upcoming Version tab's title.) See the upcoming section, Monitoring the Progress and Performance of Your APK for more details on viewing the progress of the rollout.
View Details of Your Staged Rollout
You access details about your staged rollout similar to viewing any upcoming version in the Developer Console:
- Log into the Developer Console at https://developer.amazon.com.
- Go to Apps & Services > My Apps.
- Find your app. In the "Upcoming Version" column, click Staged Rollout.
Monitor the Progress and Performance of Your APK
You can see the rollout distribution percentage you selected for your staged rollout. To view the rollout distribution percentage, go to your staged rollout version in the Developer Console (see View Details of Your Staged Rollout). The rollout percentage appears in a callout at the top of the page.
The percentage shown reflects the distribution size you selected. Below the percentage is the time when the rollout distribution was initiated (or when it will be initiated).
You can leverage third-party analytics tools and in-app instrumentation to gather information about the number of installs and crash metrics in your staged rollout version. The Developer Console shows the selected rollout distribution percentage only.
Increase the Staged Rollout Percentage
If the APK is performing well, you'll likely want to increase the rollout percentage. To increase the rollout percentage:
- Go your staged rollout version in the Developer Console (see View Details of Your Staged Rollout).
- Click the Staged Rollout button, and then select Increase staged rollout %.
In the Staged rollout dialog box, select the percentage of users who should receive the update.
For example, suppose you initially selected 10%, and now you decide to increase the percentage to 20%. If you have 20,000 users total, the staged rollout distribution would increase from 2,000 to 4,000 installs.
No testing or approval is required from Appstore to increase the staged rollout percentage. However, you cannot make any changes to the tabs (including the APK Files tab) as you increase the percentage. If you want to update your APK, see the steps in the next section, Update the APK File During a Staged Rollout.
Update the APK File During a Staged Rollout
To update your APK during a staged rollout:
- Go your staged rollout version in the Developer Console (see View Details of Your Staged Rollout).
Click the Staged Rollout button, and then select Halt staged rollout. In the Halt staged rollout dialog box, click Halt.
When you halt a staged rollout, no additional users will receive the app version. Users who already received a rollout version keep that version (the Appstore doesn't remove or adjust any APK the user already downloaded).
- From the same Staged Rollout drop-down menu, select Edit Staged Rollout. Now the tabs become editable.
Go to the APK Files tab and replace your existing APK with a new one.Important: When you update your APK, choose to replace the existing APK rather than deleting your existing APK. If you do delete your APK, select the same device support options as your live APK. If you select new device support options, users with those new devices won't be included in the staged rollout, since the device support is based on your live app.
Remember to give your new APK an incremented
versionCodein your app's Gradle build file. The value of
android:versionCodein your app's manifest must be greater than both the previous staged rollout and live version.
When you upload a new version of your APK, the release ID will change. The release ID is only relevant if you're managing your APK through the Developer Publishing API (which is now deprecated). Users won't see the release ID.
- After you complete the options on the APK Files tab, click Save.
Click Resubmit and resume staged rollout.
When you republish your APK, your new APK will need to go through the submission process for testing and approval again. A date and time for the approval appear at the top of the Staged Rollout tab. When the new version becomes available, users who already received a staged rollout version of your APK will automatically get the updated APK.
Complete the Staged Rollout
When you're ready to push your staged rollout version out to 100% of your users, do the following:
Click Submit App.
By submitting your app, you will be publishing this version out to all your users. Submitting your app will also complete the staged rollout.
In the Submit app dialog box, click Submit to confirm that you want to publish your app.
You see a message that says "App Submission Successful." Your app is now in the process of being published to the Appstore. The publishing process can take between 30 minutes to several hours to complete. During this time, you will see your app's status as "Submitted." When your app is approved, the status changes to "Approved." Once publishing is successful, your app will be live.
Abandon the Staged Rollout Version
Suppose the new APK isn't performing as well as you hoped, and you want to completely abandon it. You want all users who received the staged rollout APK to downgrade, returning to the original APK.
To "abandon" the version used in your staged rollout, you halt and edit your staged rollout; then you replace your APK with your original APK (but with a higher
versionCode) and submit the new version to all your users. Follow these specific steps:
- Go your staged rollout version in the Developer Console (see View Details of Your Staged Rollout).
- Click the Staged Rollout button, and then select Halt staged rollout. In the Halt staged rollout dialog box, click Halt.
- From the same Staged Rollout drop-down menu, select Edit Staged Rollout.
On the APK Files tab (which is now editable), replace the staged rollout APK with your original APK. Make sure the
versionCodeis higher than the
versionCodein the previous staged rollout APK.Important: Users will only get an updated APK if the
versionCodeof the new APK is higher than the
versionCodeof the APK they have installed.
Click Save to save changes on the APK Files tab.
Although you could resubmit the APK to resume the staged rollout with a new APK, in this scenario, we will abandon the staged rollout workflow and publish the app to all users directly.
Click Submit App.
By submitting your app, you will be publishing this version out to all your users. Your app will need to undergo testing and approval from the Appstore.
In the Submit app dialog box, click Submit to confirm that you want to publish your app. You see a message that says "App Submission Successful."
Your app is now in the process of being published to the Appstore. The publishing process can between 30 minutes to several hours. Once the publishing process finishes, your app will then exit the staged rollout and go live for all users.
FAQ for Staged Rollouts
The following are common questions related to staged rollout.
- I halted my staged rollout, but the tabs aren't editable. Why?
- You must select Edit Staged Rollout from the Staged Rollout drop-down menu after halting a staged rollout.
- Can the staged rollout percentage increase automatically, based on a schedule I set?
- No, you must go into the Developer Console and manually adjust the rollout percentages.
- Are there any country limitations or types of apps not allowed to participate in staged rollout? For example, are there restrictions about Fire OS 5 versus Fire OS 6? Or what if my app is only available on non-Amazon devices?
- Any app can participate in staged rollout. There are no restrictions around Fire OS versions or device support. However, see the Requirements and Limitations for Staged Rollouts section for details about app restrictions due to the minimum number of app installs, limitations regarding price or IAP changes, and more.
- My app has multiple APKs. Can I create a staged rollout for one of the APKs?
- Yes. Multiple APKs target different devices. The APK you replace in a staged rollout will target the same devices and users as its corresponding live APK. To maintain the same device support options, make sure you replace your existing APK (rather than deleting and then adding the new APK).
- Can I include specific users in my staged rollout?
- No, the audience for staged rollout is randomly selected from your existing app's user base as well as prospective users whose devices support your app. See How the Staged Rollout Audience Is Selected.
- Does staged rollout work for both tablets and TV?
- Yes, you can create a staged rollout for any app in the Appstore as long as it meets the requirements as outlined in Requirements and Limitations for Staged Rollouts (for example, your app must have a minimum of 10,000 unique app installs to participate in staged rollout).
- Will I be notified by email when the staged rollout status changes?
- There are several different email notifications sent: (1) When you submit your app, (2) If the Appstore rejects your app, (3) If you suppress your app, (4) When your app is live. You will not receive email notifications when changing the staged rollout percentage.
- Why can't I select a 100% radio button on the Staged Rollout dialog box to immediately publish my app?
- We want to ensure the 100% selection is a conscious decision. To make your staged rollout live for all users, click the Submit App button on the main screen. Note that clicking on Submit App won't trigger the same workflow as that of standard upcoming version submission. If your app has already been approved in a staged rollout, clicking Submit App publishes the metadata and makes version as live (once publishing finishes), without requiring approval and testing.
- If a customer doesn't already have the app, can he or she participate in staged rollout?
- Yes, the list of users targeted for staged rollout is drawn from both your existing user base (those who already downloaded your app) and prospective users who are eligible (because of device support) to install your app. See How the Staged Rollout Audience Is Selected.
- Should I complete the metadata tabs prior to submission, even if customers won't see this information during the staged rollout?
- Yes. If the Appstore ingestion team identifies an issue with information in another tab (for example, you might have an image asset that has issues), they can identify this issue early so that you aren't delayed when you decide to go fully live. Once your app is approved for staged rollout, you won't need to undergo testing and approval again when you decide to publish your app to all users.
- How do I change my metadata tabs during a staged rollout?
- You must first halt the staged rollout by selecting Halt Staged Rollout from the Staged Rollout menu. After halting the staged rollout, select Edit Staged Rollout from the same menu. After you do this, you can make changes to the tabs. Your app will need to be tested/approved by the Appstore ingestion team before staged rollout begins again. Any time you change information on the submission tabs, your app must go through the approval process with the Appstore. This is why the tabs are locked from editing if you're merely increasing the rollout percentage.
- Can I use the future release date feature on the Availability & Pricing tab in combination with staged rollout?
- Yes, you can set a future release date and still use staged rollouts. If you enter a future publish date (such as two weeks in the future), the staged rollout won't begin until that date.
- If I expand the country availability, will my staged rollout target users from that newly added country?
- No, your staged rollout uses the same metadata information as your live APK. If you select a new geolocation, no users in that location will receive the update because your live APK is not available in that geolocation.
- How can I see ratings and comments from users about my staged rollout version?
- You have to use your own instrumentation and third-party app analytics to gather this information. Currently, no segmentation data is provided from Appstore for staged rollouts.
- Can I lower the staged rollout percentage?
- You cannot lower the rollout percentage. For strategies on how to downgrade the APK version that users have, see Abandon the Upcoming Version, Make Users Return to the Original APK.
- How does staged rollouts differ from Live App Testing?
- Live App Testing (LAT) is intended more for functional testing. With LAT, you have to manually specify the users who should test your app, and you're limited to 1,500 users max. LAT doesn't require your app to already exist on the Appstore, and you can push out the whole app (including the metadata information), not just the APK. In contrast, staged rollouts are intended more for performance testing. With staged rollout, users are randomly from the user base of your existing app or from prospective users who can install your app, based on the rollout percentage you select. You aren't limited to the number of users included in the staged rollout. Users receive the APK file only; apart from that, they continue to see the metadata from the live app. See How the Staged Rollout Audience Is Selected for more details.
- Can I leave an app in staged rollouts forever?
- You should always complete the staged rollout, eventually submitting the app to all of your users. However, nothing in the Developer Console enforces that you complete the staged rollout. See Abandon the Staged Rollout Version for more details.
- What happens if I change the device support selections for the staged rollout APK?
- Nothing adverse will happen because the staged rollout gets pushed out only to users who either installed your live app or who are eligible to install your live app. In your staged rollout version, if you select a new device that your APK supports (e.g., perhaps a new tablet device), the existing user base for your live app won't include any users with that new tablet device, so the staged rollout won't be pushed out to those tablet device users. Your staged rollout version uses the same device support options as your live APK. If you select new devices for your app, the Appstore team will test your app on these devices, but the new devices won't be included in staged rollout distribution.
- When users are randomly selected, do the selections maintain the same geolocation ratios as the live app? For example, if the app was installed by 1,000 users (500 from the US, and 500 from the UK), will the staged rollout maintain the same proportion (that is, out of the 200 users, 100 will be in the US and 100 in the UK)?
- No, ratios of selected users are not balanced with on existing geolocation densities. The selection is purely random, independent of geolocation factors (except for matching the live app's geolocation availability).
- After the staged rollout, do you have to add an Upcoming Version of your app to make it available to all users?
- No, you can submit the staged rollout version directly, without needing to create another upcoming version.
- Is the originating developer included in the staged rollout by default?
- No, the originating developer is not included by default.
- After I submitted my app, the screen says "App Submission Successful" but the status is still "submitted" and I see an option to "Cancel App Submission." Since my app was already approved, why isn't it immediately live?
- The publishing process can take as long as several hours to complete. During this time, you will see your app's status as "Submitted." When your app is approved, the status changes to "Approved." Once publishing is successful, your app will be live.
- With my staged rollout APK, I selected a device that my live APK doesn't support. Since staged rollout won't include any users with that new device, how will this new device be tested in the staged rollout?
- The Appstore team will test your APK against all supported devices you selected, regardless of whether your staged rollout includes those devices.
- When selecting device support options for my staged rollout version, are there any indicators in device support that let me know my APK won't be tested for that device?
- No, there are no indicators in the UI letting you know this.
- If I make updates to my live app metadata (updates that wouldn't require approval and testing by the Appstore), would the staged rollout version receive these updates as well?
- Yes, your staged rollout version receives the same metadata as your live app, so any allowed updates you make to the live app would apply to your staged rollout as well. However, only certain updates to your live app are allowed, such as editing your description and images. You cannot change the content rating or APK file for your live app without creating a new version. (When you edit information for your live app, the Edit button is not available for updates that require re-submission and approval from the Appstore.) You cannot create a new version in addition to the existing staged rollout version that you already created. For example, you can't change your live app's device support options on the APK Files tab because doing so would require you to create a new version. If you already have a staged rollout version, you cannot create another new version that lives alongside the existing staged rollout version.
- Is the user base for the staged rollout dynamic?
- Yes, as a percentage, the rollout distribution can grow if your user base grows. For example, if 5,000 new users download your app, your staged rollout will grow proportionally.
- Are users who haven't downloaded the latest version of the app (they have an older version) eligible for the staged rollout?
- Yes, anyone who is eligible for the update will receive it.
Last updated: Aug 03, 2021