Code Push In Hybrid Apps
This guide explains how to use Shorebird in an iOS 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 iOS app and a Flutter module. Our
iOS app will be named IosCodePushDemo
and our Flutter module will be named
flutter_module
.
This guide also assumes that you have created a Shorebird account. If you have not created a Shorebird account, 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
Embed the Flutter module in your iOS appβ
Shorebird requires that your Flutter module be embedded in your iOS app as an .xcframework.
The steps to do this are the same as the option B in the official instructions, so in the event of a conflict between the docs here and the official docs, defer to the official docs.
Add the path to your .xcframeworks to Framework Search Pathsβ
In your app target's build settings in Xcode, add the path to your Flutter
module's Release .xcframeworks
directory to Framework Search Paths. The value
you use for this path will be the path to the Release
directory and will be
relative to your app's .xcodeproj
file.
Embed App.xcframework and Flutter.xcframework in your appβ
In the Build Phases tab of your app target, add the App.xcframework
and
Flutter.xcframework
from your Flutter module to the "Embed Frameworks" build
phase:
Ensure the frameworks are signed as part of the build processβ
In the General tab of your app target, ensure that the frameworks have the "Embed and Sign" option selected:
Create a Shorebird releaseβ
Create a Shorebird release for your Flutter module:
shorebird release ios-framework-alpha --release-version 1.2.3+1
The release-version
parameter needs to match the version of the iOS app
that uses this module (i.e., version+build
from the Xcode settings, or
CFBundleShortVersionString+CFBundleVersion
from your app's Info.plist).
The version number for this app would be 1.0.0+3
Because Shorebird only works with release builds, this will only produce a
release version of your archive. This is similar to running
flutter build ios-framework --no-debug --no-profile
.
Verify that your app runsβ
In Xcode, update the current scheme's build configuration to "Release" and run your app. Your app should work as before with no differences.
Submit your app to the App Storeβ
We won't cover this step in detail here, but this is where you would submit your
app to the App Store. For code push to work, it is important that you submit
with the same xcframework
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 ios-framework-alpha --release-version 1.2.3+1
patch
will overwrite the xcframework
generated by release
, meaning that
you will see a "hash mismatch" error if you run the app from Xcode.
As with the release
command, the release version should be the version of the
iOS app that uses this module.
Now run the app directly from the a device (not launched from Xcode), navigate to the Flutter screen, and verify that the patch is recognized and applied.