Making the UAMP sample an instant app

Starting in Android Studio 3.3, the IDE will provide tooling support for instant apps. (As of this writing, Android Studio 3.3 is available as a preview release.) In this blog post we will cover the steps that we took to convert the Universal Android Music Player (UAMP) sample into an instant app. For those hearing about instant apps for the first time, check out the session from the Android Developer summit, or read the documentation previously published about the topic.

Requirements

To build and deploy instant apps without using the command line, we’ll need at least Android Studio 3.3. It is very important to also update the Android Gradle plugin to match the version of Android Studio. For example, at the time of this writing, Android Studio is on version 3.3 RC1 — so we used the following Gradle plugin version: com.android.tools.build:gradle:3.3.0-rc01.

Updating the manifest

Inside of our manifest’s application tag, we need to add <dist:module dist:instant=”true” />. We may see an error stating that “Namespace ‘dist’ is not bound”, in which case we need to add xmlns:dist=”http://schemas.android.com/apk/distribution" to the root manifest tag. Alternatively, we can follow the prompts from Android Studio to automatically resolve the error for us.

We can also add intent filters to handle the VIEW intent for a URL associated with our app, although this is not the only way to trigger an instant app launch. For UAMP, the updated version of the manifest looks like this:

<application ...>
    <!-- Enable instant app support -->
    <dist:module dist:instant="true" />
<activity android:name=".MainActivity">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
<!-- App links for http -->
        <intent-filter android:autoVerify="true">
            <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.android.com"
                android:pathPattern="/uamp" />
        </intent-filter>
<!-- App links for https -->
        <intent-filter android:autoVerify="true">
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data
                android:scheme="https"
                android:host="example.android.com"
                android:pathPattern="/uamp" />
        </intent-filter>
    </activity>
</application>

Building and deploying an instant-enabled bundle

We could follow the process explained in the Google Play Instant documentation, but we can instead change the run configuration in Android Studio. To enable deployment as an instant app, we can select the Deploy as instant app checkbox, as shown in this image:

Enable app deployment as an instant app using the Android Studio UI

Now, all that is left to do is click the very satisfying Run button in Android Studio and, if all the previous steps were done correctly, watch the instant app being deployed and launched automatically!

After this step, we will not see our app listed anywhere in the launcher. To find it, we must go to Settings > Apps, where the deployed instant apps are listed:

Instant app info under Settings > Apps

Launching the instant app

Android will trigger the launch of an instant app in a number of ways. Outside of mechanisms that are tied to the Play Store, launching of an instant app is typically done by sending an ACTION_VIEW to one of the URLs defined as an intent filter in our manifest. For UAMP, running the following ADB command triggers our app:

adb shell am start -a android.intent.action.VIEW "https://example.android.com/uamp"

However, Android will also suggest launching our app from any other app that triggers ACTION_VIEW from URLs, which is basically every app except for web browsers:

UAMP is launched when the Open button is pressed

For more information about app links, see the relevant documentation on the topic, including how to verify the ownership of the links that your app handles.

Known issues

For devices (or emulators) running API level 28, when we clear the Deploy as Instant app checkbox and try to deploy again, the following error occurs:

Error while executing: am start -n “com.example.android.uamp.next/com.example.android.uamp.MainActivity” -a android.intent.action.MAIN -c android.intent.category.LAUNCHER
Starting: Intent { act=android.intent.action.MAIN cat=[android.intent.category.LAUNCHER] cmp=com.example.android.uamp.next/com.example.android.uamp.MainActivity }
Error type 3
Error: Activity class {com.example.android.uamp.next/com.example.android.uamp.MainActivity} does not exist.
Error while Launching activity

The solution is to remove the instant app from the device, either from the Settings > Apps menu on a device or emulator, or by running ./gradlew uninstallAll from the Android Studio terminal tab.