From f029997ee1c974fbe55f954ee678b6ac042082c6 Mon Sep 17 00:00:00 2001 From: Martin Donadieu Date: Tue, 11 Nov 2025 14:32:08 +0000 Subject: [PATCH 1/7] docs: clarify return types for Capacitor iOS plugins --- docs/plugins/creating-plugins/ios-guide.md | 6 ++++++ .../version-v7/plugins/creating-plugins/ios-guide.md | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/docs/plugins/creating-plugins/ios-guide.md b/docs/plugins/creating-plugins/ios-guide.md index 195fd218e..28686dd34 100644 --- a/docs/plugins/creating-plugins/ios-guide.md +++ b/docs/plugins/creating-plugins/ios-guide.md @@ -147,6 +147,12 @@ This makes the `echo` method available to the Capacitor web runtime, indicating To add more methods to your plugin, create them in the `.swift` plugin class with the `@objc` before the `func` keyword and add a new `CAPPluginMethod` entry in the `pluginMethods` array. +Capacitor currently exposes three `returnType` values in `ios/Capacitor/Capacitor/JSExport.swift` that control how the generated JavaScript proxies interact with native code: + +- `CAPPluginReturnNone`: Use for fire-and-forget calls that neither resolve nor reject a JavaScript promise. The generated JS uses `nativeCallback` immediately and expects no further data. +- `CAPPluginReturnPromise`: The default. The generated JS returns a `Promise` that you must resolve or reject once per call. +- `CAPPluginReturnCallback`: Use when you want to push multiple updates back to the web side. Capacitor automatically appends a `_callback` argument to your method, and the generated JS keeps the callback alive until you explicitly finish. + ## Permissions If your plugin has functionality on iOS that requires permissions from the end user, then you will need to implement the permissions pattern. diff --git a/versioned_docs/version-v7/plugins/creating-plugins/ios-guide.md b/versioned_docs/version-v7/plugins/creating-plugins/ios-guide.md index 195fd218e..7e820a8c4 100644 --- a/versioned_docs/version-v7/plugins/creating-plugins/ios-guide.md +++ b/versioned_docs/version-v7/plugins/creating-plugins/ios-guide.md @@ -147,6 +147,12 @@ This makes the `echo` method available to the Capacitor web runtime, indicating To add more methods to your plugin, create them in the `.swift` plugin class with the `@objc` before the `func` keyword and add a new `CAPPluginMethod` entry in the `pluginMethods` array. +Capacitor defines three `returnType` values in `ios/Capacitor/Capacitor/JSExport.swift`, and each one changes how the generated JavaScript wrapper calls into native code: + +- `CAPPluginReturnNone`: fire-and-forget methods that return immediately through `nativeCallback` and do not keep a promise/callback open. +- `CAPPluginReturnPromise`: the standard promise-based bridge where you resolve or reject once per invocation. +- `CAPPluginReturnCallback`: for streaming data. Capacitor adds a `_callback` parameter to your Swift method and keeps the JavaScript callback alive until you finish. + ## Permissions If your plugin has functionality on iOS that requires permissions from the end user, then you will need to implement the permissions pattern. From 85e6379fb84ef684bbcb4201be670fa58d217822 Mon Sep 17 00:00:00 2001 From: Martin DONADIEU Date: Sun, 8 Mar 2026 13:02:44 +0100 Subject: [PATCH 2/7] Update docs/plugins/creating-plugins/ios-guide.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/plugins/creating-plugins/ios-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins/creating-plugins/ios-guide.md b/docs/plugins/creating-plugins/ios-guide.md index 28686dd34..dfac31803 100644 --- a/docs/plugins/creating-plugins/ios-guide.md +++ b/docs/plugins/creating-plugins/ios-guide.md @@ -151,7 +151,7 @@ Capacitor currently exposes three `returnType` values in `ios/Capacitor/Capacito - `CAPPluginReturnNone`: Use for fire-and-forget calls that neither resolve nor reject a JavaScript promise. The generated JS uses `nativeCallback` immediately and expects no further data. - `CAPPluginReturnPromise`: The default. The generated JS returns a `Promise` that you must resolve or reject once per call. -- `CAPPluginReturnCallback`: Use when you want to push multiple updates back to the web side. Capacitor automatically appends a `_callback` argument to your method, and the generated JS keeps the callback alive until you explicitly finish. +- `CAPPluginReturnCallback`: Use when you want to push multiple updates back to the web side (for example, streaming or progress updates). The generated JS uses a callback-style API and keeps the callback alive while your native plugin keeps the associated `CAPPluginCall` alive (for example by setting `call.keepAlive = true` or using the “saving calls” API) and explicitly finishes it when no more updates will be sent. ## Permissions From e2f2f04dbfd95bb3b021880939713a7383be7a55 Mon Sep 17 00:00:00 2001 From: Martin DONADIEU Date: Sun, 8 Mar 2026 13:02:52 +0100 Subject: [PATCH 3/7] Update versioned_docs/version-v7/plugins/creating-plugins/ios-guide.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- versioned_docs/version-v7/plugins/creating-plugins/ios-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versioned_docs/version-v7/plugins/creating-plugins/ios-guide.md b/versioned_docs/version-v7/plugins/creating-plugins/ios-guide.md index 7e820a8c4..8cc3774f6 100644 --- a/versioned_docs/version-v7/plugins/creating-plugins/ios-guide.md +++ b/versioned_docs/version-v7/plugins/creating-plugins/ios-guide.md @@ -147,7 +147,7 @@ This makes the `echo` method available to the Capacitor web runtime, indicating To add more methods to your plugin, create them in the `.swift` plugin class with the `@objc` before the `func` keyword and add a new `CAPPluginMethod` entry in the `pluginMethods` array. -Capacitor defines three `returnType` values in `ios/Capacitor/Capacitor/JSExport.swift`, and each one changes how the generated JavaScript wrapper calls into native code: +Capacitor defines three `returnType` values in [`JSExport.swift`](https://github.com/ionic-team/capacitor/blob/main/ios/Capacitor/Capacitor/JSExport.swift), and each one changes how the generated JavaScript wrapper calls into native code: - `CAPPluginReturnNone`: fire-and-forget methods that return immediately through `nativeCallback` and do not keep a promise/callback open. - `CAPPluginReturnPromise`: the standard promise-based bridge where you resolve or reject once per invocation. From 3304a6abb800ad83decf5bc87513b51c7b62b4d1 Mon Sep 17 00:00:00 2001 From: Martin DONADIEU Date: Sun, 8 Mar 2026 13:03:00 +0100 Subject: [PATCH 4/7] Update versioned_docs/version-v7/plugins/creating-plugins/ios-guide.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- versioned_docs/version-v7/plugins/creating-plugins/ios-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versioned_docs/version-v7/plugins/creating-plugins/ios-guide.md b/versioned_docs/version-v7/plugins/creating-plugins/ios-guide.md index 8cc3774f6..101fb15b2 100644 --- a/versioned_docs/version-v7/plugins/creating-plugins/ios-guide.md +++ b/versioned_docs/version-v7/plugins/creating-plugins/ios-guide.md @@ -149,7 +149,7 @@ To add more methods to your plugin, create them in the `.swift` plugin class wit Capacitor defines three `returnType` values in [`JSExport.swift`](https://github.com/ionic-team/capacitor/blob/main/ios/Capacitor/Capacitor/JSExport.swift), and each one changes how the generated JavaScript wrapper calls into native code: -- `CAPPluginReturnNone`: fire-and-forget methods that return immediately through `nativeCallback` and do not keep a promise/callback open. +- `CAPPluginReturnNone`: methods that don't return a value to JavaScript and complete immediately (mapped to `Promise`), without keeping a long‑lived callback open. - `CAPPluginReturnPromise`: the standard promise-based bridge where you resolve or reject once per invocation. - `CAPPluginReturnCallback`: for streaming data. Capacitor adds a `_callback` parameter to your Swift method and keeps the JavaScript callback alive until you finish. From 48d9d466dddc38566a377e54c82a487bd94cc9ce Mon Sep 17 00:00:00 2001 From: Martin DONADIEU Date: Sun, 8 Mar 2026 13:03:08 +0100 Subject: [PATCH 5/7] Update docs/plugins/creating-plugins/ios-guide.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/plugins/creating-plugins/ios-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins/creating-plugins/ios-guide.md b/docs/plugins/creating-plugins/ios-guide.md index dfac31803..63c99c1a2 100644 --- a/docs/plugins/creating-plugins/ios-guide.md +++ b/docs/plugins/creating-plugins/ios-guide.md @@ -149,7 +149,7 @@ To add more methods to your plugin, create them in the `.swift` plugin class wit Capacitor currently exposes three `returnType` values in `ios/Capacitor/Capacitor/JSExport.swift` that control how the generated JavaScript proxies interact with native code: -- `CAPPluginReturnNone`: Use for fire-and-forget calls that neither resolve nor reject a JavaScript promise. The generated JS uses `nativeCallback` immediately and expects no further data. +- `CAPPluginReturnNone`: Use for calls that don't return a value. The generated JS still returns a `Promise` that resolves with no value (and can reject on error), and it uses `nativeCallback` immediately without expecting further data. - `CAPPluginReturnPromise`: The default. The generated JS returns a `Promise` that you must resolve or reject once per call. - `CAPPluginReturnCallback`: Use when you want to push multiple updates back to the web side (for example, streaming or progress updates). The generated JS uses a callback-style API and keeps the callback alive while your native plugin keeps the associated `CAPPluginCall` alive (for example by setting `call.keepAlive = true` or using the “saving calls” API) and explicitly finishes it when no more updates will be sent. From a2e51b74fb55dbae5b16a62d42dc355dc3ac5e14 Mon Sep 17 00:00:00 2001 From: Martin DONADIEU Date: Sun, 8 Mar 2026 13:03:15 +0100 Subject: [PATCH 6/7] Update versioned_docs/version-v7/plugins/creating-plugins/ios-guide.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- versioned_docs/version-v7/plugins/creating-plugins/ios-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versioned_docs/version-v7/plugins/creating-plugins/ios-guide.md b/versioned_docs/version-v7/plugins/creating-plugins/ios-guide.md index 101fb15b2..866f39f14 100644 --- a/versioned_docs/version-v7/plugins/creating-plugins/ios-guide.md +++ b/versioned_docs/version-v7/plugins/creating-plugins/ios-guide.md @@ -151,7 +151,7 @@ Capacitor defines three `returnType` values in [`JSExport.swift`](https://github - `CAPPluginReturnNone`: methods that don't return a value to JavaScript and complete immediately (mapped to `Promise`), without keeping a long‑lived callback open. - `CAPPluginReturnPromise`: the standard promise-based bridge where you resolve or reject once per invocation. -- `CAPPluginReturnCallback`: for streaming data. Capacitor adds a `_callback` parameter to your Swift method and keeps the JavaScript callback alive until you finish. +- `CAPPluginReturnCallback`: for streaming or repeated data. Use the associated `CAPPluginCall` (for example, with `call.keepAlive = true` and the saving-calls pattern) to keep the JavaScript callback alive until you are done and release the call. ## Permissions From 55b60c743fe4427974c9fef74b91b7f617843d6f Mon Sep 17 00:00:00 2001 From: Martin DONADIEU Date: Sun, 8 Mar 2026 13:03:21 +0100 Subject: [PATCH 7/7] Update docs/plugins/creating-plugins/ios-guide.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/plugins/creating-plugins/ios-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins/creating-plugins/ios-guide.md b/docs/plugins/creating-plugins/ios-guide.md index 63c99c1a2..6fb2c2300 100644 --- a/docs/plugins/creating-plugins/ios-guide.md +++ b/docs/plugins/creating-plugins/ios-guide.md @@ -147,7 +147,7 @@ This makes the `echo` method available to the Capacitor web runtime, indicating To add more methods to your plugin, create them in the `.swift` plugin class with the `@objc` before the `func` keyword and add a new `CAPPluginMethod` entry in the `pluginMethods` array. -Capacitor currently exposes three `returnType` values in `ios/Capacitor/Capacitor/JSExport.swift` that control how the generated JavaScript proxies interact with native code: +Capacitor currently exposes three `returnType` values in [`JSExport.swift`](https://github.com/ionic-team/capacitor/blob/main/ios/Capacitor/Capacitor/JSExport.swift) that control how the generated JavaScript proxies interact with native code: - `CAPPluginReturnNone`: Use for calls that don't return a value. The generated JS still returns a `Promise` that resolves with no value (and can reject on error), and it uses `nativeCallback` immediately without expecting further data. - `CAPPluginReturnPromise`: The default. The generated JS returns a `Promise` that you must resolve or reject once per call.