Getting Started with Device Targeting

Device targeting enables you to submit multiple versions of your app using multiple APK files (also called “binaries”) that run on different platforms and devices, and have those versions appear as the same app in the Amazon Appstore. While you can always support different APIs and device capabilities within a single APK, it may be easier for you to build different binaries for different platforms such as for Fire tablets, non-Amazon Android devices, or for the Amazon Fire TV platform.  

Benefits of Device Targeting

Device targeting provides a number of benefits for your app:

  • Better app discoverability: Instead of having multiple apps for a similar title, your reviews, page views, downloads are consolidated. This helps push your app higher in search results and relevancy rankings. 
  • Less customer confusion:  Customers won’t be confused by multiple device-specific versions of your app.
  • Device-specific feature optimization: You can tailor your APK for different platforms and device capabilities including screen size and density, OpenGL compression format, or API version. 

Device targeting is also a better and smoother experience for your customers. The customer only has to buy your app once, and the correct and optimized version is automatically delivered for each device they use.

There are three steps to using device targeting for your app:

  • Build multiple binary APKs for different devices, optimizing each binary for each device or platform.
  • Configure the Android Manifest for each APK to use different version codes.
  • Use the Binary Files(s) tab on the Apps & Games Developer Portal when you submit your app to upload your individual APKs as part of your app submission.

This document describes each of these steps in greater detail. See Submitting Android Apps to the Amazon Appstore for complete documentation on the Amazon Appstore submission process.

How Filters Work in the Amazon Appstore

The Amazon Appstore uses the supported filters described in Supported Filters on the Amazon Appstore to determine whether to show an app or a game to a customer who is browsing or searching for an app.

When determining whether to display an app, the Amazon Appstore checks the hardware and software requirements for the device, as well as carrier, location, and other characteristics. Amazon then compares the device requirements against the restrictions and dependencies expressed by the app manifest and app publishing details. 

If the app is compatible with the device according to the filter rules, the Amazon Appstore displays the app to the customer. If the app is deemed to be incompatible, the app is hidden from search results and category browsing.

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.

Filtering Based on the App Manifest

Most filters are triggered by elements within the AndroidManifest.xml file. The topic Supported Filters on the Amazon Appstore lists the manifest elements that you can use to trigger filtering for the Amazon Appstore. You can use any combination of the available filters your app.

For example, you can set minSdkVersion=4 and smallScreens=false in the app manifest, then the Amazon Appstore prevents the app from being available on any device that does not match both of these requirements. 

All filtering restrictions are associated with your app version and can change between versions. For example, if a customer has installed your app and you publish an update with new filter elements that make the customer’s device incompatible with the update, the customer will not see that an update is available.

Build your APKs and Configure the Android Manifest

To take advantage of device targeting, create and build separate APKs for your app optimized for each device you want to support. Use the same package name for each APK in your app. You can name your APKs anything you choose.  

In your Android manifest (AndroidManifest.xml), make sure that the package, versionName and versionCode attributes for each APK conforms to the values in the following table:

Attribute Description
package Use the same package name across all your APKs, for example com.mycompany.myapp. The package name you use for the Amazon Appstore must be different from the package you use for any other app store such as Google Play.
android:versionName Use a version name for all your APKs. The version name is an alphanumeric string of no more than 50 characters. Periods (.) are allowed, for example, 1.2 or 34.78.A. The version name is displayed to users when they download an APK, but is not used anywhere else. APKs within the same version of an app do not need to share the same version name.
android:versionCode Use a different version code for each APK you build. Version codes are single integers you choose, for example, 1 or 1254. Note that normally versionCode is used to indicate successive versions of an app. Here it is used to distinguish between different targets APKs for the same app. When you release a new version of your app you can increment any of the version codes to indicate new versions. Devices targeted by an APK will only receive an app update if the version code in the update package is higher than the version code in the installed app.

For example, if you were building separate APKs for Fire tablets and for Amazon Fire TV devices, the attributes for your first manifest (for the Fire tablet) might look like this:

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

