The Android App Bundle is a new upload format that includes all your app’s compiled code and resources, but defers APK generation and signing to Google Play. And, after you upload your app bundle to Google Play, Dynamic Delivery uses the app bundle to generate and serve smaller, more optimized APKs for each device configuration your app supports. That way, users download only the code and resources they need to run your app.
This guide describes the Android App Bundle format, and shows you how to build an app bundle for upload or testing. If you haven’t already done so, make sure you configure your app project to support Dynamic Delivery.
The easiest way to build an app bundle to a connected device is using Android Studio. So, make sure to download the latest Canary version of Android Studio.
The Android App Bundle format
An Android App Bundle is a file (with the
.aab file extension) that you
upload to Google Play to support its new app serving model, called Dynamic
Delivery. Each bundle includes the compiled code and resources for all of your
app’s modules and supported device configurations.
To put it simply, app bundles are signed ZIP files that organize your app’s code and resources into modules, as illustrated in figure 1, from which Google Play generates the various APKs that are served to users: such as the base APK, dynamic feature APK(s), configuration APKs, and (for devices that do not support split APKs) multi-APKs. The directories that are colored in blue represent code and resources that Google Play uses to create configuration APKs for each module.
Code and resources for each module are organized similarly to what you would find in an APK—and that makes sense because each of these modules may be generated as separate APKs. The following list describes some of the app bundle’s files and directories in more detail:
- base/, feature1/, and feature2/: Each of these directories at the
root of the app bundle represent a different module of your app. The
base module for your app is always contained in a
basedirectory of the app bundle. However, the directory for each dynamic feature module is given the name specified by the
splitattribute in the module’s manifest. To learn more, read about the Dynamic feature module manifest.
- Protocol Buffer (
*.pb) files: These files provide metadata that helps describe the contents of the app bundle to app stores, such as Google Play. For example,
BundleConfig.pb(located at the root of the app bundle) provides information about the bundle itself, such as which version of the build tools were used to build the app bundle. Other
*.pbfiles, such as
native.pb, describe how certain code and resources should be used to target different device configurations. Google Play uses this information to build APKs that are optimized for each user’s device.
- manifest/: Unlike APKs, app bundles store the
AndroidManifest.xmlfile of each module in this separate directory.
- dex/: Unlike APKs, app bundles store the DEX files for each module in this separate directory.
root/: This directory stores files that are later relocated to the root of any APK that includes the module that this directory is located in. For example, the
base/root/directory of an app bundle may include Java resources that your app loads using
Class.getResource(). Those files are later relocated to the root directory of your app’s base APK and every multi-APK that Google Play generates. Paths within this directory are also preserved. That is, directories (and their subdirectories) are also relocated to the root of the APK.
res/, lib/, and assets/: These directories are identical to those in a typical APK. When you upload your app bundle, Google Play inspects these directories and packages only the files that satisfy the target device configuration, while preserving file paths.
Now that you understand the format of a simple app bundle, and how it represents an Android app project, you should build one from your app project. The easiest way to do so is by using Android Studio.
Deploy your app from an app bundle
When using an existing or default run/debug configuration, Android Studio doesn’t use bundles to deploy your app—it builds and deploys a APKs that are targeted to your connected device. That’s because deploying from an app bundle has the following limitations you should consider:
- Instant Run does not work when deploying from an app bundle.
- The Android Studio build system must build an app bundle before using it to build APKs that it deploys to your app—this extends the total build time when deploying your app.
If you still want Android Studio to build and deploy your app from an app bundle, you can modify an existing run/debug configuration to do so as follows:
- Select Run > Edit Configurations from the menu bar.
- In the left pane of the Run/Debug Configurations dialog, select your desired configuration under the Android App node.
- In the dropdown menu next to Deploy, select APK from app bundle.
- Under Dynamic features to deploy, check the box next to each dynamic feature module you want to include when deploying your app.
- Click OK.
Using the run/debug configuration you just modified, deploy your app by selecting Run > Run from the menu bar (or by clicking Run in the toolbar). As an intermediate build step, Android Studio first converts your app project into an app bundle that includes all your app’s compiled code and resources. From that app bundle, the IDE then generates only the APKs that are required to deploy your app to the connected device.
Build an app bundle using Android Studio
Generating an Android App Bundle using Android Studio is very similar to
generating an APK. If you already have your app project open in the IDE and
you want to simply test building an app bundle, select Build > Build
Bundle(s)/APK(s) > Build Bundle(s) from the menu bar. The IDE generates an
app bundle for
your selected build variant
and places it in the
If you build an app bundle for a debug version of your app, Android Studio
automatically signs your app bundle with a debug signing key, and you can
bundletool to deploy your app from the app bundle
to a connected device. If you don’t select a version of your app that’s signed
with a debug signing key, Android Studio builds an unsigned app bundle. To
upload your app to the Play Console, you need to first
generate a signed app bundle.
After Android Studio finishes building your signed app bundle, you can either locate or analyze it by clicking on the appropriate option in the pop-up notification. Analyzing your bundle allows you to inspect the contents of the app bundle and works similarly to the APK Analyzer.
To generate an app bundle from your app project, the IDE’s build system uses
the same open-source tool, called
bundletool, that Google Play uses to later
convert your app bundle into signed APKs. To learn more about
read about how to
Test Android App Bundles with bundletool.
Build a signed app bundle for upload
Before you can upload your app bundle to the Play console you need to generate a signed app bundle. To generate a signed app bundle, proceed as follows:
- Select Build > Generate Signed Bundle/APK from the menu bar.
- In the Generate Signed Bundle or APK dialog, select Android App Bundle and click Next.
- In the Module dropdown menu, select the base module of the app you want to generate an app bundle for.
- Provide information for an existing key and keystore, or create a new one. This is the same type of key and keystore information you provide when building a signed APK.
- If you want Android Studio to also save your signing key as an encrypted file, check the box next to Export encrypted key. To be able to upload your app bundle and take advantage of Dynamic Delivery, you need to upload this encrypted file to the Play Console and enroll in app signing by Google Play.
- Click Next.
- Provide a Destination Folder for your app bundle, and select the Build Type and Flavors that you want to generate app bundles for.
- Click Finish.
After Android Studio finishes building your signed app bundle, you can either locate or analyze the app bundle by clicking on the appropriate option in the pop-up notification. If you selected the option to export your signing key, you can quickly navigate to it by clicking the dropdown arrow in the bottom right corner of the popup to expand it and clicking Show Exported Key File, as shown in figure 2.
Build an app bundle from the command line
If you’d rather generate an app bundle from the command line, run the
bundleVariant Gradle task on your app’s base module.
For example, the following command builds an app bundle for the debug version
of the base module:
If you want to build a signed bundle for upload to the Play Console, you need
to first configure the base module’s
build.gradle file with your app’s
signing information, similar to how you would when building a signed APK from
the command line. To learn more, read
Configure Gradle to sign your APK.
You can then, for example, build the release version of your app, and Gradle
automatically generates an app bundle and signs it with the signing
information you provide in the
If you instead want to sign an app bundle as a separate step, you can use
to sign your app bundle from the command line.
Upload your app bundle to the Play Console
After you build your Android App Bundle, you can upload your app bundle to the Play Console to inspect, test, and publish your app. Before you get started, be aware of the following prerequisites:
- Before you upload your app bundle, you must enroll into app signing by Google Play.
- If your app includes dynamic feature modules, you can upload and test your app through the Play Console's internal test track. However, to publish your app to production, you must apply for the Dynamic Features Beta Program. To learn more, go to the Play Console help topic about the Beta program for publishing apps with dynamic feature modules.
- Note that Google Play supports only app downloads of 100MB or less. So, for example, when first installing your app, the total size of your base APK and its configuration APKs must equal 100 MB or less. The same applies to downloading dynamic features, where the total size of any dynamic feature APK and its configuration APKs must be 100 MB or less. After uploading your app bundle, the Play Console warns you if your app bundle results in APKs that violate this restriction.
Inspect APKs using bundle explorer
When you upload your app bundle, the Play Console automatically generates split APKs and multi-APKs for all device configurations your app supports. In the Play Console, you can use the App Bundle Explorer to see all APK artifacts that Google Play generates; inspect data such as supported devices and APK size savings; and download generated APKs to deploy and test locally.
To learn more, read the Play Console help topic about Reviewing your app bundle details.
Test Dynamic Delivery using the internal test track
The easiest and fastest way to test your app after you upload your app bundle is by using Play Console’s new internal test track. This new test track is aimed towards quickly sharing your app via Dynamic Delivery to a limited amount of internal testers. And, because the only way to test downloading installing dynamic feature modules on demand is through Google Play, the internal test track is where you’ll want to upload your app bundle to fine-tune this type of user experience.
To learn more, read Set up an open, closed, or internal test.
Update your app
After you upload your app to the Play Console, updating your app requires you to increase the version code you include in the base module, and build and upload a new app bundle. Google Play then generates updated APKs with new version codes and serves them to users as needed. For more information, read Manage app updates.