InAppWebView Inspector 🔍

A powerful WebView inspector and debugging tool for flutter_inappwebview. Provides real-time console monitoring, JavaScript execution, and script history management with a draggable overlay interface.

🤖 Developed with Claude: This Flutter library was developed using Vibe coding methodology in collaboration with Claude AI, showcasing the power of AI-assisted development and human-AI collaborative programming.

🌍 Multi-language Documentation

English | 한국어 (Korean) | 日本語 (Japanese)

✨ Features

🚀 Zero Setup Auto UI Injection (New!)

No Manual Widget Placement: Inspector UI automatically injects as overlay when show() is called
Smart Context Discovery: Automatic BuildContext discovery via WidgetsBinding and NavigatorKey fallback
Developer-Controlled: User controls when auto-injection is enabled via debug mode initialization
Hot Reload Compatible: Robust overlay system that works seamlessly with Flutter's hot reload
Performance Optimized: Optional NavigatorKey integration for instant context access
Zero Configuration: Just call toggle() and the UI appears - no Stack widgets or manual placement needed

🖥️ Real-time Console Monitoring

Live Console Output: Monitor all JavaScript console messages (log, warn, error, debug) in real-time
Color-coded Messages: Different colors for different log levels for easy identification
Timestamp Display: Each message includes precise timestamp information
Multi-line Support: Full support for long messages and multi-line output
Clean Interface: Removed unnecessary labels for streamlined debugging experience

🚀 Enhanced JavaScript Execution

Interactive Console: Execute JavaScript code directly in your WebView with intelligent result handling
Smart DOM Object Processing:
- document.querySelector("h1") → Shows element details (tag, id, class, text content)
- document.querySelectorAll("p") → Lists all matching elements with comprehensive information
- document.body.classList → Automatically converts to readable array format
- Functions and complex objects → Displays in developer-friendly format
Enhanced Error Handling: Comprehensive error messages with helpful suggestions for common DOM operations
Unicode & Base64 Support: Advanced script encoding options for complex scenarios

📚 Intelligent Script History System

Pre-loaded Scripts: 15+ commonly used JavaScript snippets ready to use immediately
Frequency-based Sorting: Most-used scripts automatically appear first
Memory-based Storage: Fast, lightweight history management without file I/O
Smart Suggestions: Context-aware script recommendations
Usage Tracking: Automatically tracks and prioritizes frequently used scripts

🎯 Multi-WebView Management

Multiple WebView Support: Handle unlimited WebViews in a single application
Easy Switching: Quick dropdown to switch between registered WebViews
Individual Monitoring: Each WebView maintains its own console and execution context
Automatic Registration: Simple API to register and manage WebView instances

🌍 Comprehensive Internationalization

8 Languages Supported: English, Korean, Japanese, Spanish, French, German, Chinese (Simplified), Portuguese
Auto-detection: Automatic language detection from system locale
Easy Localization: Simple API to set preferred language
Consistent UI: All interface elements properly localized

🎨 Advanced User Interface

Draggable Overlay: Move the inspector anywhere on screen with smooth drag interactions
Resizable Interface: Switch between compact and maximized modes for different use cases
SafeArea Aware: Automatically adjusts to device screen constraints and notches
Stack-based Architecture: Stable popup system without overlay conflicts
Clean Design: Minimal, developer-focused interface optimized for productivity

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  inappwebview_inspector: ^0.2.1
  flutter_inappwebview: ^6.1.5

Then run:

$ flutter pub get

🚀 Quick Start

1. Initialize the Inspector

Add this to your main() function:

import 'package:flutter/foundation.dart';
import 'package:inappwebview_inspector/inappwebview_inspector.dart';

void main() {
  // Zero setup initialization - show() will auto-inject UI
  if (kDebugMode) {
    InAppWebViewInspector.initializeDevelopment(
      enableScriptHistory: true,
      maxScriptHistoryCount: 25,
      localizations: InAppWebViewInspectorLocalizations.english, // Change as needed
      onScriptExecuted: (script, webViewId) {
        print('Executed: $script on $webViewId');
      },
      onConsoleLog: (log) {
        print('Console [${log.levelText}]: ${log.message}');
      },
    );
  }
  
  runApp(MyApp());
}

