Device Filtering and Compatibility

When you submit an Android app to the Amazon Appstore, the attributes in your app manifest and build.gradle files determine what devices your app can be installed on. Incompatibilities between these files and a device's capabilities will prevent your binary file from being supported on that device. The sections that follow explain some of the filters that influence support for devices. You can also manually adjust the list of supported devices in the Developer Console.

Tip: The information here is more conceptual than procedural. For step-by-step details on uploading your binary file, see Step 1: Upload Your App File.

Background knowledge

Because Amazon's Fire OS is based on Android, Amazon tries to maintain as much parity with Android as possible. Because of this, the documentation here doesn't duplicate the information in the Android documentation; instead, it covers how Amazon and Fire OS differ. For a better understanding of the concepts here, consult these foundational Android documentation topics:

Key terms related to device filtering

The following are common terms used with device filtering in app submission.

app: Your app as shown in the Appstore. A single app can have multiple APKs designed for different devices or locales.
APK: Android Package Kit. The file that gets downloaded to a device when a user installs your app from the Appstore.
binary: Can refer to Android App Bundle (AAB) or APK file. "Binary targeting" or "device targeting" refers to filtering the devices available for your binary file based on the manifest.
build.gradle file: A file in the APK where build dependencies are declared. The build.gradle file indicates the minSdkVersion and versionCode, which influence the Appstore's filtering logic that determines device compatibility. Note that there are two build.gradle files in each Android Studio project. One is a project-level configuration file (in the project's root directory); the other is an app-level configuration file (in the folder called app). For device filtering, all manifest-related configuration is in the app-level build.gradle file.
compatibility: The suitability of your APK for the device — based on the API level, features, and other attributes in the manifest and build.gradle file. If your app isn't compatible with a device, the Appstore won't let users install it on their device.
device: The tablets, TV, etc. where the APK is installed. The list of supported devices shown for your APK include both Amazon and Android devices because Amazon apps can be installed on Android devices through the Amazon Appstore for Android app.
device filtering: The process of automatically determining which devices your app can be installed on, based on the features, API levels, and other attributes in the APK manifest and build.gradle file. The features declared in the manifest (and build.gradle file) act as filters that determine which devices your app is compatible with. For details on Amazon's supported filters, see Manifest Filters Supported by the Amazon Appstore.
device targeting: Refers to actively designing your app for compatibility with a particular device (similar to device filtering). When you upload multiple APKs, there is no automatic filtering that determines device support for the additional APKs. You manually select which devices each APK supports. This manual selecting of device support with multiple APKs is sometimes referred to as device targeting.
Gradle: The build system Android uses to gather dependencies and package up the APK.
manifest: A required file in your APK that describes the features and activities in your app. The manifest and build.gradle file are used to determine which devices your app is compatible with.
package name: An attribute (package) in the manifest that provides a unique identifier for your app in the Appstore. The package name for your app must remain the same and cannot change with new releases. Multiple APKs for the same app should use the same package name for each APK. Different application listings, however, should have different package names. The package name must not include amazon in the name.

For a more comprehensive glossary, see the App Submission Glossary.

Device compatibility determined by your app's manifest

As with standard Android practices, the attributes in your app's manifest and build.gradle files determine which devices are compatible with your app. For example:

If you set minSdkVersion=4 and smallScreens=false in the app manifest, the Amazon Appstore prevents the app from being installed on any device that doesn't support those requirements.
If your manifest declares a requirement for a camera feature (<uses-feature android:name="android.hardware.camera" />), any device that does not have a camera won't be compatible. Customers with incompatible devices will not see the app as available to be installed.

Using the filters in your app's manifest, Amazon Appstore checks the hardware and software requirements for the customer's device as well as the carrier, location, and other characteristics. Amazon also looks at the geographic location availability requirements as specified in your app's metadata (which you select when publishing your app). If your app is compatible with the device according to the filter rules, your app is made available to the customer. If the app is incompatible, your app is hidden from search results and category browsing for that customer's device.

The following table shows examples of filters:

Filter Type	Example
Filtering based on device compatibility	If you state in the app manifest that the app requires GPS, the Amazon Appstore does not show the app to devices that do not have a GPS.
Filtering based on app availability	If you state in the Developer Console that your app should only be available in North America, the Amazon Appstore does not show the app to devices outside North America.

For a full list of supported manifest filters, see Manifest Filters Supported by the Amazon Appstore.

Support on Android mobile devices

In addition to supporting Amazon devices, the Amazon Appstore supports Android mobile devices running Android 7.0 and above. Your manifest and build.gradle file also determine the filtering logic and device support on these devices. Android mobile devices below Android 7.0 won't be able to access the Amazon Appstore.

