Create an instant-enabled app bundle

You create an Google Play Instant experience by including it as part of an Android App Bundle. Such a bundle is known as an instant-enabled app bundle. This document shows you how to set up your development environment for instant-enabled app bundles, as well as how to configure, build, test, and publish an instant-enabled app bundle.

If you have an existing instant app project that uses the deprecated feature plugin (com.android.feature), learn how to migrate your instant app to support Android App Bundles.

Note: In order to publish an app bundle, you must opt into app signing by Google Play.

Set up development environment

To provide an instant experience within an app bundle, you need access to the Google Play Instant Development SDK. You can install the SDK using one of the following methods:

• Install Android Studio 3.3 or higher. After opening Android Studio, download the Google Play Instant Development SDK from the SDK Tools tab in the SDK Manager.

• Install from the command line:

  cd path/to/android/sdk/tools/bin && \
    ./sdkmanager 'extras;google;instantapps'
  

Additionally, if you want to test your instant experience locally, get access to either a physical or virtual device.

Configure your project for instant experiences

To be compatible with Google Play Instant, you must configure several aspects of your instant-enabled app bundle carefully. The following sections describe these considerations.

Instant-enabled app modules

You can declare that your app bundle supports instant experiences using one of the following methods:

• If you're creating a new project in Android Studio, during the Configure your project step, select the This project will support instant apps checkbox.

• If you have an existing app bundle that contains only a base module, you can instant-enable the app bundle by adding the following declaration to the module's manifest:

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

  Note: By default, the base module of an app bundle is called app.

• If you have an existing app bundle that contains multiple modules, you can Create an instant-enabled dynamic feature module. This process also instant-enables your app's base module, giving you the option to support multiple instant entry points within your app.

Note: For an app bundle to be instant-enabled, the combined download size of the code and resources within all instant-enabled modules must be at most 10 MB.

Supported permissions

Instant-enabled app bundles can only use permissions from the following list:

• ACCESS_COARSE_LOCATION
• ACCESS_FINE_LOCATION
• ACCESS_NETWORK_STATE
• BILLING – Deprecated as of Play Billing Library 1.0.
• CAMERA
• INSTANT_APP_FOREGROUND_SERVICE – Only in Android 8.0 (API level 26) and higher.
• INTERNET
• READ_PHONE_NUMBERS – Only in Android 8.0 (API level 26) and higher.
• RECORD_AUDIO
• VIBRATE
• WAKE_LOCK

Access to installed apps

When developing an instant experience, keep in mind that it cannot interact with installed apps on a device unless one of the following is true:

• One or more activities within an installed app has set its android:visibleToInstantApps element to true – This element is available to apps running Android 8.0 (API level 26) or higher.
• An installed app contains an intent filter that includes CATEGORY_BROWSABLE.
• The instant experience is sending an intent using either the ACTION_SEND, ACTION_SENDTO, or ACTION_SEND_MULTIPLE action.

Execution environment

Google Play Instant runs instant-enabled app bundles in a special kind of SELinux sandbox for added security. To be compatible with this environment, you need to create the following configuration within your instant-enabled app bundle:

• In your Network Security Config, set usesCleartextTraffic to false.
• Don't share the value of myUid(), which is your app process's kernel-assigned UID.

Build the app bundle

You can use either Android Studio or the command-line interface to build your instant-enabled app bundle.

Android Studio

Using Android Studio, you can build your app bundle by selecting Build > Build Bundle(s) / APK(s) > Build Bundle(s). For more information about building your project, see Build your project.

Command-line interface

You can also build the app bundle from the command line using Gradle. After performing this build, perform a instant-experience sanity check by running the following command:

ia check app-artifact

The app artifact can be a ZIP file, app bundle, or list of APKs that contains at least one instant experience.

Test the instant experience

Before publishing your instant-enabled app bundle, you can test the instant experience from one of the following locations to verify functionality:

• Install onto a local device using Android Studio.
• Install onto a local device using the command-line interface.
• Publish to the internal test track on the Google Play Console.

Note: Instant experiences are available only on devices running Android 5.0 (API level 21) or higher.

Android Studio

To test your app's instant experience on a local machine using Android Studio, complete the following steps:

1. If you have an installed version of your app on your test device, uninstall it.
2. In Android Studio, from the installation options that appear on the General tab of the Run/Debug Configurations dialog, enable the Deploy as instant app checkbox.
3. Select Run > Run in the menu bar, or click Run in the toolbar, then choose the device where you'd like to test your app's instant experiences. Your app's instant experience loads on the test device that you've chosen.

Command-line interface

To test your app's instant experience on a local machine using Android Studio, complete the following steps:

1. If you have an installed version of your app on your test device, uninstall it.
2. Sideload and run your instant app on your test device by entering the following command:

ia run output-from-build-command

Note: You can provide alternative information to ia run to launch an instant experience on a test device. For more information, execute the command: ia help run.

Internal test track

To test your app's instant experience from the Play Store or a banner on your website, publish the app to the internal test track on the Play Console. To do so, complete the following steps:

1. Upload your app bundle by following the steps in the Upload your app bundle to the Play Console guide.
2. Prepare the uploaded bundle for a release to the internal test track. For more information, see the support article on how to Prepare & roll out releases.

3. Sign into an internal tester account on a device, then launch your instant experience from one of the following surfaces:

   • The Try Now button from your app's Play Store listing.
   • A link from a banner on your app's website.

Note: When you use Google Play's internal test track, the 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.

Publish the app bundle to the production track

To publish your instant-enabled app bundle, complete the following steps:

1. If you haven't already, sign your app bundle with a release key and upload the app bundle to the Play Console.
2. In the Play Console, open Release management > Android Instant Apps, then navigate to the instant app production track.
3. Select Update from Library, then select the instant-enabled app bundle that you've uploaded.

Additional resources

To learn more about creating instant experiences and Android App Bundles, see the following resources:

Video: Bundling an App in an Instant

Learn how to add an instant experience to an Android App Bundle in this session from Android Dev Summit '18.

Video: Publish smaller apps with the Android App Bundle

Learn how app bundles help you develop your app more quickly and create smaller APKs for your users.

Codelab: Your First Android App Bundle

A step-by-step guide for creating an Android App Bundle and adding features to it.

The Android App Bundle Format

Learn more about how the bundletool command-line program organizes an app bundle from your app's code and resources.