[webview_flutter_android] Added the functionality to fullscreen html5 video

packages/webview_flutter/webview_flutter_android/CHANGELOG.md

@@ -1,6 +1,8 @@
 ## 3.10.0
 
-* Adds support for playing video in fullscreen.
+* Adds support for playing video in fullscreen. See
+  `AndroidWebViewController.setCustomWidgetCallbacks`.
+* Updates minimum supported SDK version to Flutter 3.7/Dart 2.19.
 
 ## 3.9.3
 

packages/webview_flutter/webview_flutter_android/README.md

@@ -36,7 +36,7 @@ This can be configured for versions >=23 with
 `AndroidWebViewWidgetCreationParams.displayWithHybridComposition`. See https://pub.dev/packages/webview_flutter#platform-specific-features
 for more details on setting platform-specific features in the main plugin.
 
-### External Native API
+## External Native API
 
 The plugin also provides a native API accessible by the native code of Android applications or
 packages. This API follows the convention of breaking changes of the Dart API, which means that any
@@ -52,6 +52,27 @@ Java:
 import io.flutter.plugins.webviewflutter.WebViewFlutterAndroidExternalApi;
 ```
 
+## Fullscreen Video
+
+To display a video as fullscreen, an app must manually handle the notification that the current page
+has entered fullscreen mode. This can be done by calling
+`AndroidWebViewController.setCustomWidgetCallbacks`. Below is an example implementation.
+
+<?code-excerpt "example/lib/main.dart (fullscreen_example)"?>
+```dart
+androidController.setCustomWidgetCallbacks(
+  onShowCustomWidget: (Widget widget, OnHideCustomWidgetCallback callback) {
+    Navigator.of(context).push(MaterialPageRoute<void>(
+      builder: (BuildContext context) => widget,
+      fullscreenDialog: true,
+    ));
+  },
+  onHideCustomWidget: () {
+    Navigator.of(context).pop();
+  },
+);
+```
+
 ## Contributing
 
 This package uses [pigeon][3] to generate the communication layer between Flutter and the host

packages/webview_flutter/webview_flutter_android/example/integration_test/webview_flutter_test.dart

@@ -581,6 +581,13 @@ Future<void> main() async {
 
       await tester.pumpAndSettle();
 
+      // Due to security reasons, Chrome doesn't allow to programmatically
+      // toggle a video to fullscreen unless the call is directly comming from
+      // a user triggered event.
+      // The top half of the loaded web content contains a clickable div, which
+      // is tapped using the code below, triggering a user event.
+      //
+      // The offset of 20 x 20 is chosen at random.
       await tester.tapAt(const Offset(20, 20));
 
       await expectLater(fullscreenEntered.future, completes);

packages/webview_flutter/webview_flutter_android/example/lib/main.dart

@@ -423,6 +423,7 @@ class SampleMenu extends StatelessWidget {
   Future<void> _onVideoExample(BuildContext context) {
     final AndroidWebViewController androidController =
         webViewController as AndroidWebViewController;
+    // #docregion fullscreen_example
     androidController.setCustomWidgetCallbacks(
       onShowCustomWidget: (Widget widget, OnHideCustomWidgetCallback callback) {
         Navigator.of(context).push(MaterialPageRoute<void>(
@@ -434,6 +435,7 @@ class SampleMenu extends StatelessWidget {
         Navigator.of(context).pop();
       },
     );
+    // #enddocregion fullscreen_example
 
     return androidController.loadRequest(
       LoadRequestParams(

packages/webview_flutter/webview_flutter_android/lib/src/android_webview_controller.dart

@@ -538,21 +538,28 @@ class AndroidWebViewController extends PlatformWebViewController {
   }
 
   /// Sets the callbacks that are invoked when the host application wants to
-  /// show or hide a custom view.
+  /// show or hide a custom widget.
   ///
   /// The most common use case these methods are invoked a video element wants
   /// to be displayed in fullscreen.
   ///
   /// The [onShowCustomWidget] notifies the host application that web content
-  /// from the specified origin wants to be displayed in a custom view. After
-  /// this call, web content will no longer be rendered in the WebViewWidget,
-  /// but will instead be rendered in the custom widget.
+  /// from the specified origin wants to be displayed in a custom widget. After
+  /// this call, web content will no longer be rendered in the `WebViewWidget`,
+  /// but will instead be rendered in the custom widget. The application may
+  /// explicitly exit fullscreen mode by invoking `onCustomWidgetHidden` in the
+  /// [onShowCustomWidget] callback (ex. when the user presses the back
+  /// button). However, this is generally not necessary as the web page will
+  /// often show its own UI to close out of fullscreen. Regardless of how the
+  /// WebView exits fullscreen mode, WebView will invoke [onHideCustomWidget],
+  /// signaling for the application to remove the custom widget.
   ///
   /// The [onHideCustomWidget] notifies the host application that the custom
-  /// view should be hidden.
+  /// widget must be hidden. After this call, web content will render in the
+  /// original `WebViewWidget` again.
   Future<void> setCustomWidgetCallbacks({
-    OnShowCustomWidgetCallback? onShowCustomWidget,
-    OnHideCustomWidgetCallback? onHideCustomWidget,
+    required OnShowCustomWidgetCallback? onShowCustomWidget,
+    required OnHideCustomWidgetCallback? onHideCustomWidget,
   }) async {
     _onShowCustomWidgetCallback = onShowCustomWidget;
     _onHideCustomWidgetCallback = onHideCustomWidget;