Android

Add the Maven repository

Add the authenticated repository to both blocks of android/settings.gradle.kts: pluginManagement resolves the Gradle plugin marker, dependencyResolutionManagement resolves the AAR the plugin pulls in transitively. The credentials reference the flitzMavenToken property that credentials --write stored in ~/.gradle/gradle.properties — nothing secret lands in a committed file.

pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
        maven {
            url = uri("<maven-repo-url>")
            credentials {
                username = "token"
                password = providers.gradleProperty("flitzMavenToken").get()
            }
        }
    }
    plugins {
        id("pl.leancode.flitz.loader") version "<plugin-version>"
    }
}

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("<maven-repo-url>")
            credentials {
                username = "token"
                password = providers.gradleProperty("flitzMavenToken").get()
            }
        }
    }
}

The Flutter Gradle plugin injects project-level repositories that take precedence over the settings-level ones, so add the same repository block to allprojects in the top-level android/build.gradle.kts as well — otherwise the AAR does not resolve during the app build:

allprojects {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("<maven-repo-url>")
            credentials {
                username = "token"
                password = providers.gradleProperty("flitzMavenToken").get()
            }
        }
    }
}

Apply the Gradle plugin

Apply the plugin unconditionally in android/app/build.gradle.kts, after com.android.application (the plugin fails configuration if it is applied to anything other than an Android application module). Do not add an implementation("pl.leancode.flitz:loader-android:…") line — the plugin adds the AAR at its own version.

plugins {
    id("com.android.application")
    id("kotlin-android")
    id("dev.flutter.flutter-gradle-plugin")
    id("pl.leancode.flitz.loader")
}

Choose the flavors that carry the loader

The loader attaches per product flavor, through the flitz { } block. Prefer a flavor your project already has (a staging or dev flavor is the usual choice). If the project has no flavors, add a dimension with a loader-bearing flavor and a clean one:

android {
    // … your existing config …
    flavorDimensions += "loader"
    productFlavors {
        create("withLoader") { dimension = "loader" }
        create("withoutLoader") { dimension = "loader" }
    }
}

flitz {
    // The loader is active ONLY in the flavors listed here.
    enabledFlavors = listOf("withLoader")
}

enabledFlavors is the only activation control — there is no environment variable, no build-type selector, and no conditional apply. Its rules:

• Opt-in default. An empty or omitted list activates the loader in no variant. The build logs one flitz.loader: applied but inactive line so an inert plugin is never silent.
• Matching is on the variant's combined flavorName. With one dimension that is the flavor itself (withLoader); with two dimensions it is the camel-cased combination (freeStaging), never a bare dimension value. The build type (debug/profile/release) is never part of the decision.
• An unknown name fails the build. An entry that matches no produced variant aborts configuration with a message listing the bad entries and the flavors the project actually declares. This also catches "set enabledFlavors but declared no flavors": a project without productFlavors produces only the empty flavor name.

An inactive flavor's APK is byte-for-byte the same as one built with the plugin never applied: no AAR, no loader activities, no CAMERA permission, no flitz:// intent filter, none of the loader's transitive dependencies. Absence is the off switch.

Manifest — nothing to edit

For each active variant, the AAR's manifest merges into yours automatically:

• pl.leancode.flitz.loader.BundleLoaderActivity — exported, singleTask, with a VIEW + DEFAULT + BROWSABLE intent filter for the flitz scheme.
• pl.leancode.flitz.loader.BundleRunnerActivity — not exported; hosts the bundle's engine.
• The INTERNET, ACCESS_NETWORK_STATE, and CAMERA permissions, and a non-required android.hardware.camera.any feature.

Your own MainActivity keeps MAIN/LAUNCHER, so a home-screen tap still opens your app; a flitz:// URL is dispatched straight to BundleLoaderActivity. The intent filter's scheme comes from the flitzUrlScheme manifest placeholder, which the Gradle plugin sets from flitz { urlScheme } (default flitz) — see Custom schemes.

The plugin also registers two per-variant tasks that run on every build and place generated assets in the APK:

• flitzGenerateAvailablePlugins<Variant> writes assets/flitz_loader_available_plugins.json from .flutter-plugins-dependencies (the file flutter pub get writes at the project root).
• flitzGenerateHostConfig<Variant> writes assets/flitz_loader_host_config.json — the expected platform_dill_hash values derived from the Flitz SDK at flutter.sdk in local.properties (falling back to FLUTTER_ROOT). If that path is not a Flitz SDK, the build fails naming the missing file.

Build and run

Build the loader-bearing flavor in profile or release mode — a debug host rejects bundles — for arm64:

flutter build apk --flavor withLoader --release --target-platform=android-arm64

Install it on a device, then open a bundle you already have on hand. The flitz://run form points at an absolute path the app process can read:

adb push my_bundle.flitz /data/local/tmp/my_bundle.flitz
adb shell am start \
    -a android.intent.action.VIEW \
    -d "flitz://run?path=/data/local/tmp/my_bundle.flitz" \
    <your.application.id>

Follow the loader log with adb logcat -s FlitzLoader:* flutter:*. A successful load reports Platform dill hash verified, Plugin check: … — OK, Native asset check: … — OK, and finally FlutterView attached.

In day-to-day use nobody types that command: flitz publish prints a QR code and a flitz://download?url=… link; a teammate scans it on a real device and the loader downloads the bundle over HTTPS and runs it. See flitz publish.