Add add-to-app gotcha documentation

[dnfield]

There are a few of us who have worked with Google and non-Google teams that have dealt with some "gotchas" around add-to-app, such as how and when to use certain APIs or whether the framework/engine does certain things automatically the way that the native stack might be expected to behave.

I'd like to write some documentation on this but I'm not sure where.

/cc @parlough /cc @jiahaog @reidbaker who also probably have some good things to write down about this.

[parlough]

I think it makes sense to document these gotchas on the website nearby or within our existing add-to-app documentation. As for exactly which page(s), I guess it depends on the exact issues. Could you start by providing more details or even just the text you think would be valuable, then we can determine where to best place it?

If anyone else has any gotchas/issues/experiences, feel free to drop them here. Thanks! :)

[sfshaza2]

This is great, @dnfield! I love this idea!

[jiahaog]

• We could also expand on Step 3: (Optional) Use a cached FlutterEngine more: onCreate might not be the best place to launch the Flutter engine if the app is not going to use a Flutter drawn screen immediately since this could block startup for ~100ms. It might be helpful to have a canonical example of how to asynchronously start the Engine and then await it when it is needed by the app
• Could be out of scope of this bug, but some examples of how to integrate the Flutter Engine with Dagger / Hilt would be nice too

cc @peixinli / @math1man who also may have more to share.

[math1man]

One thing I find particularly difficult regarding the FlutterEngine initialization is that it has to be done on the main thread. From my digging through the code, I believe it should be possible albeit difficult to rework various code such that the engine initialization can be done entirely on background threads, which could make it more appropriate to kick off such initialization eagerly without necessarily causing jank to the application.

There's definitely room to provide some basic support and better integrations with Dagger/Hilt. For example, FlutterInjector offers a home-made way to "inject" dependencies into the Flutter framework. Flutter could offer a separate package that wraps FlutterInjector in some basic Dagger boilerplate, or possibly even adapt various core APIs that depend on FlutterInjector to permit Dagger-style dependency injection, for example by exposing new constructors that could be invoked in Dagger modules in the suggested Dagger-integration package.

[math1man]

https://docs.flutter.dev/add-to-app/android/add-flutter-screen also has no information about using a FlutterFragment instead of a FlutterActivity. There a lot of strong reasons why add-to-app use cases would prefer a Fragment-based integration over an Activity-based integration, so this should definitely be discussed with all of the requirements that come with it.

[dnfield]

The item that caused me to file this is that native events that hide or get rid of a FlutterView/FlutterViewController or some analog do not tear town and dispose of the widget tree automatically. Several customers have been surprised by this and not realized they'd need to do something like runApp(SizedBox.shrink()) or something to that effect if they want the widget tree to be released from memory.

[math1man]

That's interesting. One solution to that is to dispose of the FlutterEngine. Since we migrated to a singleton FlutterEngine and a less-add-to-app configuration, we never want to lose the widget state.