Introduce blob handling for Android & iOS #8202

riderx · 2025-10-29T07:41:54Z

Summary

This PR introduces blob handling for Android & iOS webviews, based on the work from PR #5498 and updated to work with the latest main branch.

Whenever a blob:/ URL or normal download is requested to be 'opened', a folder selection is prompted and the file is saved.

This addresses issue #5478

Features

Base64 blobs through blob:data... scheme - Handles both known and unknown mime-types
- Both Android and iOS were opening images (like PNG) in the internal browser, causing users to be stuck on the image requiring manual app closure
Blob links through blob:http... scheme
Web worker initiated downloads - Partially addressed (browser core limitations may apply)

Implementation Details

iOS

Works on iOS 14.5+ (WebKit exposed necessary APIs starting from this version)
When a download request is received, prompts for folder selection and saves the file with a unique filename
Includes compiler guards for Xcode 12 compatibility

Android

Implements JS interface that injects JS code to download the received URL through XHR
Uses the JS accessible context to pipe content in chunks to an Intent for file selection
Implements duplex stream for piping received content to file

Common

Both platforms ask users for destination selection
Implement download notifications to be consumed by App plugin
Applications can decide what to do with notifications (show alert, display in list, etc.)

Test Cases

Test cases are available at: https://github.com/ikon-integration/Capacitor-Blob-Download-Issue

Changes from original PR #5498

Resolved all merge conflicts with current main branch
Maintained compatibility with existing code structure
Preserved all bug fixes and improvements from the original PR

…issing headers)), add notifications at app level for file download statuses and path

…ook initiated downloads for now (stream))

…le picker and duplex stream for javascript proxy write

…n implementation)

Copilot

Pull request overview

Adds first-party blob/download handling for Capacitor webviews on iOS and Android, prompting users to choose a destination and emitting download status updates for app/plugin consumption.

Changes:

iOS: route eligible navigation actions/responses into WKDownload, prompt for a destination folder, and post download lifecycle notifications.
Android: add a WebView download listener + JS interface that XHR-fetches blob:/HTTP(S) resources and streams them to a user-selected document via SAF.
Android/iOS: introduce download status notification primitives (Android via App callbacks; iOS via NotificationCenter).

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 19 comments.

Show a summary per file

File	Description
ios/Capacitor/Capacitor/WebViewDelegationHandler.swift	Adds `WKDownload` handling + document picker destination selection + notification posts.
ios/Capacitor/Capacitor/CAPNotifications.swift	Adds a new download update notification name + status enum.
android/capacitor/src/main/java/com/getcapacitor/DownloadJSProxy.java	New proxy implementing `DownloadListener` and optional blob override + service worker interception.
android/capacitor/src/main/java/com/getcapacitor/DownloadJSOperationController.java	New ActivityResultContract that creates the SAF file, manages piped streams, and writes downloaded content.
android/capacitor/src/main/java/com/getcapacitor/DownloadJSInterface.java	New JS interface + injector for chunking XHR blob/HTTP downloads into native streaming writes.
android/capacitor/src/main/java/com/getcapacitor/Bridge.java	Wires the download proxy into the WebView (JS interface + download listener) and blob interception.
android/capacitor/src/main/java/com/getcapacitor/App.java	Adds download status callback API (`AppDownloadListener`).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-10T02:19:40Z

android/capacitor/src/main/java/com/getcapacitor/DownloadJSInterface.java

+    @JavascriptInterface
+    public void receiveStreamErrorFromJavascript(String error, String operationID) {
+        //Guarantee pending input transition to 'started-but-stale' operation before actually failing
+        this.transitionPendingInputOperation(operationID, null, true);
+        //Fail operation signal
+        if (!this.operationsController.failOperation(operationID)) return;
+        //Notify
+        this.bridge.getApp().fireDownloadUpdate(operationID, App.DownloadStatus.FAILED, error);
+    }


receiveStreamErrorFromJavascript calls transitionPendingInputOperation(..., doNotStart=true), which removes the pending input but still fires a STARTED update and (because the operation was never launched) failOperation will typically return false, preventing a FAILED notification. The error path should either start the operation before failing, or avoid firing STARTED when doNotStart is true and ensure FAILED is still emitted/cleaned up.

Copilot · 2026-02-10T02:19:40Z

android/capacitor/src/main/java/com/getcapacitor/DownloadJSOperationController.java

+            this.operations.put(operation.input.operationID, operation);
+            this.pendingOperation = null;
+            this.createThreadedPipeForOperation(operation, result.getData());


parseResult passes result.getData() directly into the pipe setup without checking for null. ACTION_CREATE_DOCUMENT can return RESULT_OK with a null data Uri on some OEMs/flows; guard against null and treat it as a failure/cancel to avoid a crash later.

Suggested change

this.operations.put(operation.input.operationID, operation);

this.pendingOperation = null;

this.createThreadedPipeForOperation(operation, result.getData());

