Multiple APK support is a feature on Google Play that allows you to publish different APKs
for your application that are each targeted to different device configurations. Each APK is a
complete and independent version of your application, but they share the same application listing on
Google Play and must share the same package name and be signed with the same release key. This
feature is useful for cases in which your application cannot reach all desired devices with a single
APK.
Android-powered devices may differ in several ways and it's important
to the success of your application that you make it available to as many devices as possible.
Android applications usually run on most compatible devices with a single APK, by supplying
alternative resources for different configurations (for example, different layouts for different
screen sizes) and the Android system selects the appropriate resources for the device at runtime. In
a few cases, however, a single APK is unable to support all device configurations, because
alternative resources make the APK file too big (greater than 50MB) or other technical challenges
prevent a single APK from working on all devices.
Although
we encourage you to develop and publish a single APK that supports as
many device configurations as possible, doing so is sometimes not possible. To help
you publish your application for as many devices as possible, Google Play allows you to
publish multiple APKs under the same application listing. Google Play then supplies each APK to
the appropriate devices based on configuration support you've declared in the manifest file of each
APK.
By publishing your application with multiple APKs, you can:
- Support different OpenGL texture compression formats with each APK.
- Support different screen sizes and densities with each APK.
- Support different platform versions with each APK.
- Support different CPU architectures with each APK (such as for ARM, x86, and MIPS, when your
app uses the Android NDK).
Currently, these are the only device characteristics that Google Play supports for publishing
multiple APKs as the same application.
Note: You should generally use multiple APKs to support
different device configurations
only when your APK is too large (greater than
50MB) due to the alternative resources needed for different device configurations.
Using a single APK to support different configurations is always the best practice,
because it makes the path for application updates simple and clear for users (and also makes
your life simpler by avoiding development and publishing complexity). Read the section below about
Using a Single APK Instead to
consider your options before publishing multiple APKs.
Publishing Concepts
Before you start publishing multiple APKs on Google Play, you must understand a few
concepts regarding how the Google Play publisher site works.
Active APKs
Before you can publish your application (whether publishing one or multiple APKs), you
must "activate" your APK(s) from the
APK files tab. When you activate an APK, it
moves into the list of
Active APKs. This list allows you to preview which APK(s)
you're about to publish.
If there are no errors, any "active" APK will be published to
Google Play when you click the
Publish button (if the application is
unpublished) or when you click the
Save button (if the application is
already published).
Simple mode and advanced mode
The Google Play publisher site provides two modes for managing the APKs associated with
your application:
simple mode and
advanced mode. You can switch between these by
clicking the
link at the top-right corner of the
APK files tab.
Simple mode is the traditional way to publish an application, using one APK at a time. In
simple mode, only one APK can be activated at a time. If you upload a new APK to update
the application, clicking "Activate" on the new APK deactivates the currently
active APK (you must then click
Save to publish the new APK).
Advanced mode allows you to activate and publish multiple APKs that are each designed for a
specific set of device configurations. However, there are several rules based on the manifest
declarations in each APK that determine whether you're allowed to activate each APK along with
others. When you activate an APK and it violates one of the rules, you will receive an error or
warning message. If it's an error, you cannot publish until you resolve the problem; if it's a
warning, you can publish the activated APKs, but there might be unintended consequences as to
whether your application is available for different devices. These rules are discussed more
below.
How Multiple APKs Work
The concept for using multiple APKs on Google Play is that you have just one entry in
Google Play for your application, but different devices might download a different APK. This
means that:
- You maintain only one set of product details (app description, icons, screenshots, etc.).
This also means you cannot charge a different price for different APKs.
- All users see only one version of your application on Google Play, so they are not
confused by different versions you may have published that are "for tablets" or
"for phones."
- All user reviews are applied to the same application listing, even though users on different
devices may have different APKs.
- If you publish different APKs for different versions of Android (for different API levels),
then when a user's device receives a system update that qualifies them for a different APK you've
published, Google Play updates the user's application to the APK designed for the higher version
of Android. Any system data associated with the application is retained (the same as with normal
application updates when using a single APK).
To publish multiple APKs for the same application, you must enable
Advanced mode
in your application's
APK files tab (as discussed in the previous section). Once
in advanced mode, you can upload, activate, then publish multiple APKs for the same application. The
following sections describe more about how it works.
Supported filters
Which devices receive each APK is determined by
Google Play filters that are specified by
elements in the manifest file of each APK. However, Google Play allows you to publish multiple
APKs only when each APK uses filters to support a variation of the following
device characteristics:
- OpenGL texture compression formats
This is based on your manifest file's
<supports-gl-texture> element(s).
For example, when developing a game that uses OpenGL ES, you can provide one APK for
devices that support ATI texture compression and a separate APK for devices
that support PowerVR compression (among many others).
- Screen size (and, optionally, screen density)
This is based on your manifest file's
<supports-screens> or <compatible-screens> element. You should never use both elements and you should use only
<supports-screens> when possible.
For example, you can provide one APK that supports small and normal size screens and another
APK that supports large and xlarge screens.
Note: The Android system provides strong support for
applications to support all screen configurations with a single APK. You should avoid creating
multiple APKs to support different screens unless absolutely necessary and instead follow the guide
to
Supporting Multiple
Screens so that your application is flexible and can adapt to all screen configurations
with a single APK.
Caution: By default, all screen size attributes in the
<supports-screens> element are "true" if you do not declare them otherwise. However,
because the
android:xlargeScreens attribute was added in Android 2.3 (API level
9), Google Play will assume that it is "false" if your application does not set either
android:minSdkVersion or
android:targetSdkVersion to "9" or higher.
Caution: You should not combine both
<supports-screens> and
<compatible-screens> elements in your manifest file. Using both increases the chances
that you'll introduce an error due to conflicts between them. For help deciding which to use, read
Distributing to Specific Screens.
If you can't avoid using both, be aware that for any conflicts in agreement between a given size,
"false" will win.
- API level
This is based on your manifest file's
<uses-sdk> element.
You
can use both the android:minSdkVersion and android:maxSdkVersion
attributes to specify support for different API levels.
For example, you can publish your application with one APK that supports API levels 4 - 7
(Android 1.6 - 2.1)—using only APIs available since API level 4 or lower—and another
APK that supports API levels 8 and above (Android 2.2+)—using APIs available since API level 8
or lower.
Note:
- If you use this characteristic as the factor to distinguish multiple APKs, then the APK
with a higher
android:minSdkVersion value must have a higher android:versionCode
value. This is also true if two APKs overlap their device support based on a different supported
filter. This ensures that when a device receives a system update, Google Play can offer the user
an update for your application (because updates are based on an increase in the app version code).
This requirement is described further in the section below about Rules for
multiple APKs.
- You should avoid using
android:maxSdkVersion in general, because as long as you've properly developed your
application with public APIs, it is always compatible with future versions of Android. If you want
to publish a different APK for higher API levels, you still do not need to specify the
maximum version, because if the android:minSdkVersion is "4" in one APK and "8" in another, devices that
support API level 8 or higher will always receive the second APK (because it's version code is
higher, as per the previous note).
- CPU architecture (ABI)
This is based on the native libraries included in each APK (which are
determined by the architectures you declare in the
Application.mk
file) when using the Android NDK.
Other manifest elements that enable
Google Play filters—but are not
listed above—are still applied for each APK as usual. However, Google Play does not allow
you to publish separate APKs based on variations of those device characteristics. Thus, you cannot
publish multiple APKs if the above listed filters are the same for each APK (but the APKs differ
based on other characteristics in the manifest or APK). For
example, you cannot provide different APKs that differ purely on the
<uses-configuration> characteristics.
Rules for multiple APKs
Before you enable advanced mode to publish multiple APKs for your application, you need to
understand the following rules that define how publishing multiple APKs works:
Failure to abide by the above rules results in an error on the Google Play publisher site
when you activate your APKs—you will be unable to publish your application until you
resolve the error.
There are other conflicts that might occur when you activate your APKs, but which will result
in warnings rather than errors. Warnings can be caused by the following:
- When you modify an APK to "shrink" the support for a device's characteristics and no other
APKs support the devices that then fall outside the supported range. For example, if an APK
currently supports small and normal size screens and you change it to support only small screens,
then you have shrunk the pool of supported devices and some devices will no longer see your
application on Google Play. You can resolve this by adding another APK that supports normal size
screens so that all previously-supported devices are still supported.
- When there are "overlaps" between two or more APKs. For example, if an APK supports screen
sizes small, normal, and large, while another APK supports sizes large and xlarge, there is an
overlap, because both APKs support large screens. If you do not resolve this, then devices that
qualify for both APKs (large screen devices in the example) will receive whichever APK has the
highest version code
Note: If you're creating separate APKs for different CPU
architectures, be aware that an APK for ARMv5TE will overlap with an APK for ARMv7. That is,
an APK designed for ARMv5TE is compatible with an ARMv7 device,
but the reverse is not true (an APK with only the ARMv7 libraries is
not compatible with an ARMv5TE device).
When such conflicts occur, you will see a warning message, but you can still publish your
application.
Creating Multiple APKs
Once you decide to publish multiple APKs, you probably need to create separate
Android projects for each APK you intend to publish so that you can appropriately develop them
separately. You can do this by simply duplicating your existing project and give it a new name.
(Alternatively, you might use a build system that can output different resources—such
as textures—based on the build configuration.)
Tip: One way to avoid duplicating large portions of your
application code is to use a
library project. A library
project holds shared code and resources, which you can include in your actual application
projects.
When creating multiple projects for the same application, it's a good practice to identify each
one with a name that indicates the device restrictions to be placed on the APK, so you can
easily identify them. For example, "HelloWorld_8" might be a good name for an
application designed for API level 8 and above.
Note: All APKs you publish for the same application
must have the same package name and be signed with the same certificate key. Be
sure you also understand each of the
Rules for multiple APKs.
Assigning version codes
Each APK for the same application
must have a unique version code, specified by
the
android:versionCode attribute. You must be careful about assigning version codes when
publishing multiple APKs, because they must each be different, but in some
cases, must or should be defined in a specific order, based on the configurations that each APK
supports.
Ordering version codes
An APK that requires a higher API level must usually have a higher version code. For example, if
you create two APKs to support different API levels, the APK for the higher API levels must have the
higher version code. This ensures that if a device receives a system update that then qualifies it
to install the APK for higher API levels, the user receives a notification to update the app. For
more information about how this requirement applies, see the section above about
Rules for multiple APKs.
You should also consider how the order of version codes might affect which APK your users
receive either due to overlap between coverage of different APKs or future changes you might make to
your APKs.
For example, if you have different APKs based on screen size, such as one for small - normal and
one for large - xlarge, but foresee a time when you will change the APKs to be one for small and one
for normal - xlarge, then you should make the version code for the large - xlarge APK be higher.
That way, a normal size device will receive the appropriate update when you make the change, because
the version code increases from the existing APK to the new APK that now supports the device.
Also, when creating multiple APKs that differ based on support for different OpenGL texture
compression formats, be aware that many devices support multiple formats. Because a device
receives the APK with the highest version code when there is an overlap in coverage between two
APKs, you should order the version codes among your APKs so that the APK with the
preferred compression format has the highest version code. For example, you might want to perform
separate builds for your app using PVRTC, ATITC, and ETC1 compression formats. If you prefer these
formats in this exact order, then the APK that uses PVRTC should have the highest version code, the
APK that uses ATITC has a lower version code, and the version with ETC1 has the lowest. Thus, if a
device supports both PVRTC and ETC1, it receives the APK with PVRTC, because it has the highest
version code.
Using a version code scheme
In order to allow different APKs to update their version codes independent of others (for
example, when you fix a bug in only one APK, so don't need to update all APKs), you should use a
scheme for your version codes that
provides sufficient room between each APK so that you can increase the code in one without requiring
an increase in others. You should also include your actual version name in the code (that is, the
user visible version assigned to
android:versionName),
so that it's easy for you to associate the version code and version name.
Note: When you increase the version code for an APK, Google
Play will prompt users of the previous version to update the application. Thus, to avoid
unnecessary updates, you should not increase the version code for APKs that do not actually
include changes.
We suggest using a version code with at least 7 digits: integers that represent
the supported configurations are in the higher order bits, and the version name (from
android:versionName) is in the lower order bits. For example, when the application version
name is 3.1.0, version codes for an API level 4
APK and an API level 11 APK would be something like 0400310 and 1100310, respectively. The first
two digits are reserved for the API Level (4 and 11, respectively), the middle two digits are for
either screen sizes or GL texture formats (not used in these examples), and the last three digits
are for the application's version name (3.1.0). Figure 1 shows two examples that split based on both
the platform version (API Level) and screen size.
Figure 1. A suggested scheme for your version codes,
using the first two digits for the API Level, the second and third digits for the minimum and
maximum screen size (1 - 4 indicating each of the four sizes) or to denote the texture formats
and the last three digits for the app version.
This scheme for version codes is just a suggestion for how you should establish a
pattern that is scalable as your application evolves. In particular, this scheme doesn't
demonstrate a solution for identifying different texture compression formats. One option might be
to define your own table that specifies a different integer to each of the different
compression formats your application supports (for example, 1 might correspond to ETC1 and 2 is
ATITC, and so on).
You can use any scheme you want, but you should carefully consider how future versions of your
application will need to increase their version codes and how devices can receive updates when
either the device configuration changes (for example, due to a system update) or when you modify the
configuration support for one or several of the APKs.
Using a Single APK Instead
Creating multiple APKs for your application is not the normal procedure for
publishing an application on Google Play. In most cases, you should be able to publish your
application to most users with a single APK and we encourage that you do so. When you encounter
a situation in which using a single APK becomes difficult, you should carefully consider all your
options before deciding to publish multiple APKs.
First of all, there are a few key benefits to developing a single APK that supports all
devices:
- Publishing and managing your application is easier.
With only one APK to worry about at any given time, you're less likely to become confused by
which APK is what. You also don't have to keep track of multiple version codes for each
APK—by using only one APK, you can simply increase the version code with each release and
be done.
- You need to manage only a single code base.
Although you can use a library project
to share code between multiple Android projects, it's still likely that you'll reproduce some code
across each project and this could become difficult to manage, especially when resolving
bugs.
- Your application can adapt to device configuration changes.
By creating a single APK that contains all the resources for each device configuration, your
application can adapt to configuration changes that occur at runtime. For example, if the user docks
or otherwise connects a handset device to a larger screen, there's a chance that this will invoke a
system configuration change to support the larger screen. If you include all resources for different
screen configurations in the same APK, then your application will load alternative resources and
optimize the user experience for the new interface.
- App restore across devices just works.
If a user has enabled data backup on his or her current device and then buys a new device
that has a different configuration, then when the user's apps are automatically restored during
setup, the user receives your application and it runs using the resources optimized for that device.
For example, on a new tablet, the user receives your application and it runs with your
tablet-optimized resources. This restore
process does not work across different APKs, because each APK can potentially have different
permissions that the user has not agreed to, so Google Play may not restore the application at
all. (If you use multiple APKs, the user receives either the exact same APK if it's compatible or
nothing at all and must manually download your application to get the APK designed for the new
device.)
The following sections describe some of the other options you should use to support multiple
device configurations before deciding to publish multiple APKs.
Supporting multiple GL textures
To support multiple types of GL textures with a single APK, your application should query the GL
texture formats supported on the device and then use the appropriate resources or download
them from a web server. For example, in order to keep the size of your APK small, you can query the
device's support for different GL texture formats when the application starts for the first time and
then download only the textures you need for that device.
For maximum performance and compatibility, your application should use ETC1 textures wherever it
doesn't impact the visual quality. However, because ETC1 cannot deal with images that have drastic
chroma changes, such as line art and (most) text, and doesn't support alpha, it may not the best
format for all textures.
With a single APK, you should try to use ETC1 textures and uncompressed textures whenever
reasonable, and consider the use of PVRTC, ATITC, or DXTC as a last resort when ETC1 does not
suffice.
Here's an example query for supported texture compression formats from inside a
GLSurfaceView.Renderer:
public void onSurfaceChanged(GL10 gl, int w, int h) {
String extensions = gl.glGetString(GL10.GL_EXTENSIONS);
Log.d("ExampleActivity", extensions);
}
This returns a string that lists each of the supported compression formats.
Supporting multiple screens
Unless your APK file exceeds the Google Play size limit of 50MB, supporting multiple screens
should always be done with a single APK. Since Android 1.6, the Android system manages most of the
work required for your application to run successfully on a variety of screen sizes and
densities.
To further optimize your application for different screen sizes and densities, you should provide
alternative
resources such as bitmap drawables at different resolutions and different layout designs for
different screen sizes.
For more information about how to support multiple screens with a single APK, read
Supporting Multiple Screens.
Additionally, you should consider using a support library from the
Compatibility Package so that you can add
Fragments to your activity designs
when running on larger screens such as tablets.
Supporting multiple API levels
If you want to support as many versions of the Android platform as possible, you should use
only APIs available in the lowest reasonable version. For example, your application may not require
APIs newer than Android 2.1 (API Level 7), which makes an application available to
over 95% of Android-powered devices (as indicated by the
Platform Versions dashboard).
By using a support library from the
Compatibility Package, you can also use APIs
from some of the latest versions (such as Android 3.0) while
still supporting versions as low as Android 1.6. The support library includes APIs for
Fragments,
Loaders, and more. Using the fragment
APIs is particularly valuable so that you can optimize your user interface for large devices such as
tablets.
Alternatively, if you want to use some APIs that are available only in newer versions of Android
(which your application can still function without), then you should consider using reflection. By
using reflection, you can check whether the current device supports certain APIs. If the APIs are
not available, your application can gracefully disable and hide the feature.
Another way to use new APIs only when running on a version that supports them is to check the
API level of the current device. That is, you can query the value of
SDK_INT and create different code paths depending on the API level
supported by the device. For example:
if (android.os.Build.VERSION.SDK_INT >= 11) {
// Use APIs supported by API level 11 (Android 3.0) and up
} else {
// Do something different to support older versions
}
Supporting multiple CPU architectures
When using the Android NDK, you can create a single APK that supports multiple CPU architectures
by declaring each of the desired architectures with the
APP_ABI variable in the
Application.mk file.
For example, here's an
Application.mk file that declares support for three
different CPU architectures:
APP_ABI := armeabi armeabi-v7a mips
APP_PLATFORM := android-9
.png)
.png)
.png)
.png)