To install Amazon apps on Android mobile devices, customers do so through the Amazon Appstore for Android app. Customers might install your Amazon app on an Android mobile device if they already purchased the app from Amazon Appstore and don't want to buy it again from Google Play, or if they have coins or subscriptions they purchased from Amazon and want to use them in the same app on other devices, such as Android tablets.

Guidance for targetSdkVersion

If your app targets only Android mobile devices, follow the AOSP guidelines to set targetSdkVersion in your app. To reach Android 15 devices through the Amazon Appstore, set targetSdkVersion to 24 or above in your app manifest or build.gradle file. If you don't set targetSdkVersion to at least 24, your app won't be available on the Amazon Appstore for Android 15 devices.

If your app targets Android mobile devices and Fire devices, follow the guidelines for Fire OS devices in Minimum API Levels for targetSdkVersion. To reach a broader range of both Android mobile devices and Fire OS devices, set targetSdkVersion to above 34 and set minSdkVersion to the lowest API level your app can support.

Note: To maintain your app, the Android developer documentation instructs you to set targetSdkVersion to match the latest API level, and thoroughly test your app on that API level.

Fire OS and Android API Levels

Fire devices use Fire OS as the operating system. Since Fire OS is a custom version of Android, each Fire OS version corresponds to an Android API level. In your app manifest, the android:minSdkVersion attribute indicates the minimum API level of the Fire devices you intend to support. Make sure to specify the proper Android API level for your app in the minSdkVersion attribute. For example, to support all 2013 and newer tablets, your manifest should contain an entry like this:

<uses-sdk android:minSdkVersion="17" />

You can also set the android:targetSdkVersion attribute, which has a different function from minSdkVersion. Setting targetSdkVersion ensures that when your app is run on a device that matches the specified API level, it has access to the available enhancements provided in that API level. Since newer API levels introduce enhanced security and performance, Android enforces minimum API levels for targetSdkVersion. To learn more about minimum targetSdkVersion requirements for Android, see the Android documentation.

Important: If you don't set targetSdkVersion, the value defaults to what you set in minSdkVersion. And if you don't set minSdkVersion, it indicates that your app supports all Android API levels.

As with Android devices, not all Fire devices have the same API level. For specific API levels on different Fire devices, see the following:

Minimum API levels for targetSdkVersion

Due to requirements from Android, on April 1, 2022, Amazon began enforcing the following Android API level requirements for targetSdkVersion on Fire OS 6 and 7.

Note: These are minimum API levels for targetSdkVersion not for minSdkVersion. You can still support older devices by setting minSdkVersion to the desired API level.

Fire OS Version	Minimum API Level for targetSdkVersion
Fire OS 6	25
Fire OS 7	28
Fire OS 8	30
AOSP 14	34

You cannot submit new apps or update existing apps that do not meet the minimum API levels for targetSdkVersion on or after April 1, 2022. Any existing apps submitted to the Appstore will continue to work and be available for your customers.

See Fire OS documentation to learn more about setting minimum API levels:

Backwards and forwards compatibility across API levels

Android APIs are usually backwards compatible, meaning a device that supports Android Level 28 will support Levels 1 through 27. However, Android APIs are not forwards compatible, meaning Level 27 will not necessarily support all the functionality introduced in Level 28. As such, some features available in Fire OS 7 might not be supported in Fire OS 6. Some features in Fire OS 6 might not be supported on Fire OS 5, and so on. See the following for special considerations about how to develop for Fire OS 6 and Fire OS 7:

Evolving API levels

Some Android API levels for devices change over time as Fire OS updates are deployed. For example, some versions of Fire tablets were initially released with Fire OS 6, but they were upleveled to Fire OS 7 later on through an over-the-air ("OTA") update process.

If your app's binary file is compatible with multiple versions of Fire OS, in the <uses-sdk> element in your manifest, set your minSdkVersion to the lowest API level your device supports in order to ensure maximum compatibility with devices. If you set the minSdkVersion to 22, devices that support only level 19 and lower won't be compatible.

The Amazon Appstore also supports the android:maxSdkVersion attribute, which specifies the maximum allowed API level on the device. In most cases, use of this attribute is not needed unless there is a breaking incompatibility with a higher API level.

Common hardware and software capabilities

After you specify the minSdkVersion, make sure your <uses-permission> and <uses-features> elements are appropriate for the devices you want your app to be compatible with. Refer to specifications for Fire Tablets and Fire TV for specific hardware and software capabilities.

Be aware of implied (or unstated) feature requirements as well. As noted in the Android <uses-feature> documentation, specifying <uses-permission> for certain capabilities implies one or more <uses-feature> elements, with android:required="true" assumed. Because the implied features are required, the app's binary file will not be compatible with any device that does not provide those features, even if the app is designed to degrade gracefully when features aren’t present.

