Add WebView JavaScript channels (Dart side). (flutter#1116)

Allows JavaScript code running in the WebView to send messages that will be received by the Flutter app's Dart code.

To keep the PRs smaller this does not include the platform side implementations which will be sent in following PRs.

Right now there are no return values on the JavaScript side, we could think of returning a JavaScript promise (or a promise equivalent) in the future, but as a first step I start without it (`evaluateJavascript` can be used to pass messages in the other direction so this shouldn't be a blocking limitation).
I believe that if we end up adding a return value on the JavaScript side this could be done without making a breaking change.

### Sample usage
Dart:
```dart
WebView(
  javascriptChannels: <JavascriptChannel>[
    JavascriptChannel(name: 'Print', onMessageReceived: (String msg) {print(msg); }),
  ].toSet(),
),
```

JavaScript (running inside the WebView):
```javascript
Print.postMessage('Hello!');
```


Fixes: flutter/flutter#24837

Author: amirh

packages/webview_flutter/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.3.1
+
+* Added JavaScript channels to facilitate message passing from JavaScript code running inside
+  the WebView to the Flutter app's Dart code.
+
 ## 0.3.0
 
 * **Breaking change**. Migrate from the deprecated original Android Support

packages/webview_flutter/example/lib/main.dart

@@ -23,17 +23,34 @@ class WebViewExample extends StatelessWidget {
           SampleMenu(_controller.future),
         ],
       ),
-      body: WebView(
-        initialUrl: 'https://flutter.io',
-        javascriptMode: JavascriptMode.unrestricted,
-        onWebViewCreated: (WebViewController webViewController) {
-          _controller.complete(webViewController);
-        },
-      ),
+      // We're using a Builder here so we have a context that is below the Scaffold
+      // to allow calling Scaffold.of(context) so we can show a snackbar.
+      body: Builder(builder: (BuildContext context) {
+        return WebView(
+          initialUrl: 'https://flutter.io',
+          javascriptMode: JavascriptMode.unrestricted,
+          onWebViewCreated: (WebViewController webViewController) {
+            _controller.complete(webViewController);
+          },
+          javascriptChannels: <JavascriptChannel>[
+            _toasterJavascriptChannel(context),
+          ].toSet(),
+        );
+      }),
       floatingActionButton: favoriteButton(),
     );
   }
 
