Repository: flutter
Issue: v2 embedding docs don't explain background plugin cases
Labels: platform-android,engine,d: api docs,a: existing-apps,P2,a: plugins,team-android,triaged-android

This was raised by @ryanheise in [flutter/flutter/issues/47153#issuecomment-578418750](https://github.com/flutter/flutter/issues/47153#issuecomment-578418750):

> The critical thing I was looking for in this project [the android_alarm_manager plugin] was how to initialise the background isolate.
> 
> There are various comments in `FlutterBackgroundExecutor` which touch on things that I would love to see fully explained in the guide and API documentation:
> 
> ```java
>       // We need to create an instance of `FlutterEngine` before looking up the
>       // callback. If we don't, the callback cache won't be initialized and the
>       // lookup will fail.
>       FlutterCallbackInformation flutterCallback =
>           FlutterCallbackInformation.lookupCallbackInformation(callbackHandle);
> ```
> 
> This isn't mentioned in the migration guide and is also not mentioned in the javadoc for `FlutterCallbackInformation`.
> 
> Also:
> 
> ```java
>       // The pluginRegistrantCallback should only be set in the V1 embedding as
>       // plugin registration is done via reflection in the V2 embedding.
>       if (pluginRegistrantCallback != null) {
>         pluginRegistrantCallback.registerWith(new ShimPluginRegistry(backgroundFlutterEngine));
>       }
> ```
> 
> The migration guide does not explain how this reflection approach works.
> 
> Assuming that for each `FlutterEngine` instance, the `GeneratedPluginRegistrant` is automatically called and a new instance of the plugin class is created and attached to the engine resulting in a 1-to-1 mapping between engines and plugins, how does a plugin instance detect whether it is running in a flutter engine that is associated with the activity/ui vs the headless engine? I used to be able to test whether `registrar.activity()` returned null, but now I assume I have to override `onAttachedToEngine` and figure this out from the `FlutterPluginBinding` parameter.
> 
> The `androidalarmmanager` plugin overrides this and uses `getFlutterEngine` which looks almost promising except that this is a deprecated API:
> 
> ```java
>   @Override
>   public void onAttachedToEngine(FlutterPluginBinding binding) {
>     onAttachedToEngine(
>         binding.getApplicationContext(), binding.getFlutterEngine().getDartExecutor());
>   }
> ```
> 
> And even if it were fine for me to call the deprecated `getFlutterEngime` method, I do not see any way from there to get the `RenderSurface` and test whether it's null.
> I can now see that `ServiceAware` might be the way to do it, but this API doesn't seem to work, and none of the official plugins demonstrate how to use it. I made my plugin implement both `ActivityAware` and `ServiceAware` but only the lifecycle methods of the former were actually called. I also passed in my `Service` instance as the constructor argument when creating the background `FlutterEngine` but this itself didn't cause the `ServiceAware` callbacks to be called.
> 
> In any event, I got my plugin working with v2 using a different approach.
> 
> As some constructive feedback, I do appreciate all the hard work the Flutter team is doing, BUT I also hope that this migration experience is not something I will ever have to go through again. My suggestion is that a comprehensive migration guide should be in place before the release is rolled out, and should be prominently linked to from the release notes.

/cc @xster @matthew-carroll