2. Add NavigatorKey for Optimal Performance (Recommended)

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'WebView Inspector Demo',
      // Add navigatorKey for optimal auto UI injection performance
      navigatorKey: InAppWebViewInspector.navigatorKey,
      home: MyWebViewPage(),
    );
  }
}

3. Simple WebView Setup - Zero Manual UI Placement

✨ New: Zero Setup Auto UI Injection - No need to manually add widgets to your UI!

import 'package:flutter/material.dart';
import 'package:flutter_inappwebview/flutter_inappwebview.dart';
import 'package:inappwebview_inspector/inappwebview_inspector.dart';

class MyWebViewPage extends StatefulWidget {
  @override
  _MyWebViewPageState createState() => _MyWebViewPageState();
}

class _MyWebViewPageState extends State<MyWebViewPage> {
  InAppWebViewController? webViewController;
  final String webViewId = 'main_webview';

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('WebView with Inspector'),
        actions: [
          // Toggle button - UI will auto-inject when pressed!
          IconButton(
            icon: Icon(Icons.bug_report),
            onPressed: InAppWebViewInspector.toggle,
            tooltip: 'Toggle Inspector\n(Zero Setup - UI Auto-Injected!)',
          ),
        ],
      ),
      // ✨ No Stack needed! Inspector UI auto-injects as overlay
      body: Column(
        children: [
          // Your main WebView - Inspector UI auto-injects when show() is called
          Expanded(
            child: InAppWebView(
              initialUrlRequest: URLRequest(
                url: WebUri('https://flutter.dev'),
              ),
              onWebViewCreated: (controller) {
                webViewController = controller;
                
                // Register WebView with inspector
                InAppWebViewInspector.registerWebView(
                  webViewId,
                  controller,
                  'https://flutter.dev',
                );
              },
              onLoadStop: (controller, url) {
                // Update URL in inspector when navigation occurs
                if (url != null) {
                  InAppWebViewInspector.updateWebViewUrl(
                    webViewId,
                    url.toString(),
                  );
                }
              },
              onConsoleMessage: (controller, consoleMessage) {
                // Forward console messages to inspector
                InAppWebViewInspector.addConsoleLog(
                  webViewId,
                  consoleMessage,
                );
              },
              initialSettings: InAppWebViewSettings(
                isInspectable: true, // Enable debugging
                javaScriptEnabled: true,
                domStorageEnabled: true,
              ),
            ),
          ),
        ],
      ),
    );
  }

  @override
  void dispose() {
    // Clean up when page is disposed
    InAppWebViewInspector.unregisterWebView(webViewId);
    super.dispose();
  }
}

4. Control Inspector Visibility

// Show/hide inspector - UI automatically injects as overlay!
InAppWebViewInspector.show();    // ✨ Auto-injects UI overlay
InAppWebViewInspector.hide();    // Removes overlay
InAppWebViewInspector.toggle();  // ✨ Toggle with auto-injection

// Enable/disable inspector
InAppWebViewInspector.enable();
InAppWebViewInspector.disable();

// Check status
bool isVisible = InAppWebViewInspector.isVisible;
bool isEnabled = InAppWebViewInspector.isEnabled;

⚙️ Configuration Options

Development Mode (Recommended for Debug Builds)

// Zero setup - show() always auto-injects UI
if (kDebugMode) {
  InAppWebViewInspector.initializeDevelopment(
    enableScriptHistory: true,
    maxScriptHistoryCount: 25,
    maxConsoleLogCount: 500,
    localizations: InAppWebViewInspectorLocalizations.english,
    onScriptExecuted: (script, webViewId) {
      print('Script executed on $webViewId: $script');
    },
    onConsoleLog: (log) {
      print('Console [${log.levelText}]: ${log.message}');
    },
  );
}

Production Mode (Minimal Impact)

// Only initialize in production if needed
if (!kReleaseMode) {
  InAppWebViewInspector.initializeProduction(
    maxConsoleLogCount: 50,
    enableAutoResultLogging: false,
    enableScriptHistory: false,
    localizations: InAppWebViewInspectorLocalizations.english,
  );
}

Advanced Custom Configuration

