Code Push In Hybrid Apps
This guide explains how to use Shorebird in an Android hybird app scenario (that is, your app embeds Flutter UI in non-Flutter UI).
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 Shorebird 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/shorebirdtech/samples/tree/main/add_to_app.
Add Shorebird to your Flutter moduleβ
First, run shorebird init
in your Flutter module:
shorebird init
Create a Shorebird releaseβ
Create a Shorebird release for your Flutter module:
shorebird 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).
Because Shorebird 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
.
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.
Shorebird 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.shorebird.dev
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.shorebird.dev/download.flutter.io'
+ }
}
}
Even though we are replacing https://storage.googleapis.com/download.flutter.io. with https://download.shorebird.dev/download.flutter.io, any Flutter dependencies that are not unique to Shorebird will still be downloaded from https://storage.googleapis.com/download.flutter.io. This will only work for versions of Flutter that Shorebird supports.
Update your Android app to use this version of the Flutter moduleβ
In app/build.gradle
, add the following:
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 Shorebird is working with a patchβ
Make an edit to the code in your Flutter module. Then run:
shorebird patch aar --release-version 1.2.3+1
If you provided a build number to the shorebird release aar
command using the
--build-number
argument, you must also provide that same build number to the
shorebird 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:shorebird.cc(109)] Shorebird updater: no active patch.
[INFO:shorebird.cc(113)] Starting Shorebird 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