Uri uri = result.getData();

if (uri == null) {

// Treat null Uri as a failure/cancel to avoid crashes

this.pendingOperation = null; // can't be used for writing anymore

this.cancelPreOperation(operation);

return false;

}

this.operations.put(operation.input.operationID, operation);

this.pendingOperation = null;

this.createThreadedPipeForOperation(operation, uri);

Copilot · 2026-02-10T02:19:40Z

android/capacitor/src/main/java/com/getcapacitor/DownloadJSInterface.java

+        if (doNotStart == null || !doNotStart) this.launcher.launch(input);
+        //Notify
+        this.bridge.getApp().fireDownloadUpdate(operationID, App.DownloadStatus.STARTED, null);


transitionPendingInputOperation calls ActivityResultLauncher.launch(...) directly. Since @JavascriptInterface methods may be invoked off the main thread, launching an activity from here can crash (CalledFromWrongThreadException) or behave inconsistently. Consider wrapping launcher.launch(input) (and the fireDownloadUpdate callback) in bridge.getActivity().runOnUiThread(...) (or activity.runOnUiThread) to ensure it executes on the UI thread.

Suggested change

if (doNotStart == null || !doNotStart) this.launcher.launch(input);

//Notify

this.bridge.getApp().fireDownloadUpdate(operationID, App.DownloadStatus.STARTED, null);

final boolean shouldStart = (doNotStart == null || !doNotStart);

bridge

.getActivity()

.runOnUiThread(

() -> {

if (shouldStart) {

launcher.launch(input);

}

//Notify

bridge.getApp().fireDownloadUpdate(operationID, App.DownloadStatus.STARTED, null);

}

);

Copilot · 2026-02-10T02:19:41Z

android/capacitor/src/main/java/com/getcapacitor/DownloadJSProxy.java