// Advanced configuration with auto UI injection
if (kDebugMode) {
  InAppWebViewInspector.initializeWithConfig(
    InAppWebViewInspectorConfig(
      debugMode: true,
      maxConsoleLogCount: 1000,
      enableAutoResultLogging: true,
      enableUnicodeQuoteNormalization: true,
      enableBase64ScriptEncoding: true,
      enableScriptHistory: true,
      maxScriptHistoryCount: 30,
      localizations: InAppWebViewInspectorLocalizations.korean, // Multi-language support
      onScriptExecuted: (script, webViewId) {
        // Custom script execution callback
        analytics.logEvent('script_executed', {'webview_id': webViewId});
      },
      onConsoleLog: (log) {
        // Custom console logging
        if (log.level == ConsoleMessageLevel.ERROR) {
          crashlytics.recordError(log.message, null);
        }
      },
      onError: (error, webViewId) {
        // Error handling callback
        print('Inspector error in $webViewId: $error');
      },
    ),
  );
}

Language Configuration

// Available localizations
InAppWebViewInspectorLocalizations.english
InAppWebViewInspectorLocalizations.korean
InAppWebViewInspectorLocalizations.japanese
InAppWebViewInspectorLocalizations.spanish
InAppWebViewInspectorLocalizations.french
InAppWebViewInspectorLocalizations.german
InAppWebViewInspectorLocalizations.chineseSimplified
InAppWebViewInspectorLocalizations.portuguese

// Auto-detect from system locale
final localization = InAppWebViewInspectorLocalizations.getByLanguageCode(
  Localizations.localeOf(context).languageCode
);

🎯 Advanced Usage Examples

Multiple WebViews Management

class MultiWebViewExample extends StatefulWidget {
  @override
  _MultiWebViewExampleState createState() => _MultiWebViewExampleState();
}

class _MultiWebViewExampleState extends State<MultiWebViewExample> {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Multiple WebViews'),
        actions: [
          // Single toggle button for all WebViews - UI auto-injects!
          IconButton(
            icon: Icon(Icons.bug_report),
            onPressed: InAppWebViewInspector.toggle,
            tooltip: 'Toggle Inspector\n(Zero Setup Auto UI)',
          ),
        ],
      ),
      // ✨ No Stack needed! Inspector UI auto-injects as overlay
      body: Column(
        children: [
          // First WebView
          Expanded(
            child: InAppWebView(
              onWebViewCreated: (controller) {
                InAppWebViewInspector.registerWebView(
                  'webview_1',
                  controller,
                  'https://flutter.dev',
                );
              },
              onConsoleMessage: (controller, consoleMessage) {
                InAppWebViewInspector.addConsoleLog('webview_1', consoleMessage);
              },
              initialSettings: InAppWebViewSettings(
                isInspectable: true,
                javaScriptEnabled: true,
              ),
            ),
          ),
          // Second WebView  
          Expanded(
            child: InAppWebView(
              onWebViewCreated: (controller) {
                InAppWebViewInspector.registerWebView(
                  'webview_2', 
                  controller,
                  'https://dart.dev',
                );
              },
              onConsoleMessage: (controller, consoleMessage) {
                InAppWebViewInspector.addConsoleLog('webview_2', consoleMessage);
              },
              initialSettings: InAppWebViewSettings(
                isInspectable: true,
                javaScriptEnabled: true,
              ),
            ),
          ),
        ],
      ),
    );
  }
}

Custom Console Messages

// Add custom messages from Flutter
InAppWebViewInspector.instance.addCustomConsoleLog(
  InAppWebViewInspectorConsoleMessage(
    webViewId: 'main',
    level: ConsoleMessageLevel.WARNING,
    message: 'Custom warning from Flutter side',
    source: null, // Clean interface without source labels
    line: null,
    timestamp: DateTime.now(),
  ),
);

// Add development debug messages
InAppWebViewInspector.instance.addCustomConsoleLog(
  InAppWebViewInspectorConsoleMessage(
    webViewId: 'main',
    level: ConsoleMessageLevel.LOG,
    message: 'Flutter lifecycle: App resumed',
    source: null,
    line: null,
    timestamp: DateTime.now(),
  ),
);

Programmatic Script Execution

// Execute custom scripts programmatically
void executeCustomScripts() {
  final inspector = InAppWebViewInspector.instance;
  
  // Simple value retrieval
  inspector.executeScript('document.title');
  
  // Complex DOM operations  
  inspector.executeScript('''
    const links = document.querySelectorAll('a');
    Array.from(links).map(link => ({
      text: link.textContent?.trim(),
      href: link.href,
      className: link.className
    }));
  ''');
  
  // Error handling example
  inspector.executeScript('''
    try {
      const result = performComplexOperation();
      console.log('Operation successful:', result);
      return result;
    } catch (error) {
      console.error('Operation failed:', error.message);
      return { error: error.message, stack: error.stack };
    }
  ''');
}

