Device Filtering and Compatibility

When you submit your APK into the Appstore, the attributes in your app manifest determine what devices your app can be installed on. Incompatibilities between your manifest and a device’s capabilities will prevent the 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 edit the supported devices for your app.

Tip: The information here is more conceptual than procedural. For step-by-step details on uploading your APK, see Step 7: Upload APK Files.

Background Knowledge

Because Amazon's Fire OS is based on Android, Amazon tries to maintain as much parity with Android development 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 differs. For a better understanding of the concepts here, consult these foundational Android documentation topics:

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

Alternate name for APK, currently used in the user interface of the Developer Portal submission console. "Binary targeting" or "device targeting" refers to filtering the devices available for your APK 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 2 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, or other devices where the APK is installed. The list of supported devices shown for your APK include both Amazon and Android devices, because Amazon apps can actually be installed (sideloaded) 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 Appstore.

device targeting

Similar to filtering but refers to actively designing your app for compatibility with a particular device. 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

The package attribute in the manifest 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.

Device Compatibility Determined by Your APK's Manifest

As with standard Android practices, the attributes in your APK's manifest and build.gradle file 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.

Tip: In your manifest, keep in mind that some permissions imply feature requirements. Thus, even if your manifest does not explicitly require the feature, the feature can be implicitly required.

In addition to supporting Amazon devices, the Amazon Appstore can also make your app available to non-Amazon devices, using the same filtering logic. Through the Amazon Appstore for Android app, customers can install your app onto their Android devices. (This might be important if customers 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.)

Amazon 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 a single Android API level. Therefore, 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.

See the Tablet Specifications and Fire TV Specifications for the Android and Amazon API levels for various Amazon Fire devices. For example, to target all 2013 and newer tablets, your manifest should contain an entry like this:

<uses-sdkandroid: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 6, which is based on Android API level 25. Others run on Fire OS 5, based on API level 22. Fire tablets have even more variety of API levels. See the following topics for details about the Fire OS version and features:

Android API levels for devices change over time as Fire OS updates are deployed. For example, 2014 Fire tablets run Fire OS 4.5, at Android API level 19. When these devices are updated to Fire OS 5.0 (through an over-the-air or "OTA" update process), the Android API level will update to 22. If your APK is compatible with both versions of Fire OS (most are), 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 but only when determining if the app should be available on a specific device. It has no effect when the user updates their Fire OS to a later version. 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.

Implied Features

Many developers are tripped up by implied features. Per 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 is deemed not compatible with any device that does not provide those features, even if the app is designed to degrade gracefully when features aren’t present.

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:

If you then provide this APK to the Amazon Appstore, only WAN models of Fire tablets would be compatible, since these are the only Fire devices with GPS capabilities. 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):

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 a ZIP package with web files, during the submission process, the Amazon Appstore takes the web app and generates an Android app using the Corodva engine. In the end, it's 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 Apps & Games Services SDKs.

Upload your APK

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 non-Amazon 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 may 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 only have to buy your app once, and the correct, optimized version will automatically be delivered for each device they use. Increasing a customer’s confidence around the correct app purchasing decision for their devices will enhance your app brand messaging, build customer trust and loyalty, and decrease your catalog fragmentation.

Additionally, reporting, metrics, and reviews are consolidated for the app across all the APKs associated with the app. This consolidation improves the search and relevancy rankings for your 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.

A common reason APKs fail is due to duplicate package names for different apps (not for multiple APKs uploaded for the same application listing). 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.

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:

Note that the only difference is the versionCode and, for some variety, the minSdkVersion. The package name remains the same. The manifest and build.gradle file for each app may differ in other ways (declaring different features or intents, for example), but the package names should remain the same while each versionCode uses 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 in the second.