Refactoring an existing Android app to support Instant App.

This article is not exactly an introduction or guide to Instant App. There are plenty of good articles on this topic. I am just going to share some difficulties we faced while refactoring an existing android app for Instant App support.

Existing Project Structure:

The existing project was on MVP architecture and had all common libraries like Dagger2, Butterknife, RxJava etc. Here is a screenshot of all the dependencies we had in our existing project.

Refactoring Process:

Step 1: Prerequisites

According to official documentation, these are the prerequisites for getting started with Instant App.

  • Install Android Studio version 3.0 or later.
  • JDK 1.8
  • Android SDK 6.0+
  • Android SDK Build Tools 26.x or later
  • Android SDK Tools 25.x or later
  • Android SDK Platform Tools 25.x or later
  • Android Support Library (latest)
  • Android Repository (latest)

Thankfully our app satisfied all of these prerequisites.

Step 2: Installing the Instant Apps Development SDK

This was a very easy step, nothing fancy. Just launch SDK Manager, Go to SDK Tools, Select Instant Apps Development SDK and click apply. That’s all. So far so good.

You can develop Instant Apps on the following devices and emulators only:
1. Devices: Nexus 5X, Nexus 6P, Pixel, Pixel XL, Galaxy S7 running Android 6.0 or higher.
2. Emulator: Nexus 5X image running Android 6.0 (API level 23), x86, with Google APIs.

Step 3: Implement Android App Links

App links were introduced in Android 6.0. Instant Apps leverage the same app links feature to map HTTPS URLs to entry-point activities in Instant Apps. Here is a great video to get started with App links!

In this process, one thing to keep in mind is to be careful while selecting Signing Config. If you select release keystore, you won’t be able to test Applinks in your debug apk. Pretty obvious but easy to miss out while developing.

Step 4: Break your app to Feature Modules

In order to support Instant App feature you have to break your app into Feature Modules. This was the step where we faced most of the challenges. I am going to list down all of them:

Problem 1: Kotlin plugin version

We encountered this problem while converting our App application module to Feature Module. Here is a part of the error message:

null cannot be cast to non-null type


Problem was with kotlin plugin version. We were using plugin version 1.1.2–4. Updating the plugin version to v1.1.2–5 solved the issue.

Problem 2: Android Studio Issue(3.0 Canary 3)

After solving the kotlin plugin problem we faced another issue. Here is a part of the error message:

point to same directory in the file system. Each module has to have a unique path.


Delete all .iml files from your project directory and Re-import the project. Re-open project will not work. You will have to Re-import the project.

Problem 3: Same build.gradle file

After solving Problem 2 our build failed once again. Here is the error message we got.

Error:Failed to resolve: Could not resolve project :Social-News.


At this point you will have multiple build.gradle files. We solved this problem by declaring exactly the same buildTypes in all App and Modules’ build.gradle files.

Problem 4: ButterKnife Problem

After solving problem 3, we got complains from ButterKnife. Tried adding ButterKnife as we add them to library projects, but no luck. As we all developers do, I went to Github to check issues.

I found the following closed issue:

Which was a duplicate of this open issue:

Someone suggested a workaround of moving the butterknife plugin locally into project’s buildsrc. I tried that too, but did not work for me.


I know it’s not a solution but this is what we had to do. We removed Butterknife from our project. Thanks to support library 26+.

If someone finds a real solution to this problem please do comment below.

After solving these problems we were able to successfully build(with one base module) and install the apk to device. Since our original apk size was less than 4Mb, we were able to install the full featured app as an Instant App.

Problem 5: Only TLS protocol like HTTPS:

After installing the apk, we found some of our screens were not displaying anything. After checking the logcat we got to know that network traffic from inside the Instant App must be encrypted using a TLS protocol like HTTPS.


Use only https network connections from the Instant App.

Finally we had a working Instant App.

But our current Instant App consists only one base feature module which is actually the whole app. We were not satisfied with this so we decided to add another feature module to the project. This module will have only one Activity which is actually needed for our Instant App.

Problem 5: Android studio Feature Module Wizard

As soon as I added one new feature module to our project using Android studio Feature Module Wizard, I got this error:

Project refresh failed:

To solve this problem these are the things We tried, which did not work for us:

  • Clean Project
  • Re-import project
  • Restart android Studio
  • Clear cache
  • Re-install android studio(Yes! Tried this too.)


This is what worked for me. I manually deleted every build folder inside my project directory and rebuild the project.

After solving this problem we were able to build the project successfully.

Problem 6: A Strange One

I updated my android studio to 3.0 Canary 5 and my build started to fail. Here is the error I got:

Error:(2) attribute 'split' in <manifest> tag is not a valid split name

I was surprised to see something like this. Since AS was in canary channel, I was also not sure whether the problem is causing because of the update or not.


I removed ‘ — ’ from my Feature Module name and it started working again.

I have seen ‘ — ’ in module names in Google Sample projects and it was working for me earlier. So, I don’t know what’s the exact reason causing this issue. Therefore, I have convinced myself for now with this gif.

These were the main difficulties we faced during our first Instant App development period. Not as smooth as the demo video at I/O 17 right? I still have one problem(Not related to Instant App) left related to Dagger2 which is more of an Architecture level problem, That’s why I am not including it right now. If you have faced any other problems or if you have any better solutions please let me know in the comment section below.

If you liked this article please click the 💚 below to recommend. I would love to hear your thoughts in the comment section or at Twitter. Thanks a lot !