🛠️ Pre-loaded Utility Scripts

The inspector comes with 15+ ready-to-use JavaScript snippets:

Page Information

document.title - Get current page title
window.location.href - Get current URL
document.readyState - Check page load state
document.getElementsByTagName("*").length - Count all elements

DOM Manipulation

document.querySelector("selector") - Find single element with details
document.querySelectorAll("selector") - Find all matching elements
document.body.innerHTML - Get page HTML content
document.cookie - View all cookies

Browser & Performance

navigator.userAgent - Get browser information
window.innerWidth + "x" + window.innerHeight - Get viewport size
performance.now() - High-precision timing
Object.keys(window) - List global variables

Storage Access

localStorage.getItem("key") - Access local storage
sessionStorage.getItem("key") - Access session storage

Development Utilities

console.log("Hello World"); - Basic console logging

📸 Screenshots

iOS Inspector Interface

The inspector running on iOS showing the draggable overlay interface

Android Inspector Interface

The inspector running on Android with the same powerful debugging features

Key Interface Features Shown:

🖱️ Draggable Overlay: Move the inspector anywhere on screen
📱 Responsive Design: Adapts to different screen sizes and orientations
🎯 WebView Selector: Dropdown to switch between multiple WebViews
⌨️ Interactive Console: JavaScript input field with history dropdown
📋 Real-time Logs: Color-coded console output with timestamps
🔄 Resizable Interface: Toggle between compact and maximized modes

🔄 Migration Guide: v0.1.x → v0.2.0

✨ What's New in v0.2.0

Major Feature: Zero Setup Auto UI Injection

No more manual widget placement required
Automatic context discovery and overlay injection
Simplified integration with just toggle() calls

🚨 Breaking Changes

Before (v0.1.x): Manual Stack placement required

// ❌ Old way - Still works but not needed
Scaffold(
  body: Stack(
    children: [
      YourContent(),
      const InAppWebViewInspectorWidget(), // Manual placement
    ],
  ),
)

After (v0.2.0): Zero setup auto-injection (Recommended)

// ✅ New way - UI auto-injects as overlay
Scaffold(
  body: YourContent(), // No Stack needed!
)

// Just call toggle - UI appears automatically
InAppWebViewInspector.toggle();

2. NavigatorKey Integration (New Recommendation)

For optimal performance, add NavigatorKey to your MaterialApp:

// ✅ Recommended for v0.2.0
MaterialApp(
  navigatorKey: InAppWebViewInspector.navigatorKey, // New
  home: YourHomePage(),
)

📋 Migration Steps

Step 1: Update Dependencies

dependencies:
  inappwebview_inspector: ^0.2.1  # Updated
  flutter_inappwebview: ^6.1.5

Step 2: Add NavigatorKey (Recommended)

MaterialApp(
  navigatorKey: InAppWebViewInspector.navigatorKey, // Add this line
  home: YourHomePage(),
)

Step 3: Simplify UI (Optional)

You can now remove manual Stack placement:

// Before: Required Stack
Scaffold(
  body: Stack(
    children: [
      YourContent(),
      const InAppWebViewInspectorWidget(),
    ],
  ),
)

// After: Simple layout - Inspector auto-injects
Scaffold(
  body: YourContent(),
)

Step 4: Test Auto-Injection

// Inspector UI will auto-inject when you call:
InAppWebViewInspector.show();
InAppWebViewInspector.toggle();

⚡ Performance Improvements

Faster Context Discovery: NavigatorKey provides instant context access
Reduced Widget Tree: No manual Stack widgets needed
Hot Reload Friendly: Robust overlay system works seamlessly with Flutter's hot reload

🔧 Troubleshooting Migration Issues

Inspector not appearing: Add navigatorKey: InAppWebViewInspector.navigatorKey to MaterialApp
"No Overlay widget found": Ensure you're calling toggle() after initialization
Layout issues: Remove manual Stack placement - auto-injection handles positioning

🆕 New Features in v0.2.0

