@capgo/capacitor-inappbrowser 8.7.0 → 8.7.2-beta.pr599.357.1

package/README.md

@@ -25,10 +25,12 @@ The official Capacitor Browser plugin has strict security limitations that preve
 - **Camera and microphone access** within the browser context
 - **URL change monitoring** for navigation tracking
 - **Custom toolbars and UI** for branded experiences
-- **Cookie and cache management** for session control
-- **Custom sizes** for extra control of the display position
+- **Native browser layering** behind Ionic or Capacitor UI with input forwarding
+- **Partial-screen WebViews** with click-through areas outside the browser frame
+- **Cookie, cache, and full browsing-data controls** for private or isolated sessions
+- **Native proxy, download, and popup handling** for advanced embedded web apps
 
-Perfect for OAuth flows, embedded web apps, video calls, and any scenario requiring deep integration with web content.
+Perfect for OAuth flows, embedded web apps, checkout screens, browser-backed payment flows, video calls, support portals, and apps that need native UI around live web content.
 
 ## Documentation
 
@@ -74,6 +76,82 @@ import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
 InAppBrowser.open({ url: 'YOUR_URL' });
 ```
 
+### Common use cases
+
+#### Show Ionic UI over a live browser page
+
+Use `toBack` when the native browser should stay visible behind your Ionic or Capacitor UI. This is useful for checkout overlays, payment confirmation panels, guided browser flows, or any flow where your app owns the controls while the web page remains loaded behind it.
+
+```js
+import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
+
+const { id } = await InAppBrowser.openWebView({
+  url: 'https://example.com/checkout',
+  toBack: true,
+  transparentBackground: true,
+});
+
+// If your overlay needs to interact with the page behind it, forward the gesture.
+await InAppBrowser.dispatchInputEvent({
+  id,
+  type: 'click',
+  x: 160,
+  y: 420,
+});
+
+// Bring the browser back above the app when the native overlay is done.
+await InAppBrowser.bringToFront({ id });
+```
+
+Make the app background transparent wherever the browser should be visible. `dispatchInputEvent()` supports click, touch, and scroll forwarding; coordinates are relative to the browser viewport.
+
+#### Build a partial-screen browser or bottom sheet
+
+Use `height`, `width`, `x`, and `y` for picture-in-picture views, browser sheets, or layouts where the user should keep interacting with the Ionic app around the browser. When the WebView does not cover the full screen, touches outside the browser frame pass through to the underlying Capacitor WebView on Android and iOS.
+
+```js
+const bottomGap = 200;
+
+const { id } = await InAppBrowser.openWebView({
+  url: 'https://example.com/offers',
+  height: window.innerHeight - bottomGap,
+  y: 0,
+});
+```
+
+Use `updateDimensions()` to resize the browser while keeping the same page state, for example when expanding a mini browser into a larger sheet.
+
+#### Keep checkout, auth, or support sessions private
+
+Use `persistWebViewData: false` when a WebView must avoid persistent cookies, cache, local storage, IndexedDB, and other website data where the platform supports it. Use `clearAllBrowsingData()` when the app needs to wipe the default store and all opened managed WebViews.
+
+```js
+const { id } = await InAppBrowser.openWebView({
+  url: 'https://example.com/login',
+  persistWebViewData: false,
+});
+
+// Later, after logout or account switching:
+await InAppBrowser.clearAllBrowsingData();
+```
+
+#### Keep multiple browser instances ready
+
+Use `hidden`, `hide()`, and `show()` when you need to preload or preserve several WebViews without keeping them on screen. This keeps browser state available while the native modal is dismissed so it does not block touches in the app.
+
+```js
+const first = await InAppBrowser.openWebView({ url: 'https://example.com/a', hidden: true });
+const second = await InAppBrowser.openWebView({ url: 'https://example.com/b', hidden: true });
+
+await InAppBrowser.show({ id: first.id });
+await InAppBrowser.hide({ id: first.id });
+await InAppBrowser.show({ id: second.id });
+```
+
+#### Embed advanced web app flows
+
+Use proxy rules and `handleDownloads` for web apps that need request control, file uploads, downloads, or controlled popup behavior inside the managed browser. Typical examples include document portals, support desks, payment pages, Google Pay flows on Android, and apps that need to keep `_blank` links inside the same managed WebView.
+
 ### Customize Chrome Custom Tab Appearance (Android)
 
 The `open()` method launches a Chrome Custom Tab on Android. You can customize its appearance to blend with your app:

package/android/src/main/java/ee/forgr/capacitor_inappbrowser/SafeAreaInsetsSupport.java

@@ -26,19 +26,32 @@ final class SafeAreaInsetsSupport {
         boolean applyFallbackWhenZero
     ) {
         int inset = resolveSafeBottomInset(systemBarsBottom, navigationBarsBottom, systemGesturesBottom, mandatoryGesturesBottom);
-        if (inset > 0 || !applyFallbackWhenZero || fallbackBottomInset <= 0) {
+        if (!applyFallbackWhenZero || fallbackBottomInset <= 0) {
             return inset;
         }
 
-        if (hasSideNavigationBarInsets(systemBarsLeft, systemBarsRight, navigationBarsLeft, navigationBarsRight)) {
-            return 0;
+        if (hasSideNavigationBarInsets(systemBarsLeft, systemBarsRight, navigationBarsLeft, navigationBarsRight, fallbackBottomInset)) {
+            return inset;
         }
 
-        return fallbackBottomInset;
+        return Math.max(inset, fallbackBottomInset);
     }
 
-    static boolean hasSideNavigationBarInsets(int systemBarsLeft, int systemBarsRight, int navigationBarsLeft, int navigationBarsRight) {
-        return systemBarsLeft > 0 || systemBarsRight > 0 || navigationBarsLeft > 0 || navigationBarsRight > 0;
+    static boolean hasSideNavigationBarInsets(
+        int systemBarsLeft,
+        int systemBarsRight,
+        int navigationBarsLeft,
+        int navigationBarsRight,
+        int minSideNavBarInset
+    ) {
+        if (minSideNavBarInset <= 0) {
+            return false;
+        }
+
+        return (
+            Math.max(systemBarsLeft, navigationBarsLeft) >= minSideNavBarInset ||
+            Math.max(systemBarsRight, navigationBarsRight) >= minSideNavBarInset
+        );
     }
 
     static int resolveBottomMargin(boolean enabledSafeBottomMargin, int safeBottomInset, int imeBottom) {

package/ios/Sources/InAppBrowserPlugin/InAppBrowserPlugin.swift

@@ -98,7 +98,7 @@ public class CapgoInAppBrowserPlugin: CAPPlugin, CAPBridgedPlugin {
         case aware = "AWARE"
         case fakeVisible = "FAKE_VISIBLE"
     }
-    private let pluginVersion: String = "8.7.0"
+    private let pluginVersion: String = "8.7.2"
     public let identifier = "CapgoInAppBrowserPlugin"
     public let jsName = "CapgoInAppBrowser"
     public let pluginMethods: [CAPPluginMethod] = [
@@ -190,11 +190,16 @@ public class CapgoInAppBrowserPlugin: CAPPlugin, CAPBridgedPlugin {
         }
     }
 
-    private func dismissNavigationControllerIfPresented(_ navigationController: UINavigationController?) {
-        guard let navigationController, navigationController.presentingViewController != nil else {
+    private func dismissNavigationControllerIfPresented(_ navigationController: UINavigationController?, completion: (() -> Void)? = nil) {
+        guard let navigationController else {
+            completion?()
+            return
+        }
+        guard navigationController.presentingViewController != nil else {
+            completion?()
             return
         }
-        navigationController.dismiss(animated: false)
+        navigationController.dismiss(animated: false, completion: completion)
     }
 
     private func unregisterWebView(id: String) {
@@ -446,7 +451,6 @@ public class CapgoInAppBrowserPlugin: CAPPlugin, CAPBridgedPlugin {
         }
 
         dismissActiveKeyboard()
-        dismissNavigationControllerIfPresented(navigationController)
         navigationController.view.removeFromSuperview()
         if transparentBackground {
             makeHostWebViewTransparent(for: id)
@@ -1378,6 +1382,7 @@ public class CapgoInAppBrowserPlugin: CAPPlugin, CAPBridgedPlugin {
                 containerView.backgroundColor = .clear
                 containerView.frame = UIScreen.main.bounds
                 containerView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+                containerView.passthroughView = self.bridge?.webView
 
                 let targetFrame = CustomWebViewFrameSupport.resolvedFrame(
                     width: width.map { CGFloat($0) },
@@ -1602,14 +1607,16 @@ public class CapgoInAppBrowserPlugin: CAPPlugin, CAPBridgedPlugin {
             }
 
             let transparentBackground = call.getBool("transparentBackground", true)
-            webViewController.isLayeredBehind = true
-            webViewController.transparentHostBackground = transparentBackground
-            guard self.sendNavigationControllerToBack(id: resolvedId, transparentBackground: transparentBackground) else {
-                call.reject("Failed to send webview to back")
-                return
+            self.dismissNavigationControllerIfPresented(navigationController) {
+                webViewController.isLayeredBehind = true
+                webViewController.transparentHostBackground = transparentBackground
+                guard self.sendNavigationControllerToBack(id: resolvedId, transparentBackground: transparentBackground) else {
+                    call.reject("Failed to send webview to back")
+                    return
+                }
+                self.setActiveWebView(id: resolvedId, webView: webViewController, navigationController: navigationController)
+                call.resolve()
             }
-            self.setActiveWebView(id: resolvedId, webView: webViewController, navigationController: navigationController)
-            call.resolve()
         }
     }
 

package/ios/Sources/InAppBrowserPlugin/WKWebViewController.swift

@@ -756,40 +756,62 @@ open class WKWebViewController: UIViewController, WKScriptMessageHandler {
         return windowScene?.statusBarManager?.statusBarFrame.height ?? 0
     }
 
-    // Make status bar background with colored view underneath
-    open func setupStatusBarBackground(color: UIColor) {
-        // Remove any existing status bar view
-        statusBarBackgroundView?.removeFromSuperview()
+    private func applyNavigationBarBackground(color: UIColor) {
+        guard let navigationBar = navigationController?.navigationBar else {
+            return
+        }
 
-        // Create a new view to cover both status bar and navigation bar
-        statusBarBackgroundView = UIView()
+        navigationBar.backgroundColor = color
+        navigationBar.barTintColor = color
+        navigationBar.isTranslucent = false
+        navigationBar.setBackgroundImage(UIImage(), for: .default)
+        navigationBar.shadowImage = UIImage()
+        navigationBar.setValue(true, forKey: "hidesShadow")
 
-        if let navView = navigationController?.view {
-            // Add to back of view hierarchy
-            navView.insertSubview(statusBarBackgroundView!, at: 0)
-            statusBarBackgroundView?.translatesAutoresizingMaskIntoConstraints = false
+        if #available(iOS 13.0, *) {
+            let appearance = UINavigationBarAppearance()
+            appearance.configureWithOpaqueBackground()
+            appearance.backgroundColor = color
+            appearance.backgroundEffect = nil
+            appearance.shadowColor = .clear
+            appearance.shadowImage = UIImage()
 
-            // Calculate total height - status bar + navigation bar
-            let navBarHeight = navigationController?.navigationBar.frame.height ?? 44
-            let totalHeight = (navigationController?.view.safeAreaInsets.top ?? CGFloat(0)) + navBarHeight
+            if let titleTextAttributes = navigationBar.titleTextAttributes {
+                appearance.titleTextAttributes = titleTextAttributes
+            }
+            if let largeTitleTextAttributes = navigationBar.largeTitleTextAttributes {
+                appearance.largeTitleTextAttributes = largeTitleTextAttributes
+            }
 
-            // Position from top of screen to bottom of navigation bar
-            NSLayoutConstraint.activate([
-                statusBarBackgroundView!.topAnchor.constraint(equalTo: navView.topAnchor),
-                statusBarBackgroundView!.leadingAnchor.constraint(equalTo: navView.leadingAnchor),
-                statusBarBackgroundView!.trailingAnchor.constraint(equalTo: navView.trailingAnchor),
-                statusBarBackgroundView!.heightAnchor.constraint(equalToConstant: totalHeight)
-            ])
+            navigationBar.standardAppearance = appearance
+            navigationBar.compactAppearance = appearance
+            navigationBar.scrollEdgeAppearance = appearance
+            navigationBar.compactScrollEdgeAppearance = appearance
+        }
+    }
 
-            // Set background color
-            statusBarBackgroundView?.backgroundColor = color
+    // Make status bar background with colored view underneath
+    open func setupStatusBarBackground(color: UIColor) {
+        statusBarBackgroundView?.removeFromSuperview()
+        statusBarBackgroundView = UIView()
 
-            // Make navigation bar transparent to show our view underneath
-            navigationController?.navigationBar.setBackgroundImage(UIImage(), for: .default)
-            navigationController?.navigationBar.shadowImage = UIImage()
-            navigationController?.navigationBar.isTranslucent = true
-            navigationController?.navigationBar.isTranslucent = true
+        guard let navController = navigationController,
+              let navView = navController.view,
+              let statusBarBackgroundView else {
+            return
         }
+        navView.insertSubview(statusBarBackgroundView, at: 0)
+        statusBarBackgroundView.translatesAutoresizingMaskIntoConstraints = false
+        statusBarBackgroundView.backgroundColor = color
+
+        NSLayoutConstraint.activate([
+            statusBarBackgroundView.topAnchor.constraint(equalTo: navView.topAnchor),
+            statusBarBackgroundView.leadingAnchor.constraint(equalTo: navView.leadingAnchor),
+            statusBarBackgroundView.trailingAnchor.constraint(equalTo: navView.trailingAnchor),
+            statusBarBackgroundView.bottomAnchor.constraint(equalTo: navController.navigationBar.bottomAnchor, constant: 1)
+        ])
+
+        applyNavigationBarBackground(color: color)
     }
 
     // Override to use our custom status bar style
@@ -3244,6 +3266,7 @@ class PassThroughView: UIView {
         }
     }
     weak var framedContentView: UIView?
+    weak var passthroughView: UIView?
 
     override func layoutSubviews() {
         super.layoutSubviews()
@@ -3256,14 +3279,14 @@ class PassThroughView: UIView {
     }
 
     override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
-        // If we have a target frame and the touch is outside it, pass through
-        if let frame = targetFrame {
-            if !frame.contains(point) {
-                return nil  // Pass through to underlying views
+        if let frame = targetFrame, !frame.contains(point) {
+            guard let passthroughView else {
+                return nil
             }
+            let convertedPoint = convert(point, to: passthroughView)
+            return passthroughView.hitTest(convertedPoint, with: event)
         }
 
-        // Otherwise, handle normally
         return super.hitTest(point, with: event)
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capgo/capacitor-inappbrowser",
-  "version": "8.7.0",
+  "version": "8.7.2-beta.pr599.357.1",
   "description": "Capacitor plugin in app browser",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",