To better understand implied features, consider this scenario. Your app uses the device’s current location to find nearby gas stations. The app can get your current location from the device's GPS, but if GPS is not available, the user can input an address or location. To use the GPS, you should include this element in your manifest:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

However, if you don’t explicitly define the feature requirements, these elements are implicitly defined:

<uses-feature android:name="android.hardware.location" android:required="true" />
<uses-feature android:name="android.hardware.location.gps" android:required="true" />

If you then provide this binary to the Amazon Appstore, only Fire tablets with built-in GPS capabilities (that is, with WAN, or wireless access networks) would be compatible. To be compatible with additional Fire devices, you should include these elements in your manifest but specify them as not required (provided your app functions correctly without GPS):

<uses-feature android:name="android.hardware.location" android:required="false" />
<uses-feature android:name="android.hardware.location.gps" android:required="false" />

For a full list of permissions that cause implied features, see Permissions that Imply Feature Requests.

Devices supporting only 64-bit apps

Some devices no longer support 32-bit apps, including any 32-bit apps currently available on Amazon Appstore. Customers attempting to download a 32-bit app on one of these devices will receive a notification alerting them that the app is not compatible with system requirements.

To make your app available to customers using one of these devices, add 64-bit (arm64-v8a) support to your app and submit an update using the Amazon Developer Console. Do not remove support for 32-bit (armeabi-v7a) while building your app, as it may impact current Amazon device selection.

Device filtering for Fire TV devices

For Fire TV devices, the following manifest attribute identifies support for Fire TV:

<uses-feature android:name="android.hardware.touchscreen" android:required="false" />

This attribute indicates that the touchscreen feature is false. Fire TV devices do not support touchscreens and multi-touch capabilities, whereas phones and tablets do. As a result, you must declare this android.hardware.touchscreen attribute to be false for the Appstore to classify your app as compatible with Fire TV devices.

However, this classification isn't automatic. When you upload a binary designed for Fire TV devices, you must still manually select which devices your binary file is compatible with in the Developer Console. For details, see Supported devices.

Device filtering for web apps

Although device filtering based on your Android manifest is not available for web apps, you can still control the supported devices through a list of checkboxes during the submission process. With web apps, even though you submit a URL to a website or upload a zip package with web files, the Amazon Appstore takes the web app and generates an Android app using a Cordova wrapper. This Cordova-packaged app is the Android app that users download and install on their devices.

Web apps are compatible with all devices because in terms of Android APIs, they are very basic — there's one activity with a WebView into which web files or a URL is loaded, and the API level is set to 10 to gain the widest compatibility possible.

Device filtering by web browser apps

For privacy and security reasons, Amazon does not allow third-party browsers on Fire Tablet and Fire TV. Please verify the targeted devices during your app submission process. In isolated instances, we may permit third-party browser apps if they pass our privacy and security bar. Please reach out to us by visiting the Contact Us form, then select the Appstore category and choose the Content Policy Results topic if you want more information.

Device filtering by country

The countries and regions you selected during the app submission process on Step 2: Target Your App, help determine which devices your app can support. Not all Amazon devices are available in all countries. If a Fire TV or Fire tablet isn't available in any of your targeted countries or regions, it will be filtered out as unsupported during the submission process.

Specifying an installation location for your app

Your Android Manifest file specifies the installation location for your app on Fire devices. For most apps, setting this value to External Storage (preferExternal) will provide a better experience for your app's users, as it will reduce scenarios where customers can't install your app because their device's internal storage is full. For more information, see Specifying the Installation Location for Your App.

Remove uses-amzn-sdk from app manifest

If you have the following tag in your app's manifest, <uses-amzn-sdk>, remove it. This tag relates to the old Fire OS SDK add-on and is no longer used for apps on Fire TV.

Although your app will (usually) still work with this tag in your manifest, removing it will avoid any future incompatibilities. None of the components of the old Fire OS SDK add-on are required to develop apps for Fire devices. Instead, use standard Android APIs and the Amazon SDKs.

Multiple APKs for the same application listing

Note: Adding multiple APKs for the same app is supported for Amazon devices only. The Amazon Appstore does not support multiple APKs when targeting Android mobile devices.

