Code Push for Android Hybrid Apps

This guide explains how to use Patchwing in an Android hybrid app scenario (that is, your app embeds Flutter UI in non-Flutter UI).

Note

If your app is a pure Flutter app, follow the standard code push guide instead.

Prerequisites

This guide assumes you have already have an Android app and a Flutter module. Our Android app will be named android_app and our Flutter module will be named flutter_module.

This guide also assumes that you have created a Patchwing account. If you have not, please see our code push guide for instructions.

The reference code for this guide is available at https://github.com/AstralWing/samples/tree/main/add_to_app.

Add Patchwing to your Flutter module

First, run patchwing init in your Flutter module:

patchwing init

Create a Patchwing release

Create a Patchwing release for your Flutter module:

patchwing release aar --release-version 1.2.3+1

The release-version parameter needs to match the version of the Android app that uses this module (i.e., versionName+versionCode from the app’s app/build.gradle file).

Note

Because Patchwing only works with release builds, this will only produce a release version of your archive. This is similar to running flutter build aar --no-debug --no-profile.

Note

This command creates an aar with a build number of 1.0. As with the flutter build aar command, you may optionally provide a different build number using the --build-number argument, although this is not necessary. The build number is used to identify the Flutter module in your app’s build.gradle file, as you can see below.

Patchwing does not use the build number, but it should remain consistent between a release and patches to that release.

Update your Android app to use the download.patchwing.net Maven repository

In settings.gradle:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
+        maven {
+           // This is a relative path from this settings.gradle file to the
+           // my_flutter_module/build/host/outputs/repo directory.
+           url '../my_flutter_module/release'
+       }
+       maven {
-           url 'https://storage.googleapis.com/download.flutter.io'
+           url 'https://download.patchwing.net/download.flutter.io'
+      }
    }
}

Note

Even though we are replacing https://storage.googleapis.com/download.flutter.io. with https://download.patchwing.net/download.flutter.io, any Flutter dependencies that are not unique to Patchwing will still be downloaded from https://storage.googleapis.com/download.flutter.io. This will only work for versions of Flutter that Patchwing supports.

Update your Android app to use this version of the Flutter module

In app/build.gradle, add the following:

buildTypes {
    release {
        // ...
+        // The Dart compiler builds libapp.so directly (does not use clang),and already strips
+        // symbols. However when llvm-strip is run on libapp.so, the symbols are re-sorted
+        // causing the hash of the library to change (which can confuse Patchwing tools).
+        // This line tells gradle to skip the unnecessary llvm-strip step for libapp.so
+        // thus ensuring that the libapp.so that Patchwing sees is byte-identical to the one
+        // which ends up in the APK/AAR/AAB.
+        packaging.jniLibs.keepDebugSymbols.add("**/libapp.so")
        // ...
    }
}

dependencies {
    // ...
+    releaseImplementation 'com.example.my_flutter_module:flutter_release:1.0'
    // ...
}

Verify that your app runs

In Android Studio, update the active build variant to release and run your app. Your app should work as before with no differences.

To set the active build variant to release, click on the “Build Variants” tab in the lower left corner of Android Studio. Then select “release” from the “Active Build Variant” dropdown.

Attempting to build with a non-release build variant will not be able to resolve Flutter symbols in your app.

Submit your app to the Play Store

We won’t cover this step in detail here, but this is where you would submit your app to the Play Store. For code push to work, it is important that you submit with the same aar generated by the release command above.

Verify that Patchwing is working with a patch

Make an edit to the code in your Flutter module. Then run:

patchwing patch aar --release-version 1.2.3+1

Note

If you provided a build number to the patchwing release aar command using the --build-number argument, you must also provide that same build number to the patchwing patch aar command.

As with the release command, the release version should be the version of the Android app that uses this module.

Now relaunch the app, navigate to the Flutter screen, and verify that the patch is recognized and applied. In logcat, you should see output like the following:

[INFO:patchwing.cc(109)] Patchwing updater: no active patch.
[INFO:patchwing.cc(113)] Starting Patchwing update
updater::network: Sending patch check request: PatchCheckRequest { app_id: "baad0583-6810-44a7-9034-6aadb8127f29", channel: "stable", release_version: "1.0.0+8", patch_number: None, platform: "android", arch: "aarch64" }
updater::updater: Patch 1 successfully installed.
updater::updater: Update thread finished with status: Update installed