Restrict Android engine flags in release mode

• You build and run standard release apps with the Flutter CLI (flutter run --release, flutter build apk --release, or flutter build appbundle).

• You run tests and benchmarks in debug or profile mode.

• You use --use-application-binary without passing engine configuration flags.

• You launch release builds using Android Intent extras directly (such as with adb shell am start or custom launch intents in native code) to pass engine configuration flags or route arguments.

• Your CI/CD pipelines, automated scripts, or test runners pass flags to prebuilt release binaries using --use-application-binary.

• You build Flutter Android applications using non-Gradle or hermetic build systems (such as Bazel) and configure release binaries with launch-time flags.

If your workflows are affected, use one of the following migration paths:

Switch testing and benchmarking to profile mode

If your automated test pipelines, scripts, or benchmarks pass flags to release binaries dynamically at launch time:

1. Switch your test target to profile mode (--profile). Profile mode mirrors release performance characteristics while retaining support for dynamic runtime flag configuration through Intent extras and the Flutter CLI without recompilation.

Configure direct Intent launches and hermetic build systems

If you launch release builds using Android Intents directly (for example, via adb shell am start or custom test runners), or if you build Flutter Android apps with non-Gradle or hermetic build systems (such as Bazel) that separate compilation from execution:

1. Do not rely on Intent extras for release builds. Any engine flags passed in Intent extras to a release binary are silently ignored by the embedding at runtime.
2. Use profile mode for dynamic testing: For integration tests or performance benchmarks that require varying flags dynamically at launch time, compile and run a profile build instead of a release build.
3. Declare flags statically in AndroidManifest.xml: If you must run a release binary with specific engine flags, statically declare those flags in your AndroidManifest.xml before compiling the release binary. For details, refer to Declare engine flags in AndroidManifest.xml.

Build release binaries with flags directly using the Flutter CLI

If you must run tests against a release binary with the Flutter CLI:

1. Run flutter build or flutter run with your configuration flags without --use-application-binary. The CLI automatically embeds the flags into the compiled manifest.
2. Alternatively, compile separate release binaries for each required configuration.

Configure engine flags programmatically in native host code

If you launch Flutter from native Android code (such as in an add-to-app integration or custom native activity) and previously passed engine flags through Intent extras:

1. Override getFlutterEngineFlags(): If you subclass FlutterActivity or FlutterFragment, override getFlutterEngineFlags() instead of using Intent extras or the deprecated getFlutterShellArgs():

   class MyFlutterActivity : FlutterActivity() {
       override fun getFlutterEngineFlags(): List<String> {
           val flags = super.getFlutterEngineFlags().toMutableList()
           flags.add("--trace-startup")
           return flags
       }
   }

2. Use FlutterFragment.NewEngineFragmentBuilder: If you host a FlutterFragment, pass flags using the builder:

   val fragment = FlutterFragment.withNewEngine()
       .flutterEngineFlags(listOf("--trace-startup"))
       .build<FlutterFragment>()

3. Pre-initialize and cache a FlutterEngine: If you manage the engine lifecycle directly, supply engine arguments to the FlutterEngine constructor:

   val args = arrayOf("--trace-startup", "--enable-impeller=true")
   val flutterEngine = FlutterEngine(context, args)
   FlutterEngineCache.getInstance().put("my_engine_id", flutterEngine)

Declare engine flags in manifest

To configure engine flags statically in release builds, add <meta-data> elements under the <application> tag in your android/app/src/main/AndroidManifest.xml file:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application
        android:label="my_app"
        android:name="${applicationName}"
        android:icon="@mipmap/ic_launcher">
        <!-- Declare engine configuration flags statically -->
        <meta-data
            android:name="io.flutter.embedding.android.DartFlags"
            android:value="--some-dart-flag" />
        <meta-data
            android:name="io.flutter.embedding.android.EnableDartProfiling"
            android:value="false" />
        <activity
            ...
        </activity>
    </application>
</manifest>