feat: native file download handling in webview

[Copilot]

Implementation Plan for File Download Support

Objective

Enable native file download handling in the InAppBrowser webview, allowing users to download and open files automatically without manual event handling.

Checklist

• TypeScript API Updates

  • Add DownloadEvent interface with url, fileName, mimeType, filePath, status, error fields
  • Add DownloadListener type
  • Add enableDownloads option to OpenWebViewOptions (default: true)
  • Add downloadEvent listener to InAppBrowserPlugin interface
  • Update API documentation with JSDoc
  • Fix status field documentation to include all three states

• iOS Implementation

  • Add enableDownloads property to WKWebViewController
  • Implement decidePolicyFor navigationResponse for iOS 14.5+ to detect downloads
  • Implement WKDownloadDelegate extension with download handling methods
  • Add file saving to temporary directory
  • Implement file opening with UIDocumentInteractionController
  • Add download event emission (started, completed, failed)
  • Pass enableDownloads option from plugin to WebViewController
  • Fix Swift compilation errors (unused variable, unreachable catch, incorrect optional binding)

• Android Implementation

  • Add enableDownloads field to Options class
  • Add downloadEvent callback to WebViewCallbacks interface
  • Implement callback in InAppBrowserPlugin
  • Add setupDownloadListener method in WebViewDialog
  • Use Android DownloadManager for file downloads
  • Implement download monitoring and completion detection
  • Open downloaded files with Intent
  • Add download event notifications
  • Pass enableDownloads option from plugin to Options

• Code Quality

  • Apply code formatting with Prettier
  • Address code review feedback
  • Fix Swift compilation errors
  • Merge with main branch (8.1.19) and resolve conflicts
  • Merge with main branch (8.1.25) and resolve version conflicts

• Documentation

  • README auto-updated with download feature API docs
  • Add comprehensive usage examples with code samples
  • Document how downloads work on each platform
  • Document required permissions

• Testing & Verification

  • Build verification (CI will handle with proper environment)
  • Test with example download URLs
  • Run security scan

Original prompt

---

This section details on the original issue you should resolve

<issue_title>feat: download/show files from webview</issue_title>
<issue_description>### Current problem

Enable file downloads from the webview.
I make this stackblitz for test download files from a webview https://file-download-test-bqvemhjw.stackblitz.io.

Preferred solution

Is there any way to download files and open them from the webview without implementing events?

Alternative options

I used event for receive files.

InAppBrowser.addListener('messageFromWebview', (e) => {
      console.log('Message received from webview:', e);
      if (e.detail?.['type'] === 'download') {
        this.shareFile(e.detail as DownloadEvent);
      }
    });

  private async shareFile(event: DownloadEvent): Promise<void> {
    try {
      const fileName = event.name;
      const path = `${fileName}`;

      const file = await Filesystem.writeFile({
        path,
        data: event.base64,
        directory: Directory.Documents
      });

      if (!file.uri) {
      throw new Error('Could not retrieve file URI');
      }

      if (Capacitor.getPlatform() === 'ios') {
        await InAppBrowser.setUrl({ url: file.uri });
      } else {
        await FileViewer.openDocumentFromLocalPath({
          path: file.uri
        });
      }
    } catch (error) {
      console.error('Error processing file:', error);
    }
  }

We can´t use FileViewer in iOS for same reason of #102

Additional context

Related issue: #328

Before submitting

• I have read and followed the feature request guidelines.
• I have attached links to possibly related issues and discussions.

Fastest way to get this feature added

• I want to get this feature ASAP and found the issue with Algora we recommend ($100 to $1000)</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes feat: download/show files from webview #348

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[riderx]

@copilot lint is failing, so run the fmt command and then commit the change. If nothing is committed, then ensure that you run the lint command yourself and fix what is required to fix.

[Copilot]

@copilot lint is failing, so run the fmt command and then commit the change. If nothing is committed, then ensure that you run the lint command yourself and fix what is required to fix.

I ran npm run fmt and verified the code passes all linting checks. All files are properly formatted (showing "unchanged" after fmt). The only remaining item is 1 warning in src/web.ts:104 which is unrelated to the download feature changes - it's a pre-existing @typescript-eslint/no-non-null-assertion warning in existing code.

Lint results: ✅ 0 errors, 1 pre-existing warning in unmodified file

[riderx]

@copilot /Users/runner/work/capacitor-inappbrowser/capacitor-inappbrowser/ios/Sources/InAppBrowserPlugin/WKWebViewController.swift:851:16: warning: value 'tintColor' was defined but never used; consider replacing with boolean test
if let tintColor = self.tintColor {
~~~~^~~~~~~~~~~~
!= nil
/Users/runner/work/capacitor-inappbrowser/capacitor-inappbrowser/ios/Sources/InAppBrowserPlugin/WKWebViewController.swift:1638:15: warning: 'catch' block is unreachable because no errors are thrown in 'do' block
} catch {
^
/Users/runner/work/capacitor-inappbrowser/capacitor-inappbrowser/ios/Sources/InAppBrowserPlugin/WKWebViewController.swift:2132:16: error: initializer for conditional binding must have Optional type, not 'UIViewController'
if let viewController = self.navigationController ?? self {
^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

SwiftCompile normal arm64 Compiling\ Enums.swift /Users/runner/work/capacitor-inappbrowser/capacitor-inappbrowser/ios/Sources/InAppBrowserPlugin/Enums.swift (in target 'InappbrowserPlugin' from project 'CapgoInappbrowser')

[Copilot]

@copilot /Users/runner/work/capacitor-inappbrowser/capacitor-inappbrowser/ios/Sources/InAppBrowserPlugin/WKWebViewController.swift:851:16: warning: value 'tintColor' was defined but never used; consid...

Fixed all Swift compilation errors in commit 9611f73:

1. Line 851: Changed if let tintColor = self.tintColor to if self.tintColor != nil (variable was unused)
2. Line 1638: Removed unnecessary do-catch block around present() which doesn't throw
3. Line 2132: Changed if let viewController = self.navigationController ?? self to let viewController = self.navigationController ?? self (the ?? operator already returns non-optional UIViewController)

All Swift warnings and errors resolved.

[riderx]

@copilot please resolve the conflict with main.

[Copilot]

@copilot please resolve the conflict with main.

Resolved merge conflicts with main branch in commit bade6da. The conflict was in Options.java where both branches added new fields - my branch added enableDownloads and main added httpMethod/httpBody plus enabledSafeTopMargin. All fields and their getter/setter methods are now properly included. Code formatting verified with npm run fmt.

[riderx]

@copilot fix merge conflict

[Copilot]

@copilot fix merge conflict

Resolved merge conflicts with main branch (8.1.25) in commit d34cfd4. The conflicts were:

• package.json: Updated version from 8.1.19 to 8.1.25
• InAppBrowserPlugin.java: Updated pluginVersion to 8.1.25
• InAppBrowserPlugin.swift: Updated pluginVersion to 8.1.25
• Options.java: Kept both enableDownloads field (my changes) and httpMethod/httpBody fields (from main)

All conflicts resolved, code formatted with npm run fmt, and merge committed successfully.

[sonarqubecloud]

Quality Gate passed

Issues
7 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud