Developer Console
Vielen Dank für deinen Besuch. Diese Seite ist nur in Englisch verfügbar.

Device Filtering and Compatibility

When you submit your APK into 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 APK 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.

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.

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

Device Compatibility Determined by Your APK's Manifest

As with standard Android practices, the attributes in your APK'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 APK'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 portal 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 Supported Filters on the Amazon Appstore.

Support on Non-Amazon Devices

In addition to supporting Amazon devices, the Amazon Appstore supports non-Amazon devices as well. Your manifest and build.gradle file determine the filtering logic and device support on these devices as well.

To install Amazon apps on non-Amazon devices, customers do so through the Amazon Appstore for Android app. Customers might do install your Amazon app on a non-Amazon 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.

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. The first step in creating your app manifest is to specify the proper Android API level in the android:minSdkVersion attribute for the Fire devices you intend to target. For example, to target all 2013 and newer tablets, your manifest should contain an entry like this:

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

As with Android devices, not all Fire devices have the same API level. For example, some Fire TV devices run on Fire OS 7 (based on Android API level 28), others run on Fire OS 6 (based on Android API level 25), and others run on Fire OS 5 (based on API level 22). Fire tablets have even more differences between API levels. See the following for specific API levels for different Fire devices:

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

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 an APK designed for Fire TV devices, you must still manually select which devices your APK is compatible with in the developer console. See Adjust Device Support for your APK for details.

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 check boxes 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 an 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.

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

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 non-Amazon Android 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.

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.