lightbulb_outline Please take our October 2018 developer survey. Start survey

Add an instant experience to your existing Android App Bundle

This document guides you through the process of adding instant app functionality to an existing Android App Bundle, followed by building and testing the updated app bundle. For guidance on creating the app bundle, see Android App Bundle.

Get the necessary tools

In order to create and test an instant-enabled app bundle, add the following tools to your development environment if you haven't done so already:

  • Google Play Instant Development SDK: Download the latest version of this SDK from the SDK Tools tab within the Android SDK Manager.
  • bundletool command-line program: Download this program from the bundletool project on GitHub.
  • Target device: Use either a physical or virtual device to test the instant app experience.

Request only supported permissions

In order for your app bundle to be instant-compatible, it can only use permissions from the following list:

Edit your app's manifest and build configuration

To configure your app bundle as instant-enabled, make the following changes to your app's build file and manifest.

  1. Navigate to the directory containing your app's manifest file, typically src/main/. Update the manifest file so that you provide users with an entry point into the instant version of your app, either by using a default activity or verifying your intent filters' app links.

  2. In the src directory, add a new subdirectory called instant. This directory contains files for the instant version of your app, which users view through the Google Play Store or a URL.

  3. In this new instant directory, create a new manifest file called AndroidManifest.xml. In this file, declare the module as instant, and set the targetSandboxVersion to 2, which is required for the instant app experience to run:

    instant/AndroidManifest.xml

    <manifest
        xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:dist="http://schemas.android.com/apk/distribution"
        android:targetSandboxVersion="2">
        <dist:module dist:instant="true" />
    </manifest>

    This setting places the instant version of your app in a more secure SELinux sandbox, which allows the instant version of your app to transfer user data to the installed version.

  4. Update your app's Gradle configuration to declare the product flavors that you've added to the project, as shown in the following code snippet.

    When defining the product flavors, make sure that the instant variant has a smaller versionCode value than the one for the installed variant of your app or game. This configuration allows users to upgrade from the instant version of your app or game to the installed version.

    base/build.gradle

    android {
        ...
    
        // All product flavors must belong to a named flavor dimension.
        // If you specify only one dimension, all flavors are assigned
        // to that dimension by default.
        flavorDimensions "experience"
        productFlavors {
            instant {
                versionCode 1
            }
            installed {
                versionCode 2
            }
        }
    }

Build the app bundle

The app bundle now has two release variants: instantRelease and installedRelease.

Build each release variant of the app bundle by selecting Build Bundle(s) / APK(s) > Build Bundle(s) from the menu bar. Then, use the APK Analyzer tool to open the output bundle's base/manifest/AndroidManifest.xml file. Make sure that the instantRelease variant has set android:targetSandboxVersion to 2.

Test the instant experience

Before publishing your app bundle, you can test the instant experience both locally and using the Google Play's internal test track.

Local machine

To test your instant-enabled app bundle's functionality, build the set of split APKs that correspond to your app bundle, and use one of these APKs to launch the instant app experience on a target device. The following steps describe how to complete this process:

  1. Sign your APK, using either Android Studio or the jarsigner command-line program:

    $ jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 \
          -keystore your-keystore-path base.aab \
          your-key-alias

    If you're signing your app from the command line, use the debug signing key.

  2. Open a terminal window and navigate to the output directory for the generated app bundle. This directory varies based on how you've signed your APK.

    If you signed your APK using Android Studio, the app bundle is located in the following directory:

    $ cd app-project-dir/release/installed/release
    

    If you signed your APK from the command line, on the other hand, the app bundle is in this other directory:

    $ cd app-project-dir/base/build/outputs/bundle/instantRelease
    

    These examples assume your app bundle's base module is called base.

  3. Create and extract the set of split APKs for this app bundle:

    $ bundletool build-apks --bundle=base.aab --output=base.apks \
          --connected-device \
          --ks=your-keystore-path \
          --ks-pass=your-keystore-pswd \
          --ks-key-alias=your-key-alias \
          --key-pass=your-key-pswd
    $ unzip base.apks
    

    By building APKs only for devices that are running and connected to ADB, you can run all of the APKs in the next step.

  4. Launch the instant app experience on your target device:

    $ $ANDROID_HOME/extras/google/instantapps/ia --debug run splits/*.apk

Internal test track

When you use the internal test track, the Google Play Console doesn't apply the size limits discussed in the Google Play Instant overview. Therefore, you can test and internally showcase an instant experience, even if it's larger than 10 MB.

After publishing an app or game to the internal test track, you can see the Try Now button on the Play Store and launch your instant experience from a banner on your website. Perform QA tests on this instant experience to ensure that it gracefully manages the sandbox restrictions that instant experiences impose to respect user safety.

Publish the app bundle

To publish the app bundle that contains your instant app, complete the following steps:

  1. If you haven't already, sign your app bundle with a release key.
  2. Navigate to the Google Play Console, then open Release management > Android Instant Apps.
  3. During the release process, upload the app bundle that you've built.

Note: When you publish an app bundle, consider the sizes of the different combinations for base APK, feature APK, base configuration split set (language, screen density, and ABI), and feature configuration split set. If each combination is less than 10 MB in size, Google Play can make instant experiences of your app available to users.

To learn more about the different APKs that Google Play generates from an app bundle, see Dynamic Delivery with split APKs.