Automatic UI Injection: Zero setup overlay system
Smart Context Discovery: Automatic BuildContext discovery
NavigatorKey Integration: Optional performance optimization
Enhanced Error Recovery: Better fallback mechanisms
Hot Reload Compatibility: Improved development experience

⚠️ Important Implementation Notes

✨ Zero Setup Auto UI Injection

New Simplified Approach: No manual widget placement required!

✅ New Zero Setup Method: Auto UI injection (Recommended)

// 1. Add NavigatorKey for optimal performance
MaterialApp(
  navigatorKey: InAppWebViewInspector.navigatorKey, // ✅ Optimal setup
  home: MyWebViewPage(),
)

// 2. Simple UI with no Stack needed
Scaffold(
  body: Column(  // ✅ Simple layout
    children: [
      Expanded(
        child: InAppWebView(
          // Register WebView and inspector auto-injects UI
          onWebViewCreated: (controller) {
            InAppWebViewInspector.registerWebView('main', controller, url);
          },
        ),
      ),
    ],
  ),
)

// 3. Toggle inspector - UI auto-appears as overlay!
InAppWebViewInspector.toggle(); // ✅ Zero manual UI work

For advanced use cases, you can still manually place the widget:

Scaffold(
  body: Stack(
    children: [
      YourMainContent(),
      const InAppWebViewInspectorWidget(), // Manual placement
    ],
  ),
)

Common Issues & Solutions

Inspector not appearing: Ensure NavigatorKey is added to MaterialApp for optimal context discovery
Auto UI injection fails: Check that you're in debug mode and inspector is properly initialized
"No Overlay widget found": Add navigatorKey: InAppWebViewInspector.navigatorKey to your MaterialApp
Dependency conflict with git-sourced flutter_inappwebview: Add dependency override

If your app uses flutter_inappwebview from git source:

dependencies:
  inappwebview_inspector: ^0.2.1
  flutter_inappwebview:
    git:
      url: https://github.com/pichillilorenzo/flutter_inappwebview.git
      ref: master
      path: flutter_inappwebview

dependency_overrides:
  flutter_inappwebview:
    git:
      url: https://github.com/pichillilorenzo/flutter_inappwebview.git
      ref: master
      path: flutter_inappwebview

Development vs Production

Development Build with Auto UI Injection:

if (kDebugMode) {
  InAppWebViewInspector.initializeDevelopment(
    enableScriptHistory: true,
    maxConsoleLogCount: 500,
  );
}

Production Build (Optional):

if (!kReleaseMode) {
  InAppWebViewInspector.initializeProduction(
    maxConsoleLogCount: 50,
    enableScriptHistory: false,
  );
}

📱 Example App

The example app demonstrates:

✅ Complete WebView integration with inspector
✅ Multi-language support demonstration
✅ Pre-loaded script usage
✅ Enhanced DOM object handling
✅ Multiple WebView management
✅ Custom script execution examples

Run the example:

cd example && flutter run

📋 Requirements

Flutter: >= 3.24.0
Dart: >= 3.5.0
flutter_inappwebview: >= 6.1.5

🌐 Platform Support

Platform	Status	Notes
Android	✅ Full Support	All features available
iOS	✅ Full Support	All features available

🤝 Contributing

This project demonstrates the power of AI-assisted development using Claude and Vibe coding methodology. Contributions are welcome!

How to Contribute

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Test your changes thoroughly
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/baccusf/inappwebview_inspector.git
cd inappwebview_inspector

# Install dependencies  
flutter pub get

# Run tests
flutter test

# Run example
cd example && flutter run

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

🤖 Claude AI: This library was developed through AI-human collaborative programming using Claude
⚡ Vibe Coding: Demonstrated the effectiveness of AI-assisted development methodology
💙 Flutter Community: For providing the amazing Flutter framework
🌐 flutter_inappwebview: For the excellent WebView foundation

📞 Support & Community

🐛 Issues: Report bugs and issues
💡 Features: Request new features
📖 Documentation: Check the comprehensive CLAUDE.md for development guidance
💬 Discussions: Join community discussions

📦 pub.dev: Package on pub.dev
🌐 Repository: GitHub Repository
📚 flutter_inappwebview: Core WebView package
🤖 Claude: Learn more about Claude AI

Happy debugging with AI-assisted development! 🐛✨🤖