Troubleshooting & FAQ

Common Issues

White/Blank Screen

Symptom: The browser area shows a white or blank texture.

Possible Cause Solution
WebView2 not installed (Windows) Install WebView2 Runtime
WebKitGTK not installed (Linux) sudo apt install libwebkit2gtk-4.1-0 libgtk-3-0
URL blocked by security Use https:// instead of http://
DLL not loaded Check Unity Console for DLL loading errors
Webview off-screen Set Normalised Rect to (0,0,0,0) for fullscreen

Address Bar Not Updating

Possible Cause Solution
Missing event subscription Subscribe to _browser.WebView.UrlChanged
WebView not ready Subscribe in Start()/Update() with null-check

Back/Forward Buttons Don’t Work

Possible Cause Solution
Not polling state Read WebView.CanGoBack/CanGoForward each frame

Keyboard Input Not Working

Possible Cause Solution
Browser doesn’t have focus Click on the browser RawImage first
InputForwarder missing Add the InputForwarder component to the same GameObject

Black Texture / No Capture

Possible Cause Solution
GPU driver issue Update GPU drivers (PrintWindow + PW_RENDERFULLCONTENT)
DPI scaling Ensure Normalised Rect accounts for system DPI
Page not loaded Wait for PageFinished event before expecting texture

Bridge Messages Not Arriving

Possible Cause Solution
Bridge not enabled Check Bridge Enabled in Inspector
Wrong handler name Names are case-sensitive
Page reloaded Re-register JS listeners on DOMContentLoaded
Subscription disposed Verify your IDisposable subscription is alive

FAQ

Can I show multiple browser windows?

No. One webview instance per application is supported.

Does it work in the Unity Editor?

Yes on Windows Editor — uses the same WebView2 engine. Other platforms fall back to EditorWebView if native DLLs are missing.

Can I load local HTML files?

Yes. Use a file:// URL:

string path = Path.Combine(Application.streamingAssetsPath, "mypage.html");
_browser.LoadUrl("file://" + path);

On Android, use file:///android_asset/ for StreamingAssets.

Can I use HTTP instead of HTTPS?

  • Windows / macOS / Linux: Yes.
  • Android: Add android:usesCleartextTraffic="true" to AndroidManifest.xml.
  • iOS: Add an ATS exception in Info.plist.

Does it play videos?

Yes — depends on the platform webview engine. See Compatibility Matrix for codec details.

Can I intercept/block specific URLs?

Not directly. Options:

  1. Monitor UrlChanged and call GoBack() for blocked URLs
  2. Inject JavaScript to intercept link clicks

How do I inject CSS? 

_browser.WebView.EvaluateJavaScript(@"
    var style = document.createElement('style');
    style.textContent = 'body { background: #1a1a2e !important; }';
    document.head.appendChild(style);
");

What’s the performance impact?

  • CPU: Texture capture (PrintWindow) capped at 30 FPS
  • Memory: One Texture2D at screen resolution (~8 MB for 1920x1080 RGBA)
  • GPU: Minimal — single RawImage blit
  • Bridge: Negligible JSON serialization overhead

Can I use the new Input System?

The plugin uses legacy Input. Enable both Input Systems in Player Settings (Active Input Handling → Both).

How do I handle errors? 

_browser.WebView.ErrorOccurred += (message, code) =>
{
    Debug.LogError($"WebView error ({code}): {message}");
};

Debug Checklist

If something isn’t working, check in order:

  1. Console errors — Look for [LWB] prefixed messages
  2. DLL loading — Check for DllNotFoundException
  3. WebView2 — Verify Edge Chromium is installed (Windows)
  4. HTTPS — Ensure you’re using HTTPS URLs
  5. Bridge enabled — Confirm the checkbox in Inspector
  6. Debug overlay — Toggle with F12 to see live traffic
  7. Remote debugger — Use Edge/Safari/Chrome DevTools
  8. Native rebuild — Ensure Unity loaded the latest DLL