Loader plugins

The Flitz loader is native code you embed in your own Flutter app. Your app plus the loader is the host: it carries the compiled Dart runtime, the Flutter engine, and every native plugin you use. A bundle (.flitz) is a complete build of your app's Dart side, compiled to bytecode by flitz publish. The loader receives a bundle, checks that it fits the host, and runs it on a Flutter engine of its own.

Where the bundle runs differs by platform:

• Android runs the bundle in a separate process and task. Your app keeps running in its own task, and Back leaves the bundle.
• iOS hands the app's window to the loader. Your app's UI and its Flutter engine are gone until the app is relaunched.

The loader ships as compiled binaries with no Dart-side surface: a Maven AAR plus a Gradle plugin for Android, and a FlitzLoader.xcframework for iOS (CocoaPods or Swift Package Manager). You add the dependency, write a few lines of platform glue, and your host can open bundles.

What the loader does

Every bundle goes through the same sequence on both platforms:

1. Open. A flitz://download link opens the host: the button on the landing page flitz publish creates, a link tapped on the device, or a build picked in the panel. See the URL scheme.
2. Sign in — only in a host with sign-in. The loader renews the user's session, or opens the sign-in page in the system browser.
3. Check. The loader checks that the bundle fits this host: it was built with the same Flitz SDK, the host ships every native package it needs, and the host's SDK is new enough for this loader-plugin version. A bundle that does not fit is refused with an error screen before any of its code runs. See Compatibility.
4. Run. The bundle starts on its own Flutter engine and fills the screen.
5. Clean up. When a bundle is torn down — on Android when you leave it, on either platform when the next bundle replaces it — its extracted files are removed.

The loader takes over only when one of its own links arrives — a flitz://download link, or flitz://flitz-panel in a host with sign-in. A normal home-screen launch still runs your own lib/main.dart, unless you set the host to launch into the panel. There is no Dart API for the loader and no supported way to embed its UI inside your own FlutterActivity / FlutterViewController.

Supported platforms

32-bit ARM (armeabi-v7a) devices are not supported and will crash.

A debug host cannot run bundles, and that includes a plain flutter run. The bundle passes the loader's checks and then fails to start: a blank screen on Android, "Bundle engine did not start" on iOS. Build the host in release mode.

Linux, macOS, Windows, and web hosts are not yet supported — there is no loader plugin for them.

Requirements

• The host is built with the Flitz SDK, not stock Flutter. Stock Flutter does not ship the engine the loader needs, and the loader-plugin build fails when the SDK it builds with is not a Flitz SDK. Pin the SDK with flitz sdk use and point your toolchain at it — see Getting started.
• Host and bundles share one SDK tag. A bundle built with a different SDK is refused with Platform dill hash mismatch (under "Bundle invalid") when it loads. To confirm which SDK the host is built with, check that flutter --version — or flutter.sdk in android/local.properties — points at the path flitz sdk path prints.
• The host ships every native package your bundles need. Every package with native code in the bundle app's dependency graph — a plugin with a native platform implementation, or a package with a native build hook — must also be in the host, whether or not the bundle calls it. Keep the host and the bundle on the same pubspec.yaml and this holds. Adding a native package means rebuilding the host.
• The app meets the loader's minimum OS. Set Android minSdk to 29 and the iOS deployment target to 16.0; the Flutter templates default lower. The Android and iOS quickstarts show where.
• The loader-plugin version supports your SDK. Use the version flitz plugins configure prints — see Plugin versions.

Sign-in and the panel

Two optional loader features, both off by default and part of Flitz Enterprise. Sign-in signs each teammate in with their Flitz account before every load — only a host with sign-in opens builds of an app set to Members only. The panel lets a signed-in teammate browse your organization's apps, tracks, and builds inside the host and run one, with no link needed. See Sign-in and the panel.

Get the host to your team

Every teammate who opens a bundle needs the host on their device. Distribute it the way you already distribute internal builds of your app:

• iOS: TestFlight, or Firebase App Distribution with an ad hoc build, which installs only on devices registered in its provisioning profile.
• Android: a Google Play internal testing track, or Firebase App Distribution.

Whichever you use, the build you upload must be:

• the build that includes the Flitz loader — on Android a flavor listed in enabledFlavors; on iOS a build with FLITZ_ENABLED=true exported (CocoaPods) or your loader scheme (SwiftPM);
• a release build — a debug host cannot run bundles;
• built with the pinned Flitz SDK, like every host.

flutter build appbundle --flavor withLoader --release   # Google Play internal testing
flutter build apk --flavor withLoader --release         # Firebase App Distribution
FLITZ_ENABLED=true flutter build ipa                    # TestFlight
FLITZ_ENABLED=true flutter build ipa --export-method ad-hoc   # Firebase App Distribution

If your organization sets an app to Members only in the portal — an Enterprise feature — its builds open only in a host with sign-in, for a teammate signed in to your organization.

Teammates install the host once. After that, your changes reach them as bundles, with no new build to upload. Upload a new host build whenever you move the SDK pin or add or upgrade a package with native code: until teammates update, the loader refuses bundles built after the change. Changing the loader's scheme, sign-in, or panel settings also takes a new host build.

Credentials

The plugin binaries live in the private Flitz package repository, which has Maven, CocoaPods, and Swift views. Access is handled by the flitz plugins command group — see the CLI reference:

• flitz plugins credentials --write fetches your organization's repository token and stores it in two machine-local files, at mode 0600: as the flitzMavenToken property in ~/.gradle/gradle.properties, which your Gradle build files read, and as a machine entry in ~/.netrc, which CocoaPods and SwiftPM read. The repository URLs live in your build files, not in these files. --write prints a redacted confirmation.
• Without --write, flitz plugins credentials writes nothing but prints the raw token, so do not run it where output is logged.

If you add the loader on iOS through Swift Package Manager, also register the Flitz package registry and sign in to it:

swift package-registry set --global --scope leancode https://swift.cloudsmith.io/leancode/flitz/
swift package-registry login https://swift.cloudsmith.io/leancode/flitz/ \
  --username token --password "$(flitz plugins credentials --print-token)"

Never copy the token into a committed file. Every machine that builds the host needs the token, CI included — see the Android and iOS quickstarts.

Plugin versions

The loader plugin has its own version, separate from the SDK tag. Each plugin version supports Flitz SDKs from a minimum iteration upward — see Compatibility.

• flitz plugins configure prints the loader-plugin version for your pinned SDK, the SDK tag it resolved against, and the repository URLs. flitz plugins configure --version-only prints just the version for scripts. It never prints the token and never edits project files.

Wherever these pages show <plugin-version>, substitute the value flitz plugins configure prints — the quickstarts never carry a hard-coded version. Re-run configure after changing your SDK pin.

Set it up

Reference