Introduce blob handling for Android & iOS by riderx · Pull Request #8202 · ionic-team/capacitor

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

+    @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.

Fixed: errors no longer launch the picker or emit STARTED. receiveStreamErrorFromJavascript drops the pending input and fires FAILED.

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

+            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);

Fixed: parseResult now treats a null data Uri as cancel/failure.

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

+        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);

}

);

Fixed: launcher.launch and the STARTED notification now run on the UI thread.

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

+    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.

Removed the ServiceWorkerClient override. Bridge already installs one when config.isResolveServiceWorkerRequests() is true.

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

+                //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);

Fixed: the pipe now uses a blocking read and writes only lastReadSize bytes. Filename split uses \\.. Null pendingOperation / OutputStream are guarded. Shared cached executor replaces per-download executors. @Override added on createIntent/parseResult. EXTRA_INITIAL_URI is no longer set from a filesystem path.

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

+    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.

Fixed: implemented documentPicker(_:didPickDocumentsAt:) and switched newer toolchains to UTType.folder. Download status is posted as FileDownloadNotificationStatus Int raw values.

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

+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

+    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

+        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

+        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

riderx · 2026-03-27T04:08:04Z

@copilot fix all comments and resolve them

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

Merge branch 'main' into blob-handling-update

6c04ea9

riderx and others added 6 commits August 26, 2026 17:29

Merge branch 'main' into blob-handling-update

74f9323

fix: stop overriding Bridge service worker handling in download proxy

55443c4

fix: address remaining blob-download review comments

f44fcd5

fix: post download status as Int raw values for ObjC consumers

13bc703

fix: address remaining blob-download review comments

2759939

fix: address remaining blob-download review comments

60a593d

TorichanCapgo mentioned this pull request Aug 26, 2026

feat: Bidirectional Blob Transfer API for Efficient Binary Data Transfer #8203

Open

-            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

Uh oh!

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!

TorichanCapgo Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

TorichanCapgo Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

TorichanCapgo Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

TorichanCapgo Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

TorichanCapgo Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

TorichanCapgo Aug 26, 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!

riderx commented Mar 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

riderx commented Oct 29, 2025 •

edited

Loading