+  JavascriptChannel _toasterJavascriptChannel(BuildContext context) {
+    return JavascriptChannel(
+        name: 'Toaster',
+        onMessageReceived: (JavascriptMessage message) {
+          Scaffold.of(context).showSnackBar(
+            SnackBar(content: Text(message.message)),
+          );
+        });
+  }
+
   Widget favoriteButton() {
     return FutureBuilder<WebViewController>(
         future: _controller.future,
@@ -44,7 +61,7 @@ class WebViewExample extends StatelessWidget {
               onPressed: () async {
                 final String url = await controller.data.currentUrl();
                 Scaffold.of(context).showSnackBar(
-                  SnackBar(content: Text("Favorited $url")),
+                  SnackBar(content: Text('Favorited $url')),
                 );
               },
               child: const Icon(Icons.favorite),
@@ -56,7 +73,7 @@ class WebViewExample extends StatelessWidget {
 }
 
 enum MenuOptions {
-  evaluateJavascript,
+  showUserAgent,
   toast,
 }
 
@@ -73,8 +90,8 @@ class SampleMenu extends StatelessWidget {
         return PopupMenuButton<MenuOptions>(
           onSelected: (MenuOptions value) {
             switch (value) {
-              case MenuOptions.evaluateJavascript:
-                _onEvaluateJavascript(controller.data, context);
+              case MenuOptions.showUserAgent:
+                _onShowUserAgent(controller.data, context);
                 break;
               case MenuOptions.toast:
                 Scaffold.of(context).showSnackBar(
@@ -87,8 +104,8 @@ class SampleMenu extends StatelessWidget {
           },
           itemBuilder: (BuildContext context) => <PopupMenuItem<MenuOptions>>[
                 PopupMenuItem<MenuOptions>(
-                  value: MenuOptions.evaluateJavascript,
-                  child: const Text('Evaluate JavaScript'),
+                  value: MenuOptions.showUserAgent,
+                  child: const Text('Show user agent'),
                   enabled: controller.hasData,
                 ),
                 const PopupMenuItem<MenuOptions>(
@@ -101,15 +118,12 @@ class SampleMenu extends StatelessWidget {
     );
   }
 
-  void _onEvaluateJavascript(
+  void _onShowUserAgent(
       WebViewController controller, BuildContext context) async {
-    final String result = await controller
-        .evaluateJavascript("document.body.style.backgroundColor = 'red'");
-    Scaffold.of(context).showSnackBar(
-      SnackBar(
-        content: Text('JavaScript evaluated, the result is: $result'),
-      ),
-    );
+    // Send a message with the user agent string to the Toaster JavaScript channel we registered
+    // with the WebView.
+    controller.evaluateJavascript(
+        'Toaster.postMessage("User Agent: " + navigator.userAgent);');
   }
 }
 

packages/webview_flutter/lib/webview_flutter.dart

@@ -19,6 +19,51 @@ enum JavascriptMode {
   unrestricted,
 }
 
+/// A message that was sent by JavaScript code running in a [WebView].
+class JavascriptMessage {
+  /// Constructs a JavaScript message object.
+  ///
+  /// The `message` parameter must not be null.
+  const JavascriptMessage(this.message) : assert(message != null);
+
+  /// The contents of the message that was sent by the JavaScript code.
+  final String message;
+}
+
+/// Callback type for handling messages sent from Javascript running in a web view.
+typedef void JavascriptMessageHandler(JavascriptMessage message);
+
+final RegExp _validChannelNames = RegExp('^[a-zA-Z_][a-zA-Z0-9]*\$');
+
+/// A named channel for receiving messaged from JavaScript code running inside a web view.
+class JavascriptChannel {
+  /// Constructs a Javascript channel.
+  ///
+  /// The parameters `name` and `onMessageReceived` must not be null.
+  JavascriptChannel({
+    @required this.name,
+    @required this.onMessageReceived,
+  })  : assert(name != null),
+        assert(onMessageReceived != null),
+        assert(_validChannelNames.hasMatch(name));
+
+  /// The channel's name.
+  ///
+  /// Passing this channel object as part of a [WebView.javascriptChannels] adds a channel object to
+  /// the Javascript window object's property named `name`.
+  ///
+  /// The name must start with a letter or underscore(_), followed by any combination of those
+  /// characters plus digits.
+  ///
+  /// Note that any JavaScript existing `window` property with this name will be overriden.
+  ///
+  /// See also [WebView.javascriptChannels] for more details on the channel registration mechanism.
+  final String name;
+
+  /// A callback that's invoked when a message is received through the channel.
+  final JavascriptMessageHandler onMessageReceived;
+}
+
 /// A web view widget for showing html content.
 class WebView extends StatefulWidget {
   /// Creates a new web view.
@@ -32,6 +77,7 @@ class WebView extends StatefulWidget {
     this.onWebViewCreated,
     this.initialUrl,
     this.javascriptMode = JavascriptMode.disabled,
+    this.javascriptChannels,
     this.gestureRecognizers,
   })  : assert(javascriptMode != null),
         super(key: key);
@@ -56,6 +102,35 @@ class WebView extends StatefulWidget {
   /// Whether Javascript execution is enabled.
   final JavascriptMode javascriptMode;
 
+  /// The set of [JavascriptChannel]s available to JavaScript code running in the web view.
+  ///
+  /// For each [JavascriptChannel] in the set, a channel object is made available for the
+  /// JavaScript code in a window property named [JavascriptChannel.name].
+  /// The JavaScript code can then call `postMessage` on that object to send a message that will be
+  /// passed to [JavascriptChannel.onMessageReceived].
+  ///
+  /// For example for the following JavascriptChannel:
+  ///
+  /// ```dart
+  /// JavascriptChannel(name: 'Print', onMessageReceived: (String message) { print(message); });
+  /// ```
+  ///
+  /// JavaScript code can call:
+  ///
+  /// ```javascript
+  /// Print.postMessage('Hello');
+  /// ```
+  ///
+  /// To asynchronously invoke the message handler which will print the message to standard output.
+  ///
+  /// Adding a new JavaScript channel only takes affect after the next page is loaded.
+  ///
+  /// Set values must not be null. A [JavascriptChannel.name] cannot be the same for multiple
+  /// channels in the list.
+  ///
+  /// A null value is equivalent to an empty set.
+  final Set<JavascriptChannel> javascriptChannels;
+
   @override
   State<StatefulWidget> createState() => _WebViewState();
 }
@@ -103,45 +178,79 @@ class _WebViewState extends State<WebView> {
         '$defaultTargetPlatform is not yet supported by the webview_flutter plugin');
   }
 
+  @override
+  void initState() {
+    super.initState();
+    _assertJavascriptChannelNamesAreUnique();
+  }
+
   @override
   void didUpdateWidget(WebView oldWidget) {
     super.didUpdateWidget(oldWidget);
-    _updateSettings(_WebSettings.fromWidget(widget));
+    _assertJavascriptChannelNamesAreUnique();
+    _updateConfiguration(_WebSettings.fromWidget(widget));
   }
 
-  Future<void> _updateSettings(_WebSettings settings) async {
+  Future<void> _updateConfiguration(_WebSettings settings) async {
     _settings = settings;
     final WebViewController controller = await _controller.future;
     controller._updateSettings(settings);
+    controller._updateJavascriptChannels(widget.javascriptChannels);
   }
 
   void _onPlatformViewCreated(int id) {
-    final WebViewController controller =
-        WebViewController._(id, _WebSettings.fromWidget(widget));
+    final WebViewController controller = WebViewController._(
+      id,
+      _WebSettings.fromWidget(widget),
+      widget.javascriptChannels,
+    );
     _controller.complete(controller);
     if (widget.onWebViewCreated != null) {
       widget.onWebViewCreated(controller);
     }
   }
+
+  void _assertJavascriptChannelNamesAreUnique() {
+    if (widget.javascriptChannels == null ||
+        widget.javascriptChannels.isEmpty) {
+      return;
+    }
+    assert(_extractChannelNames(widget.javascriptChannels).length ==
+        widget.javascriptChannels.length);
+  }
+}
+
+Set<String> _extractChannelNames(Set<JavascriptChannel> channels) {
+  final Set<String> channelNames = channels == null
+      ? Set<String>()
+      : channels.map((JavascriptChannel channel) => channel.name).toSet();
+  return channelNames;
 }
 
 class _CreationParams {
-  _CreationParams({this.initialUrl, this.settings});
+  _CreationParams(
+      {this.initialUrl, this.settings, this.javascriptChannelNames});
 
   static _CreationParams fromWidget(WebView widget) {
     return _CreationParams(
       initialUrl: widget.initialUrl,
       settings: _WebSettings.fromWidget(widget),
+      javascriptChannelNames:
+          _extractChannelNames(widget.javascriptChannels).toList(),
     );
   }
 
   final String initialUrl;
+
   final _WebSettings settings;
 
+  final List<String> javascriptChannelNames;
+
   Map<String, dynamic> toMap() {
     return <String, dynamic>{
       'initialUrl': initialUrl,
       'settings': settings.toMap(),
+      'javascriptChannelNames': javascriptChannelNames,
     };
   }
 }
@@ -178,14 +287,32 @@ class _WebSettings {
 /// A [WebViewController] instance can be obtained by setting the [WebView.onWebViewCreated]
 /// callback for a [WebView] widget.
 class WebViewController {
-  WebViewController._(int id, _WebSettings settings)
-      : _channel = MethodChannel('plugins.flutter.io/webview_$id'),
-        _settings = settings;
+  WebViewController._(
+      int id, this._settings, Set<JavascriptChannel> javascriptChannels)
+      : _channel = MethodChannel('plugins.flutter.io/webview_$id') {
+    _updateJavascriptChannelsFromSet(javascriptChannels);
+    _channel.setMethodCallHandler(_onMethodCall);
+  }
 
   final MethodChannel _channel;
 
   _WebSettings _settings;
 
+  // Maps a channel name to a channel.
+  Map<String, JavascriptChannel> _javascriptChannels =
+      <String, JavascriptChannel>{};
+
+  Future<void> _onMethodCall(MethodCall call) async {
+    switch (call.method) {
+      case 'javascriptChannelMessage':
+        final String channel = call.arguments['channel'];
+        final String message = call.arguments['message'];
+        _javascriptChannels[channel]
+            .onMessageReceived(JavascriptMessage(message));
+        break;
+    }
+  }
+
   /// Loads the specified URL.
   ///
   /// `url` must not be null.
@@ -279,6 +406,40 @@ class WebViewController {
     return _channel.invokeMethod('updateSettings', updateMap);
   }
 
+  Future<void> _updateJavascriptChannels(
+      Set<JavascriptChannel> newChannels) async {
+    final Set<String> currentChannels = _javascriptChannels.keys.toSet();
+    final Set<String> newChannelNames = _extractChannelNames(newChannels);
+    final Set<String> channelsToAdd =
+        newChannelNames.difference(currentChannels);
+    final Set<String> channelsToRemove =
+        currentChannels.difference(newChannelNames);
+    if (channelsToRemove.isNotEmpty) {
+      // TODO(amirh): remove this when the invokeMethod update makes it to stable Flutter.
+      // https://github.com/flutter/flutter/issues/26431
+      // ignore: strong_mode_implicit_dynamic_method
+      _channel.invokeMethod(
+          'removeJavascriptChannels', channelsToRemove.toList());
+    }
+    if (channelsToAdd.isNotEmpty) {
+      // TODO(amirh): remove this when the invokeMethod update makes it to stable Flutter.
+      // https://github.com/flutter/flutter/issues/26431
+      // ignore: strong_mode_implicit_dynamic_method
+      _channel.invokeMethod('addJavascriptChannels', channelsToAdd.toList());
+    }
+    _updateJavascriptChannelsFromSet(newChannels);
+  }
+
+  void _updateJavascriptChannelsFromSet(Set<JavascriptChannel> channels) {
+    _javascriptChannels.clear();
+    if (channels == null) {
+      return;
+    }
+    for (JavascriptChannel channel in channels) {
+      _javascriptChannels[channel.name] = channel;
+    }
+  }
+
   /// Evaluates a JavaScript expression in the context of the current page.
   ///
   /// On Android returns the evaluation result as a JSON formatted string.

packages/webview_flutter/pubspec.yaml

@@ -1,6 +1,6 @@
 name: webview_flutter
 description: A Flutter plugin that provides a WebView widget on Android and iOS.
-version: 0.3.0
+version: 0.3.1
 author: Flutter Team <flutter-dev@googlegroups.com>
 homepage: https://github.com/flutter/plugins/tree/master/packages/webview_flutter