lightbulb_outline Please take our October 2018 developer survey. Start survey

Create and maintain an instant app that uses the feature plugin

This guide teaches you how to set up your development environment for working with instant apps. Next, you learn how to create an instant app, either from the Create project wizard or from an existing app. You then learn how to run and debug an Android Studio project containing an instant app. Finally, the guide provides resources on publishing an instant app.

If you haven't already done so, download Android Studio 3.0 or higher before following the steps in this guide.

Prepare your development environment

In Android Studio, open the Android SDK Manager. On the SDK Platforms tab, make sure that Android 6.0 (API level 23) or later is installed.

Then, open the SDK Tools tab, and install the following packages:

  • Android SDK Build-Tools 26.x or higher
  • Android SDK Platform Tools 25.x or higher
  • Android SDK Tools (latest)
  • Google Play Instant Development SDK (latest)
  • Support Repository (latest)
    • All dependencies of Support Repository (latest version for each)

Request only supported permissions

Instant apps can use only permissions from the list found on the guide to Make your existing app instant-enabled using Android App Bundle.

Create your instant app

You can create an instant app using one of the following workflows:

Create a new instant app project

To create an instant app, complete the following steps:

  1. Launch Android Studio and create a new project:
    • If you haven't opened a project yet, in the Welcome to Android Studio window, click Start a new Android Studio project.
    • If you already have a project open, select File > New Project.
  2. In the Create Android Project window, do the following:
    1. In the Application name box, enter "My First Instant App".
    2. In the Company domain box, enter "example.com".
    3. Leave the Package name as "com.example.myfirstinstantapp".
    4. Click Next.
  3. In the Target Android Devices window, do the following:
    1. Ensure that Phone and Tablet is selected.
    2. Under the Minimum SDK list, check Include Android Instant App support. Click Next.
  4. In the Customize Instant App Support window, leave the default settings. Click Next.
  5. In the Add an Activity to Mobile window, select Empty Activity. Click Next.
  6. In the Configure Activity window, do the following:
    • In the Instant App URL Host box, enter "myfirstinstantapp.example.com" (without the quotation marks).
    • In the Instant App URL route box, enter "/hello" (without the quotation marks).
    • Keep the default values of the other settings.
    • Click Finish.

Android Studio builds and loads your new project's files.

Modularize an existing app

This section describes how to convert an existing monolithic app to a modularized one, then how to add instant-enabled functionality to the newly modularized app.

Create base feature and APK modules

To create instant apps, you first need to create the following modules:

  • A base feature module, or a feature module that's bundled in every instant app that you create. This is different from the base module of an Android App Bundle, which contains both the instant app experience and the initial installed app experience.
  • A minimal module that contains only the shared code that's essential for building your app's APK file.

After completing the process, your app's build process is separated from your app's logic, making it possible to convert part of the logic-based module to an instant app.

Designate your app as a base feature module

When you create an app, it automatically contains a module called "app". This section describes how to declare your app's logic as part of a base feature module.

To move your app's logic into a base feature module, complete the following steps:

  1. Rename your module to something like base.
  2. Update the import statements for your app's resources so that they refer to the newly-named module.
  3. Open your module's base/build.gradle file and designate the module as a feature module by making the following change:

    base/build.gradle

    // Replace
    // apply plugin: 'com.android.application'
    // with
    apply plugin: 'com.android.feature'
  4. This module represents your app's base feature module, so mark it as such by setting the baseFeature flag to true:

    base/build.gradle

    android {
        ...
        baseFeature true
        ...
    }

    Note: If your app has only one feature module, it must be designated as the base feature module.

Create a minimal APK module

In addition to creating a base feature module, you also need to create a minimal module. This module contains the shared code necessary to build your app's APK file.

To create the minimal module, complete the following steps:

  1. Select File > New > New Module...
  2. In the Create New Module dialog that appears, choose Phone & Tablet Module. Click Next.
  3. In the Phone & Tablet Module window, choose a module name and package name. This guide uses apk as the module name.

    Click Next.

  4. In the Add an Activity to Mobile window, select Add No Activity. Click Finish.

Android Studio finishes creating the minimal module and loads it in the project window.

Associate the minimal module with feature modules

You've created a feature module, but Android Studio doesn't include it in your app's APK file unless you associate it with your app's minimal module. To do so, complete the following steps:

  1. Because you must always declare your application ID in the Gradle module that declares com.android.application, move the applicationID line from a feature module to the minimal module.

    To do so, follow the instructions in these code snippets:

    base/build.gradle

    android {
       defaultConfig {
           // Remove this line
           // applicationId "com.mycompany.example"
           ...
       }
       ...
    }
    
    dependencies {
          // Add this line to declare this module's dependency
          // on the minimal module
          application project(":apk")
    }

    apk/build.gradle

    android {
        ...
        defaultConfig {
            // replace
            // applicationId "com.mycompany.example.apk"
            // with
            applicationId "com.mycompany.example"
            ...
        }
        ...
    }
  2. The minimal module needs to depend on each of your app's feature modules. To do so, update the compilation dependencies, as shown in the following code snippet:

    apk/build.gradle

    dependencies {
        implementation project(':base')
        // If your app contains feature modules other than the base feature module,
        // add dependency lines that are similar to the following:
        // implementation project(':feature1')
        // implementation project(':feature2')
    }
  3. In the base feature module, update the AndroidManifest.xml file so that it contains the following contents:

    base/src/main/AndroidManifest.xml

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
              xmlns:tools="http://schemas.android.com/tools"
              package="com.mycompany.example">
    ...
    </manifest>
  4. Each of your app's manifest files must reference a unique package, so update the name in your APK's AndroidManifest.xml as follows:

    apk/src/main/AndroidManifest.xml

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
              package="com.mycompany.example.app">
    </manifest>

