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.

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.6 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.

Learn about the required execution conditions

Google Play Instant runs instant-enabled app bundles in a special kind of SELinux sandbox for added security. This sandbox permits a subset of permissions, as well as limited types of interactions with other apps. The following sections explain the characteristics of this sandbox in more detail.

Supported permissions and operations

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

Handling common unsupported permissions

The following is a list of common, non-supported permissions that you must remove from your application and the recommended migration path for each:

  • ACCESS_WIFI_STATE: Use ACCESS_NETWORK_STATE, which should provides information similar to ACCESS_WIFI_STATE.
  • BILLING: This is a deprecated permission. Use the Google Play Billing library, which no longer requires the com.android.vending.BILLING permission.
  • READ/WRITE_EXTERNAL_STORAGE: Use internal storage instead. If the app must write to external storage, use application-specific directories in external storage. The app does not need to request permission to write to these directories.
  • com.google.android.c2dm.permission.RECEIVE and permission.C2D_MESSAGE: C2DM is deprecated. Migrate to Firebase Cloud Messaging (FCM). FCM does not need any additional permissions to work.

In addition, instant-enabled app bundles cannot do the following:

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.

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.

Declare project dependencies

To use the Google Play Instant APIs in your app, include the following declaration in your app module's build.gradle configuration file:

implementation "com.google.android.gms:play-services-instantapps:17.0.0"

Define the correct version codes

The version code of your app's instant experience needs to be less than the version code of the installable app. The expectation is that users move from the Google Play Instant experience to downloading and installing the app onto their device. The Android framework considers this transition to be an app update.

To make sure that you follow the versioning scheme that users expect, follow one of these strategies:

  • Restart the version codes for the Google Play Instant experience at 1.
  • Increase the version code of the installable APK by a large number, such as 1000, to ensure that there is enough space for your instant experience's version number to increase.

It's OK to develop your instant app and your installable app in two separate Android Studio projects. If you do so, however, you must do the following to publish your app on Google Play:

  1. Use the same package name in both Android Studio projects.
  2. In the Google Play Console, upload both variants to the same application.

For more details on setting your app's version, see Version your app.

Update the target sandbox version

Your instant app's AndroidManifest.xml file needs to be updated to target the sandbox environment that Google Play Instant supports. You can complete this update by adding the android:targetSandboxVersion attribute to your app's <manifest> element, as shown in the following code snippet:

<manifest
   xmlns:android="http://schemas.android.com/apk/res/android"
  ...
   android:targetSandboxVersion="2" ...>

For more information, see documentation on the targetSandboxVersion attribute.

Declare instant-enabled app modules

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

  • If you have an existing app bundle that contains only a base module, you can instant-enable the app bundle as follows:

    1. Open the Project panel by selecting View > Tool Windows > Project from the menu bar.
    2. Right-click on your base module, typically named 'app', and select Refactor > Enable Instant Apps Support.
    3. In the dialog that appears, select your base module from the dropdown menu.
    4. Click OK.

    Android Studio adds the following declaration to the module's manifest:

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

  • 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.

Add support for sign-in

If your instant experience allows users to sign in, your instant-enabled app bundle must support Smart Lock for Passwords on Android. If you are building an "Instant play" game, you should use Google Play Games Services sign-in instead.

Support the execution environment

To be compatible with the SELinux sandbox in which instant experiences run, keep the following in mind when creating your instant-enabled app bundle:

  • Don't share the value of myUid(), which is your app process's kernel-assigned UID.
  • If your app targets Android 8.1 (API level 27) or lower, create a Network Security Config file, and set cleartextTrafficPermitted to false. Instant experiences don't support HTTP traffic. For apps that target Android 9 or higher, cleartext traffic is disabled by default.

  • Your instant experience remains downloaded on a user's device until the instant experience cache is cleared, which occurs in one of the following situations:

    • The instant experience cache is garbage-collected because the device is running low on available memory.
    • The user restarts their device.

    If either process occurs, the user must re-download your instant experience in order to interact with it.

  • If the system is running very low on storage space, it's possible that your instant experience's user data is removed from internal storage. Therefore, it's recommended to periodically sync user data with your app's server so that the user's progress is preserved.

Add logic for instant experience workflows

After you configure your app bundle so that it supports instant experiences, add the logic that's shown in the following sections.

Check whether app is running instant experience

If some of your app's logic depends on whether the user is engaged in your instant experience, call the isInstantApp() method. This method returns true if the currently-running process is an instant experience.

Display an install prompt

If you are building a trial version of your app or game, Google Play Instant allows you to display a prompt within your instant experience, inviting users to install the full experience on their device. To display this prompt, use the InstantApps.showInstallPrompt() method, as shown in the following code snippet:

Kotlin

class MyInstantExperienceActivity : AppCompatActivity {
    // ...
    private fun showInstallPrompt() {
        val postInstall = Intent(Intent.ACTION_MAIN)
                .addCategory(Intent.CATEGORY_DEFAULT)
                .setPackage(your-installed-experience-package-name)

        // The request code is passed to startActivityForResult().
        InstantApps.showInstallPrompt(this@MyInstantExperienceActivity,
                postInstall, request-code, /* referrer= */ null)
    }
}

Java

public class MyInstantExperienceActivity extends AppCompatActivity {
    // ...
    private void showInstallPrompt() {
        Intent postInstall = new Intent(Intent.ACTION_MAIN)
                .addCategory(Intent.CATEGORY_DEFAULT)
                .setPackage(your-installed-experience-package-name);

        // The request code is passed to startActivityForResult().
        InstantApps.showInstallPrompt(MyInstantExperienceActivity.this,
                postInstall, request-code, /* referrer= */ null);
    }
}

Transfer data to an installed experience

If the user enjoys your instant experience, they might decide to install your app. To provide a good user experience, it's important that the user's data is transferred from your instant experience to the full version of your app.

If the user is using a device that runs Android 8.0 (API level 26) or higher, and if your app specifies a targetSandboxVersion of 2, then the user's data is transferred automatically to the full version of your app. Otherwise, you must transfer the data manually. To do so, use one of the following APIs:

  • For users who use devices that run Android 8.0 (API level 26) and higher, use the Cookie API - sample app
  • If users can interact with your experience on devices that run Android 7.1 (API level 25) and lower, add support for the Storage API - sample app

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:

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 the command line, 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

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 publish your app to the internal test track, 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.

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.

Choose where to publish your instant experience

It's possible to launch an instant experience of your app in a subset of the countries and regions where people can install your app. This capability is useful in cases where you want to promote your app's instant experience to users who reside in a specific set of countries and regions.

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.