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
  • Advantages of staged rollouts
  • Requirements and limitations for staged rollouts
  • How the staged rollout audience is selected
  • The scope and workflow with staged rollouts
  • Testing performed on staged rollouts
• Staged rollout tasks
  • Start a staged rollout
  • View details of your staged rollout
  • Monitor the progress and performance of your APK
  • Increase the staged rollout percentage
  • Update the app file during a staged rollout
  • Complete the staged rollout
  • Abandon the staged rollout version
• 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 app file. 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 new app file.

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 or 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 app file is included: Metadata from the live app version will continue to be displayed to the staged rollout recipients (for example, the description, images and multimedia, availability, pricing, device support options, and more). Users will receive only the APK file in your staged rollout.
• Android app files only: Staged rollouts is limited to Android app files 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,000 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. 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:

Open/Close Text description  

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 Target Your App screen 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 app submission screens as usual. You can not edit the information in the Content rating section of the Target Your App screen. However, during the staged rollout, users receive only the APK, not any other metadata updates.

For example, suppose you create a staged rollout and edit the Appstore Details screen to explain a new feature in the release. Users who are included in the staged rollout won't see the updated description. They receive only your updated APK file because only the app file is included in the staged rollout. However, updating the metadata for your staged rollout allows you to publish your app immediately when you finish the 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. At the top of the Upcoming Version submission screens, a staged rollout banner indicates the percentage of users selected and displays the date and time when your app will go live.

After your staged rollout is live, you can increment the percentage as desired (ramping up from 1% to a maximum of 50%). 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, the metadata fields become inactive and can't be updated.

When you increase the rollout percentage, you can't make changes, not even to your app's binary file. Once a staged rollout is underway, you can only increase the rollout percentage for the app file 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 (including replacing the app file), 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:

Open/Close Text description  

After you halt the staged rollout, select Staged rollout > Edit staged rollout. Then fields on the submission screens become editable.

Now, you can update your app's binary file (perhaps replacing it with a file that fixes some issue you detected). When you're ready to resume the staged rollout, click Staged rollout > 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. For details, see Start a staged rollout.
• If you halt, edit, and resubmit a staged rollout: If you halt and edit a staged rollout, and then republish your app's binary file to resume the staged rollout, the Appstore will also test and approve your app file. For details, see Update the app file during a staged rollout.

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. In the Upcoming Version section, the Review & Submit screen has a Staged rollout button. To start a staged rollout:

1. Sign in to the Developer Console.
2. From the Dashboard (the default homepage), under the Amazon Appstore section, click App List.
3. Select the app you want to update. You can use staged rollouts only with existing, live apps.

4. On the sidebar, click Add Upcoming Version. A confirmation message appears — click Confirm to proceed.

   Green check marks in the sidebar indicate that the required fields have been pre-filled with the information associated with your live app. The Upload Your App File screen doesn't have a green check mark because the Release notes field must be completed. When you add release notes and the information is saved, the screen will also have a green check mark.

5. Update the information on all of the submission screens to correspond with your new release.

   Update the Release notes field on the Upload Your App File screen. Make other updates as needed for your new APK. For example, you might want to update image assets to correspond with your new release.

   You cannot make updates to the Content rating section on the Target Your App screen for a staged rollout.

   Understanding which updates are included in a staged rollout
   
   Any updates you make to metadata aren't included in the staged rollout. Metadata refers to all submission information other than the app file. For example, updates to the description of image assets 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 app's binary file is pushed out during the staged rollout.
   
   Even though updates to metadata aren'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 screens, see the following:

   • Step 1: Upload Your App File
   • Step 2: Target Your App
   • Step 3: Add Appstore Details
   • Step 4: Review and Submit

6. On the Upload Your App File screen, replace your existing app file with a new version. For more details on how to upload your app file, see Step 1: Upload Your App File.

   Note: Rather than deleting your app's existing binary file, replace it instead. Replacing your app file retains the same device support selections. In contrast, if you delete your app file, you will need to reconfigure the same device support selections as before.
   Important: Be sure to give your app's binary file a higher android:versionCode value than your live app. Users receive the updated APK only if the versionCode value is higher than the current APK they have installed. Also, make sure your package name stays the same as your previous app file. The Developer Console automatically rejects app files that don't meet these versionCode and package requirements.
7. On the Review & Submit screen, click Staged rollout.

8. 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. You cannot lower the percentage — you can only increase it.

9. Click Publish.

   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.

   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:

1. Log into the Developer Console at https://developer.amazon.com.
2. Go to Apps & Services > My Apps.
3. Find your app and select it.
4. On the sidebar, select Upcoming Version | 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:

1. Go your staged rollout version in the Developer Console (see View details of your staged rollout).
2. Click the Staged rollout button, and then select Increase staged rollout %.

3. 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 (including on the Upload Your App File screen where you upload your app's binary file) as you increase the percentage. If you want to update your app file, see the steps in the next section, Update the app file during a staged rollout.

Update the app file during a staged rollout

To update your app's binary file during a staged rollout:

1. Go your staged rollout version in the Developer Console (see View details of your staged rollout).
2. Click the Staged rollout button, and then select Halt staged rollout.

3. 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).

4. From the same Staged rollout drop-down menu, select Edit staged rollout. Now you can edit the information on the submission screens.

5. Go to the Upload Your App File screen and replace your existing app file with a new one.

   Important: When you update your app's binary file, choose to replace the existing file rather than deleting your existing one. If you do delete your app file, select the same device support options as your live app. 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 app file an incremented versionCode in your app's Gradle build file. The value of android:versionCode in your app's manifest must be greater than both the previous staged rollout and live version.

   When you upload a new version of your app's binary file, the release ID will change. The release ID is only relevant if you're managing your app file through the Developer Publishing API (which is now deprecated). Users won't see the release ID.

6. Complete the fields on the Upload Your App File screen.

7. Click Staged rollout > Resume staged rollout.

   

   When you republish your app's binary file, your new app file needs to go through the submission process for testing and approval again. A date and time for the approval appear at the top of the screen. When the new version becomes available, users who already received a staged rollout version of your APK 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:

1. 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.

2. In the Submit 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." After 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 app's binary file with your original app file (but with a higher versionCode) and submit the new version to all your users. Follow these specific steps:

1. Go your staged rollout version in the Developer Console (see View details of your staged rollout).
2. Click Staged rollout > Halt staged rollout.
3. In the Halt staged rollout dialog box, click Halt.
4. Select Staged rollout > Edit staged rollout.

5. On the Upload Your App File screen, replace the staged rollout app file with your original app file. Make sure the versionCode is higher than the versionCode in the previous staged rollout app file.

   Important: Users will only get an updated APK if the versionCode of the new APK is higher than the versionCode of the APK they have installed.

   Although you could resubmit the app file to resume the staged rollout with a new file, in this scenario, we will abandon the staged rollout workflow and publish the app to all users directly.

6. 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.

7. In the Submit 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 I can't edit my app's information. 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 mobile Android 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?

This is 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 Review & Submit screen. 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 fields 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 the information (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 Review & Submit screen 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 app. If you select a new geolocation, no users in that location will receive the update because your live app 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 staged rollout version.

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 app file. 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 app file?

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 app 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 app. 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 app's staged rollout binary file, I selected a device that my live app 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 app 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 app 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, 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 your app's binary file without creating a new version of your app. In your live app, you're unable to edit fields that would require a new version of your app. 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 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: Nov 05, 2024