Create more feature modules for Google Play Instant

By having feature modules, your app is easier to update. These modules also make it easier for you to create instant apps, where users can click a link to access functionality within a particular feature module without having to install your app.

If you're creating a feature module from scratch, you can add functionality for Google Play Instant immediately.

To create a new feature module for Google Play Instant, complete these steps:

  1. In Android Studio, select File > New > New Module...
  2. In the Create New Module window that appears, choose Instant App. Click Next.
  3. Provide a name for the new feature module. This guide calls it "instant". Click Finish.

Android Studio finishes creating and building your new instant app feature module.

Verify base feature module dependency

Make sure that the feature module includes a dependency on your app's base feature module:

instant/build.gradle

dependencies {
    implementation project(':base')
}

Enable "Try Now" functionality

Figure 1. The "Try Now" button that's shown for an instant app

Google Play Instant allows you to deliver your instant app to users without having them click on a URL. This experience, called "Try Now", is available in the Play Store, as shown in Figure 1.

To provide this capability in your app, you have two options:

  1. Leave your default activity as an entry point for "Try Now" experience.
  2. Add URLs to activities and declare a default URL, which becomes the entry point for the "Try Now" experience.
Use default activity

An activity that includes the following intent filter becomes the entry point:

<activity android:name="com.example...MainActivity" ... >
  <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
  </intent-filter>
</activity>
Create default URL

If you provide URL access to your instant app, you must include a default URL. This URL is the one that's invoked when users click Try Now in the Google Play Store or when users pin your instant app to a launcher. Usually, the default URL corresponds to your app's main activity, found in your app's base feature module.

To add a default URL, include a <meta-data> attribute in the app module that contains your app's main activity, as shown in the following code snippet:

base/manifests/AndroidManifest.xml

<activity android:name="com.example.base.MainActivity" ... >
    <meta-data android:name="default-url"
               android:value="https://example.com/welcome" />
</activity>

Provide URL access to instant app

If you'd like users to be able to open your instant app outside of the Play Store, such as in a banner on your app's website, complete one of the following tasks:

  • Use the Launch API:

    https://play.google.com/store/apps/details?id=package_name&launch=true
  • Add app links to your app. Each app link is a specific URL that you own that, when clicked, loads a specific activity in your instant app.

Associate your domain with your app

The URL Mapping Editor helps you associate your app links with the respective activities that should serves as entry points into your instant app. To learn more, see Verify Android App Links.

Make sure that the app link appears in the manifest file of the feature module that launches when users click the link. The following example includes such a link for a feature module named "survey":

survey/manifests/AndroidManifest.xml

<activity android:name="com.example.survey_module.SurveyActivity" ... >
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data
            android:scheme="http"
            android:host="example.com"
            android:pathPrefix="/survey" />
    </intent-filter>
</activity>

If, after completing these steps, a browser tries to load a URL instead of your instant app, try clearing your DevMan database by running the following command:

$ adb shell pm clear com.google.android.instantapps.devman

Send users directly to your instant app

You can send users directly to your app when they click on your app link. To do so, provide app link verification by following these steps:

  1. Declare website associations with your instant app.
  2. Add auto-verification functionality to each <intent-filter> element that corresponds to an app link:

    survey/manifests/AndroidManifest.xml

    <activity android:name="com.example.survey.SurveyActivity" ... >
         <intent-filter android:autoVerify="true">
             ...
         </intent-filter>
    </activity>

If you've created app links for your instant app, you can load a different feature module in one of the following ways:

  • Invoke an intent that loads a URL associated with that feature module.
  • Use the Play Core Library.

Run your instant app

You can deploy instant apps onto most devices running Android 5.1 (API level 21) or higher. If you don't have a test device, read the following section to learn how you can set up an emulator for running instant apps.

To run the project in Android Studio, do the following:

  1. Open the Project window by clicking View > Tool Windows > Project, then select Run > Run 'instantapp'.
  2. In the Select Deployment Target window, select the target device on which you'd like to run the app.

Android Studio builds your app, then installs it on your test device or emulator.

Set up an emulator that supports instant apps

To set up your emulator for running instant apps, complete the following steps:

  1. Create an Android Virtual Device. To use all the latest features related to instant apps, configure the device so that it runs Android 8.1 (API level 27) or later, uses the x86 architecture, and includes Google APIs.

  2. Start your emulator and log into a test Google account.

  3. In the system's Settings menu, go to Google > Instant Apps and opt into Android Instant Apps.

Deploy your instant app for publishing

To prepare your instant app for publishing, complete the following steps:

  1. In Android Studio, select Build > Generate Signed APK...
  2. In the Generate Signed APK window, choose the instantapp module. Click Next.
  3. Complete the steps described in the Distribute your instant app article.
  4. Navigate to the Google Play Console to complete the workflow, as described in the Prepare & rollout releases article. Make sure you upload your instant app APK.

To learn more about how to prepare and roll out your app in the Google Play Console, see Sign your APK.

Additional resources

Learn more about Google Play Instant from these additional resources:

Codelab: Build Your First Instant App
Add support for Google Play Instant in an existing app.
Codelab: Build a Multi-Feature Instant App
Modularize a multi-feature app.