+    private void installServiceWorkerProxy() {
+        //Downloads can be done via webworker, webworkers might need local resources, we enable that
+        if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.N) {
+            ServiceWorkerController swController = ServiceWorkerController.getInstance();
+            swController.setServiceWorkerClient(
+                new ServiceWorkerClient() {
+                    @Override
+                    public WebResourceResponse shouldInterceptRequest(WebResourceRequest request) {
+                        Logger.debug("ServiceWorker Request", request.getUrl().toString());
+                        return bridge.getLocalServer().shouldInterceptRequest(request);
+                    }
+                }
+            );


installServiceWorkerProxy() unconditionally calls ServiceWorkerController.setServiceWorkerClient(...), which overrides Bridge's existing service worker handling (and ignores config.isResolveServiceWorkerRequests()). This can break existing service worker interception behavior and may also run before localServer is initialized, causing a null dereference when bridge.getLocalServer() is used. Consider removing this override and relying on Bridge's existing config.isResolveServiceWorkerRequests() logic, or integrate with it so only one client is installed and it is safe when localServer is null.

Copilot · 2026-02-10T02:19:41Z

android/capacitor/src/main/java/com/getcapacitor/DownloadJSOperationController.java

+                //Read
+                byte[] bytes = new byte[lastReadSize];
+                lastReadSize = operation.inStream.read(bytes, 0, lastReadSize);
+                output.write(bytes);


output.write(bytes) writes the full buffer, even if inStream.read(...) returns fewer bytes than requested. This can corrupt the downloaded file by appending zero-padding/garbage. Use the actual byte count returned from read(...) (and handle -1) when writing to the output stream.

Suggested change

output.write(bytes);

if (lastReadSize == -1) {

// End of stream; treat as no more data available

lastReadSize = 0;

continue;

}

output.write(bytes, 0, lastReadSize);

Copilot · 2026-02-10T02:19:43Z

ios/Capacitor/Capacitor/WebViewDelegationHandler.swift

+    func documentPicker(_ controller: UIDocumentPickerViewController, didPickDocumentAt url: URL) {
+        if let pendingDownload = self.pendingDownload {
+            // Generate unique file name on the choosen directory
+            let fileName: URL = self.getUniqueDownloadFileURL(url, suggestedFilename: pendingDownload.proposedFileName, optionalSuffix: nil)
+            pendingDownload.pathSelectionCallback(fileName)
+            // Notify


UIDocumentPickerDelegate on iOS 11+ primarily uses documentPicker(_:didPickDocumentsAt:). Implementing only the deprecated documentPicker(_:didPickDocumentAt:) risks never receiving the callback on modern iOS versions (which would leave the download’s completionHandler uncalled). Implement didPickDocumentsAt and forward the first URL to the existing logic.

Copilot · 2026-02-10T02:19:43Z

ios/Capacitor/Capacitor/WebViewDelegationHandler.swift

+import MobileCoreServices
+
+// TODO: remove once Xcode 12 support is dropped
+#if compiler(<5.5)
+    protocol WKDownloadDelegate {}
+#endif


MobileCoreServices is deprecated; for iOS 14+ the preferred API is UniformTypeIdentifiers (UTType.folder) with UIDocumentPickerViewController(forOpeningContentTypes:). If Xcode 12 support is still needed, consider conditional compilation so newer toolchains use UTType and only older compilers fall back to kUTTypeFolder.

Copilot · 2026-02-10T02:19:44Z

android/capacitor/src/main/java/com/getcapacitor/DownloadJSOperationController.java

+    private void createThreadedPipeForOperation(Operation operation, Uri uri) {
+        DownloadJSOperationController upperRef = this;
+        Executors.newSingleThreadExecutor().execute(() -> upperRef.createPipeForOperation(operation, uri));
+    }


createThreadedPipeForOperation creates a new Executors.newSingleThreadExecutor() per download and never shuts it down, which can leak threads over time if multiple downloads occur. Prefer a shared executor (e.g., a single cached/thread pool owned by the controller) and shut it down appropriately.

Copilot · 2026-02-10T02:19:44Z

android/capacitor/src/main/java/com/getcapacitor/DownloadJSOperationController.java

+        return intent;
+    }
+
+    public Boolean parseResult(int resultCode, @Nullable Intent result) {


This method overrides ActivityResultContract<Input,Boolean>.parseResult; it is advisable to add an Override annotation.

Copilot · 2026-02-10T02:19:44Z

android/capacitor/src/main/java/com/getcapacitor/DownloadJSOperationController.java

+        return true;
+    }
+
+    /* ActivityResultContract Implementation */


This method overrides ActivityResultContract<Input,Boolean>.createIntent; it is advisable to add an Override annotation.

Suggested change

/* ActivityResultContract Implementation */

/* ActivityResultContract Implementation */

@Override

gwdp and others added 15 commits October 29, 2025 07:36

Improved solution for iOS 14.5 >=

76500c3

Improvements to file writting (avoid collision and empty file name (m…

a2b9de2

…issing headers)), add notifications at app level for file download statuses and path

Android code working with encoding and mime type issues (also no webh…

a2de621

…ook initiated downloads for now (stream))

More changes relative to android download, implement activity with fi…

f353ddf

…le picker and duplex stream for javascript proxy write

Working thread operation with content type resolution from XHR

79cd81e

Intercept known chrome mimetype blobs and spawn same download process

1f01c45

Fix mime type issue and copy to capacitor

b2ef3b5

Tweaks on android + add notification to application (yet, needs plugi…

e71a8d2

…n implementation)

Improve handler to also download common mime type blobs

93efbff

Add folder picker for iOS

b9ffb6d

Fix Swiftlint warnings

e6afdc1

Fix Java ESlint

efe51b6

Fix compiler errors after fixes on swift lint

a6ba8b9

Fix compile errors on Xcode 12.4 and bellow

c4e53ad

Merge branch 'main' into blob-handling-update

7020e28

Copilot AI review requested due to automatic review settings February 10, 2026 02:09

Copilot started reviewing on behalf of riderx February 10, 2026 02:10 View session

Copilot AI reviewed Feb 10, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Introduce blob handling for Android & iOS #8202

Introduce blob handling for Android & iOS #8202

riderx commented Oct 29, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 10, 2026

Uh oh!

Copilot AI Feb 10, 2026

Uh oh!

Copilot AI Feb 10, 2026

Uh oh!

Copilot AI Feb 10, 2026

Uh oh!

Copilot AI Feb 10, 2026

Uh oh!

Copilot AI Feb 10, 2026

Uh oh!

Copilot AI Feb 10, 2026

Uh oh!

Copilot AI Feb 10, 2026

Uh oh!

Copilot AI Feb 10, 2026

Uh oh!

Copilot AI Feb 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

-            this.operations.put(operation.input.operationID, operation);
-            this.pendingOperation = null;
-            this.createThreadedPipeForOperation(operation, result.getData());
+            Uri uri = result.getData();
+            if (uri == null) {
+                // Treat null Uri as a failure/cancel to avoid crashes
+                this.pendingOperation = null; // can't be used for writing anymore
+                this.cancelPreOperation(operation);
+                return false;
+            }
+            this.operations.put(operation.input.operationID, operation);
+            this.pendingOperation = null;
+            this.createThreadedPipeForOperation(operation, uri);

-                output.write(bytes);
+                if (lastReadSize == -1) {
+                    // End of stream; treat as no more data available
+                    lastReadSize = 0;
+                    continue;
+                }
+                output.write(bytes, 0, lastReadSize);

	/* ActivityResultContract Implementation */
	/* ActivityResultContract Implementation */
	@Override

Introduce blob handling for Android & iOS #8202

Are you sure you want to change the base?

Introduce blob handling for Android & iOS #8202

Conversation

riderx commented Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Features

Implementation Details

Test Cases

Changes from original PR #5498

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

riderx commented Oct 29, 2025 •

edited

Loading