The manifest for the second APK might look like the following. Note that the only difference is the version code. Your manifest for each app may differ in other ways (different features, different intents, for example) but these are the configurations that are relevant for device targeting.

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

Upload your APKs

Submit your app as usual to the Amazon Appstore through your dashboard on the Apps & Games Developer Portal. You only need one submission for each app, regardless of device. Follow the instructions in Submitting Android Apps to the Amazon Appstore for specific details on how to fill out the various tabs on the submission forms and upload metadata such as icons and screen shots.

Use the Binary Files(s) tab to configure and upload the separate APKs you built in the previous section. For each APK, use these steps:

  1. Select the Binary Files(s) tab on the submission page when it is available (after you have filled out the other tabs).
  2. Drag and drop your app’s binary (APK) file onto the Upload Binary box. You can also click Upload Binary to find and select the APK file to upload on your file system. If your APK is larger than 125MB, you can use SFTP to upload that APK with a name that includes your submission ID. Select SFTP instructions and naming convention to find information about using SFTP.
  3. Choose the devices to which this APK applies. For example, if you have one APK that is targeted to the larger Kindle Fire tablets, you would choose Fire HD 8.9 and Fire HDX 8.9. To target a Amazon Fire TV device, choose Amazon Fire TV or Fire TV Stick. The submission form shows you data extracted from the APK, including the package, version name and version code. Verify that these values are correct for this APK.
  4. Give your APK an alias. This name is used only to distinguish different APKs as part of the submission process. By default, your APKs have the name Binary with a number, for example Binary1, Binary2, and so on.
  5. Fill out the other parts of the form, and click Save. If you have additional APKs to upload, click Save and Add a Binary instead.
  6. Repeat these steps for every other APK you want to upload for your app.

Each binary you upload has its own subtab under Binary Files(s) named for the alias you defined in Step 4. The available device targets for your APK also changes for each binary you upload, based on the values you choose for the other APKs in your submission.

Targeting non-Amazon Android Devices

In addition to device targeting using compatibility settings in the application’s AndroidManifest.xml file, you can use the Device Support options in the Binary File(s) tab to see which devices are compatible with your app, and if your app manifest settings have automatically filtered out any devices as incompatible. If necessary, you can manually filter out additional Android devices that have known compatibility issues, without having to re-submit a new APK file.

To implement device targeting for non-Amazon Android Devices, use these steps:

  1. Select the Binary File(s) tab. If your app has multiple binaries, select the one that will target non-Amazon devices and click the Edit button at the bottom of the screen to navigate to the device support options. If you can’t select the Edit button, click the Create Upcoming Version link under the app title.
  2. Use the Device Support Summary to review the total number of devices that are Supported (compatible), Excluded (manually de-selected) and Unsupported (incompatible based on your manifest settings, or already targeted by a different binary file for the app).
  3. To change your device support settings, click the Edit device support link to open the Device Support dialog.
  4. If you want to limit your app’s availability to only a handful of non-Amazon devices, you can toggle-off the Enable non-Amazon devices control to initially exclude all devices before manually selecting devices for inclusion in to your compatibility list.
  5. Alternatively, at the bottom of the Device Support dialog, there is a setting for All other Android devices. This control is enabled by default. It allows your app to be distributed to any other compatible Android devices not explicitly listed. It also allows your app to be made available for newly released (future) Android devices that are compatible with your manifest.

The device summary drop-down at the top of the screen provides an overview of current device support. Clicking any of the links will filter the UI to show only the devices in the selected category. This is a quick and easy way of reviewing and editing your device support options:

  • All Devices shows every possible device
  • Supported Devices shows those that this binary is targeting
  • Manually Excluded shows devices that have been de-selected
  • Unsupported Devices shows devices that have been automatically excluded from targeting. This includes devices targeted by another binary

Searching for Devices

If you need to find a specific device by model or manufacturer, the search function will highlight devices that match the entered text. Simply start typing, and the dialog lists matching devices. You can choose to exclude or target devices directly from the search results.