Although you can support different devices within a single APK (such as by checking for the permissions at runtime and degrading gracefully if the device doesn't support the feature), it might be easier for you to build multiple APKs for the same application listing. Each APK can accommodate different software or hardware features and components for different devices.

The device differences accommodated by multiple APKs might include the API level, OpenGL compression format, CPU, screen size and density, device features, or even other factors such as geographic locales. For example, you might want an APK for Fire tablets, a separate APK for Fire TV, and another APK for Android mobile devices. For this reason, the Amazon Appstore lets you upload more than one APK for the same app.

No matter how many APKs you upload, the user sees just one app in the Appstore. The APK that gets downloaded depends on the user's device. For example, suppose you have an app called "Stream Sports Everywhere." You want the app to work seamlessly across phones, tablets, and TVs. However, you find it difficult to use a single APK for all of these devices. As such, you decide to create two APKs — one for phones/tablets, and one for TVs.

In the Appstore, the user sees just one "Stream Sports Everywhere" app. When the user installs the app from a TV device, the APK designed for TVs gets installed. When the user installs the app from a phone or tablet, the APK designed for phones and tablets gets installed.

If you charge for your app, the customer won't be prompted to re-purchase the same app on other devices because the user has already purchased the app. Customers have to buy your app just one time, and the correct, optimized version will automatically be delivered for each device they use.

Additionally, reporting, metrics, and reviews are consolidated for the app across all the APKs associated with the app.

Requirements for multiple APKs

When you submit multiple APKs for the same app, be sure to do the following:

1. Give each APK a unique version code.

The versionCode is an internal numbering scheme not displayed to users. (Only the versionName is shown to users.) Version codes are single integers you choose, for example, 1 or 1254. The versionCode (and versionName) are specified in your app's build.gradle file. See Version Your App for details.

The versionCode is used to indicate successive versions of your app. When you have multiple APKs and publish an update, the versionCode also determines whether the device receives the updated APK. Higher versionCode numbers indicate newer versions. Devices compatible with the APK will receive an app update only if the versionCode in the updated APK is higher than the existing device APK's versionCode.

For example, suppose you have one app with two APKs — APK "Ham" with versionCode 10 and APK "Eggs" with versionCode 20. A customer has a device with "Eggs" installed. In an update to your APKs, you decide to remove "Eggs" and use "Ham" exclusively, targeting all devices with it. If you increment Ham's versionCode to 11, customers with Eggs already installed won't receive the update because Eggs has a higher versionCode. Therefore you will need to set your versionCode to 21 or higher before submitting an update.

2. Use the same package name for each APK within the same application listing.

Each APK for the same application listing must use the same package name in the manifest. See package for details.

Every app in the Appstore is identified by its package name. Each app's package name must be unique, and for catalog integration, the package name cannot include the term amazon.

Note: A common reason APKs fail is due to duplicate package names for different apps. Different apps must have different package names. However, when you have multiple APKs for the same app, each APK must use the same package name. Additionally, when you submit new versions of the APKs, the package names must remain the same from one version to the next.

Example of versionCode with multiple APKs

Let's walk through an example of package names and versionCode with multiple APKs. Suppose that for the same app, you're building separate APKs — one APK for Fire tablets and one APK for Amazon Fire TV devices. The attributes for your first APK's manifest might look like this:

APK 1's manifest:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.mycompany.myapp">

</manifest>

APK 1's build.gradle file:

    defaultConfig {
        minSdkVersion 19
        targetSdkVersion 23
        versionCode 13
        versionName "1.0.6"
    }

APK 2's manifest:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.mycompany.myapp">

</manifest>

APK 2's build.gradle file:

    defaultConfig {
        minSdkVersion 22
        targetSdkVersion 23
        versionCode 14
        versionName "1.0.6"
    }

Note that in these code samples, the only difference is the versionCode and, for the sake of variety, the minSdkVersion. The package name remains the same. The manifest and build.gradle file for each app might differ in other ways (declaring different features or intents, for example), but the package names should remain the same. In contrast, each versionCode should use a unique value.

(The Appstore does not perform logic checks to ensure the APKs are sufficiently different from each other.)

How multiple APK support on Amazon differs from Google Play

One way multiple APKs differ on Amazon (versus Google Play), is that with the Amazon Appstore, when you upload multiple APKs, you manually select the supported devices for each APK.

For example, suppose more than one APK is compatible for the same device. The supported devices are not automatically selected based on the same logic that Google Play uses (where the highest supported API level for the device is automatically selected, or where a higher versionCode determines the device support).

Instead, with Amazon's Appstore, after you upload the first APK, you will see the supported devices automatically selected based on the filtering logic. If you want to support different devices with a second APK, you must manually remove the supported devices from the first APK. Then after you upload the second APK, you can select the devices you want to support with the second APK. The Appstore won't let you support the same device with multiple APKs. (The concept is the same as with Google Play — one APK per device — but the selection process for this on Amazon is manual).

When devices are unavailable for the second APK

Note that many developers often experience confusion around this point. They upload the second APK and see all devices as incompatible, or they cannot select any of the devices. The reason is because those devices are already selected for the first APK, so they need to deselect the devices in the first APK to make them available for the second APK.

Tip: The steps for uploading multiple APKs are described in detail in Add multiple APKs for the same app. This section appears in Step 1: Upload Your App File.

Last updated: Oct 17, 2024