Implementing Flutter WebView with JS Bridge Communication

Introduction

This tutorial shows how to implement a Flutter WebView that communicates with JavaScript through a lightweight JS bridge. You will learn how to configure the WebView, expose a message channel from Dart to JavaScript, send messages both ways, and handle common security and debugging concerns. The examples use the official webview_flutter package and focus on practical code you can reuse in mobile development.

Environment Setup

Add webview_flutter to pubspec.yaml and run flutter pub get. On Android, ensure AndroidX and an updated minSdkVersion (19+ recommended). On iOS, enable WKWebView by using the package’s default configuration and add the NSAllowsArbitraryLoads exceptions to Info.plist only if required for development resources.

Import the package and prepare a WebViewController reference. Use JavascriptMode.unrestricted when you need two-way JS communication, but restrict it if your content doesn't require JS to reduce attack surface.

import 'package:webview_flutter/webview_flutter.dart';

late final WebViewController controller;

// Initialize controller in initState or a builder

Creating The JS Bridge

A JS bridge is simply a named communication channel between Dart and JS. For webview_flutter, use JavascriptChannel to receive messages from JS, and controller.evaluateJavascript (or runJavascript) to send messages to JS. The pattern:

• Register a JavascriptChannel with a name (for example, FlutterBridge).

• In the loaded HTML, call window.FlutterBridge.postMessage(JSON.stringify({type:..., payload:...})).

• On the Dart side, parse the incoming JSON and dispatch accordingly.

Example WebView widget with a channel and page load callback:

WebView(
  initialUrl: 'about:blank',
  javascriptMode: JavascriptMode.unrestricted,
  onWebViewCreated: (c) => controller = c,
  javascriptChannels: {
    JavascriptChannel(
      name: 'FlutterBridge',
      onMessageReceived: (msg) => _handleJsMessage(msg.message),
    ),
  },
  onPageFinished: (_) => _injectBootstrapJs(),
)

Inject a small bootstrap JS after load that safely exposes helper functions or registers handlers. Keep the injected script minimal and validate messages on both sides.

Sending And Receiving Messages

Receiving messages: _handleJsMessage should parse JSON and map message types to app actions. Validate the payload shape and origin if you load remote content.

Sending messages: call controller.runJavascript("window.onFlutterMessage(...)") or evaluate a small script that calls a JS function you injected. Use JSON.stringify on the Dart side to serialize complex data into a single string argument.

Example helper to call JS from Dart:

Future<void> sendMessageToWeb(Map<String, dynamic> data) async {
  final json = jsonEncode(data);
  await controller.runJavascript("window.__onFlutterMessage && window.__onFlutterMessage($json);");
}

On the JS side you must implement window.__onFlutterMessage to accept the data and respond via FlutterBridge.postMessage when needed.

Best practices for message format: include a type field, an id for request/response patterns, and a payload field. This makes implementing promises/futures easier: store a Completer keyed by id in Dart, and when the JS returns a message with the same id, complete the completer.

Security And Best Practices

• Limit JavascriptMode to unrestricted only when necessary. If your app loads untrusted remote content, isolate it or avoid executing arbitrary scripts.

• Validate incoming messages: check type, required fields, and expected value ranges. Never execute unsanitized strings as code.

• Use Content Security Policy and served static HTML for predictable behavior when possible. For remote pages, ensure they use HTTPS.

• Use origin checks (if your app loads multiple domains) and a strict message schema to prevent spoofing.

• For Android, consider enabling Safe Browsing and keep WebView updated through Play services; on iOS, rely on WKWebView’s sandbox.

Debugging tips: log both sides of the bridge, attach Chrome remote debugger for Android WebView, and use Safari Web Inspector for iOS. Add a verbose mode that echoes every message with timestamps and IDs.

Vibe Studio

Vibe Studio, powered by Steve’s advanced AI agents, is a revolutionary no-code, conversational platform that empowers users to quickly and efficiently create full-stack Flutter applications integrated seamlessly with Firebase backend services. Ideal for solo founders, startups, and agile engineering teams, Vibe Studio allows users to visually manage and deploy Flutter apps, greatly accelerating the development process. The intuitive conversational interface simplifies complex development tasks, making app creation accessible even for non-coders.

Conclusion

Implementing a JS bridge in Flutter WebView is straightforward with webview_flutter: register JavascriptChannel(s) to receive messages and use controller.runJavascript to send messages. Design a simple message schema (type, id, payload), validate everything, and minimize JS privileges. With request/response IDs and careful validation, you can build reliable, debuggable bi-directional integrations between Flutter and embedded web content—useful for hybrid UI, payment flows, or embedded widgets in mobile development.