Package io.flutter.embedding.engine.plugins

# Interface FlutterPlugin

public interface FlutterPlugin
Interface to be implemented by all Flutter plugins.

A Flutter plugin allows Flutter developers to interact with a host platform, e.g., Android and iOS, via Dart code. It includes platform code, as well as Dart code. A plugin author is responsible for setting up an appropriate `MethodChannel` to communicate between platform code and Dart code.

A Flutter plugin has a lifecycle. First, a developer must add a `FlutterPlugin` to an instance of `FlutterEngine`. To do this, obtain a `PluginRegistry` with `FlutterEngine.getPlugins()`, then call `PluginRegistry.add(FlutterPlugin)`, passing the instance of the Flutter plugin. During the call to `PluginRegistry.add(FlutterPlugin)`, the `FlutterEngine` will invoke `onAttachedToEngine(FlutterPluginBinding)` on the given `FlutterPlugin`. If the `FlutterPlugin` is removed from the `FlutterEngine` via `PluginRegistry.remove(Class)`, or if the `FlutterEngine` is destroyed, the `FlutterEngine` will invoke `onDetachedFromEngine(FlutterPluginBinding)` on the given `FlutterPlugin`.

Once a `FlutterPlugin` is attached to a `FlutterEngine`, the plugin's code is permitted to access and invoke methods on resources within the `FlutterPlugin.FlutterPluginBinding` that the `FlutterEngine` gave to the `FlutterPlugin` in `onAttachedToEngine(FlutterPluginBinding)`. This includes, for example, the application `Context` for the running app.

The `FlutterPlugin.FlutterPluginBinding` provided in `onAttachedToEngine(FlutterPluginBinding)` is no longer valid after the execution of `onDetachedFromEngine(FlutterPluginBinding)`. Do not access any properties of the `FlutterPlugin.FlutterPluginBinding` after the completion of `onDetachedFromEngine(FlutterPluginBinding)`.

To register a `MethodChannel`, obtain a `BinaryMessenger` via the `FlutterPlugin.FlutterPluginBinding`.

An Android Flutter plugin may require access to app resources or other artifacts that can only be retrieved through a `Context`. Developers can access the application context via `FlutterPlugin.FlutterPluginBinding.getApplicationContext()`.

Some plugins may require access to the `Activity` that is displaying a Flutter experience, or may need to react to `Activity` lifecycle events, e.g., `onCreate()`, `onStart()`, `onResume()`, `onPause()`, `onStop()`, `onDestroy()`. Any such plugin should implement `ActivityAware` in addition to implementing `FlutterPlugin`. `ActivityAware` provides callback hooks that expose access to an associated `Activity` and its `Lifecycle`. All plugins must respect the possibility that a Flutter experience may never be associated with an `Activity`, e.g., when Flutter is used for background behavior. Additionally, all plugins must respect that a `Activity`s may come and go over time, thus requiring plugins to cleanup resources and recreate those resources as the `Activity` comes and goes.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static interface`
  `FlutterPlugin.FlutterAssets`
  Provides Flutter plugins with access to Flutter asset information.
  `static class`
  `FlutterPlugin.FlutterPluginBinding`
  Resources made available to all plugins registered with a given `FlutterEngine`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `onAttachedToEngine(FlutterPlugin.FlutterPluginBinding binding)`
  This `FlutterPlugin` has been associated with a `FlutterEngine` instance.
  `void`
  `onDetachedFromEngine(FlutterPlugin.FlutterPluginBinding binding)`
  This `FlutterPlugin` has been removed from a `FlutterEngine` instance.

- ## Method Details

  - ### onAttachedToEngine

    void onAttachedToEngine(@NonNull FlutterPlugin.FlutterPluginBinding binding)
    This `FlutterPlugin` has been associated with a `FlutterEngine` instance.

    Relevant resources that this `FlutterPlugin` may need are provided via the `binding`. The `binding` may be cached and referenced until `onDetachedFromEngine(FlutterPluginBinding)` is invoked and returns.

  - ### onDetachedFromEngine

    void onDetachedFromEngine(@NonNull FlutterPlugin.FlutterPluginBinding binding)
    This `FlutterPlugin` has been removed from a `FlutterEngine` instance.

    The `binding` passed to this method is the same instance that was passed in `onAttachedToEngine(FlutterPluginBinding)`. It is provided again in this method as a convenience. The `binding` may be referenced during the execution of this method, but it must not be cached or referenced after this method returns.

    `FlutterPlugin`s should release all resources in this method.