@capgo/capacitor-uploader 8.2.11 → 8.2.13

package/README.md

@@ -65,6 +65,32 @@ Add the following to your `AndroidManifest.xml` file:
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
 ```
 
+
+
+## iOS
+
+On iOS the plugin uploads through a background `URLSession` using the identifier `CapacitorUploaderBackgroundSession`.
+
+Uploads often work without extra `Info.plist` keys. To allow the system to wake your app when background transfers finish, add the `fetch` background mode:
+
+```xml
+<key>UIBackgroundModes</key>
+<array>
+  <string>fetch</string>
+</array>
+```
+
+Do **not** add the `processing` background mode for this plugin alone. App Store Connect requires `BGTaskSchedulerPermittedIdentifiers` whenever `processing` is declared, and this plugin does not register `BGTaskScheduler` tasks. If your app already includes `processing` (for example from older documentation) and validation fails, add:
+
+```xml
+<key>BGTaskSchedulerPermittedIdentifiers</key>
+<array>
+  <string>CapacitorUploaderBackgroundSession</string>
+</array>
+```
+
+See [issue #115](https://github.com/Cap-go/capacitor-uploader/issues/115) for context.
+
 ## Example S3 upload
 
 ```typescript
@@ -242,6 +268,20 @@ Documentation for the [Capacitor Camera preview](https://github.com/Cap-go/camer
 
 Capacitor Uploader Plugin for uploading files with background support and progress tracking.
 
+### iOS setup
+
+On iOS the native layer uses a background `URLSession` with the identifier
+`CapacitorUploaderBackgroundSession`. Many apps can upload without adding
+`UIBackgroundModes`; add `fetch` when you need uploads to continue after the app
+is suspended.
+
+App Store Connect rejects builds that declare `UIBackgroundModes` → `processing`
+without `BGTaskSchedulerPermittedIdentifiers`. This plugin does not schedule
+`BGTaskScheduler` work, so avoid `processing` unless another feature needs it.
+If `processing` is present (for example from older setup guides), include
+`CapacitorUploaderBackgroundSession` in `BGTaskSchedulerPermittedIdentifiers`
+in your app's `Info.plist`.
+
 ### startUpload(...)
 
 ```typescript

package/android/src/main/java/ee/forgr/capacitor/uploader/UploaderPlugin.java

@@ -29,7 +29,7 @@ public class UploaderPlugin extends Plugin {
 
     private static final String CAPACITOR_CONTENT_PATH_PREFIX = "/_capacitor_content_";
 
-    private final String pluginVersion = "8.2.11";
+    private final String pluginVersion = "8.2.13";
 
     private Uploader implementation;
 

package/dist/docs.json

@@ -2,8 +2,12 @@
   "api": {
     "name": "UploaderPlugin",
     "slug": "uploaderplugin",
-    "docs": "Capacitor Uploader Plugin for uploading files with background support and progress tracking.",
+    "docs": "Capacitor Uploader Plugin for uploading files with background support and progress tracking.\n\n### iOS setup\n\nOn iOS the native layer uses a background `URLSession` with the identifier\n`CapacitorUploaderBackgroundSession`. Many apps can upload without adding\n`UIBackgroundModes`; add `fetch` when you need uploads to continue after the app\nis suspended.\n\nApp Store Connect rejects builds that declare `UIBackgroundModes` → `processing`\nwithout `BGTaskSchedulerPermittedIdentifiers`. This plugin does not schedule\n`BGTaskScheduler` work, so avoid `processing` unless another feature needs it.\nIf `processing` is present (for example from older setup guides), include\n`CapacitorUploaderBackgroundSession` in `BGTaskSchedulerPermittedIdentifiers`\nin your app's `Info.plist`.",
     "tags": [
+      {
+        "text": "```xml\n<key>UIBackgroundModes</key>\n<array>\n  <string>fetch</string>\n</array>\n<key>BGTaskSchedulerPermittedIdentifiers</key>\n<array>\n  <string>CapacitorUploaderBackgroundSession</string>\n</array>\n```",
+        "name": "example"
+      },
       {
         "text": "0.0.1",
         "name": "since"

package/dist/esm/definitions.d.ts

@@ -184,6 +184,32 @@ export interface UploadEvent {
 /**
  * Capacitor Uploader Plugin for uploading files with background support and progress tracking.
  *
+ * ### iOS setup
+ *
+ * On iOS the native layer uses a background `URLSession` with the identifier
+ * `CapacitorUploaderBackgroundSession`. Many apps can upload without adding
+ * `UIBackgroundModes`; add `fetch` when you need uploads to continue after the app
+ * is suspended.
+ *
+ * App Store Connect rejects builds that declare `UIBackgroundModes` → `processing`
+ * without `BGTaskSchedulerPermittedIdentifiers`. This plugin does not schedule
+ * `BGTaskScheduler` work, so avoid `processing` unless another feature needs it.
+ * If `processing` is present (for example from older setup guides), include
+ * `CapacitorUploaderBackgroundSession` in `BGTaskSchedulerPermittedIdentifiers`
+ * in your app's `Info.plist`.
+ *
+ * @example
+ * ```xml
+ * <key>UIBackgroundModes</key>
+ * <array>
+ *   <string>fetch</string>
+ * </array>
+ * <key>BGTaskSchedulerPermittedIdentifiers</key>
+ * <array>
+ *   <string>CapacitorUploaderBackgroundSession</string>
+ * </array>
+ * ```
+ *
  * @since 0.0.1
  */
 export interface UploaderPlugin {

package/dist/esm/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["import type { PluginListenerHandle } from '@capacitor/core';\n\n/**\n * Configuration options for uploading a file.\n *\n * @since 0.0.1\n */\nexport interface UploadFileOption {\n  /**\n   * The local file path of the file to upload.\n   * Can be a file:// URL or an absolute path.\n   *\n   * @since 0.0.3\n   */\n  filePath: string;\n\n  /**\n   * The form field name for the file part when using multipart upload.\n   *\n   * If omitted, `uploadOption.fileField` is used (defaults to `'file'`).\n   *\n   * @since 0.0.3\n   */\n  fieldName?: string;\n\n  /**\n   * The MIME type of this file.\n   * If not specified, the plugin will attempt to determine it automatically.\n   *\n   * @since 0.0.3\n   */\n  mimeType?: string;\n}\n\nexport interface uploadOption {\n  /**\n   * The local file path of the file to upload.\n   * Can be a file:// URL or an absolute path.\n   *\n   * If you need to upload multiple files in a single multipart request, use `files`.\n   *\n   * @since 0.0.1\n   */\n  filePath?: string;\n\n  /**\n   * Multiple files to upload in a single request.\n   *\n   * When provided, uploads are sent as `multipart/form-data` with one part per file.\n   * Use `fieldName` to control each part name (e.g. `images[]`).\n   *\n   * Note: `PUT` uploads (e.g. presigned S3 URLs) only support a single file.\n   *\n   * @since 0.0.3\n   */\n  files?: UploadFileOption[];\n\n  /**\n   * The server URL endpoint where the file should be uploaded.\n   *\n   * @since 0.0.1\n   */\n  serverUrl: string;\n\n  /**\n   * The title of the upload notification shown to the user.\n   * Android only.\n   *\n   * @default 'Uploading'\n   * @since 0.0.1\n   */\n  notificationTitle?: string;\n\n  /**\n   * HTTP headers to send with the upload request.\n   * Useful for authentication tokens, content types, etc.\n   *\n   * @since 0.0.1\n   * @example\n   * ```typescript\n   * headers: {\n   *   'Authorization': 'Bearer token123',\n   *   'X-Custom-Header': 'value'\n   * }\n   * ```\n   */\n  headers: {\n    [key: string]: string;\n  };\n\n  /**\n   * The HTTP method to use for the upload request.\n   *\n   * @default 'POST'\n   * @since 0.0.1\n   */\n  method?: 'PUT' | 'POST';\n\n  /**\n   * The MIME type of the file being uploaded.\n   * If not specified, the plugin will attempt to determine it automatically.\n   *\n   * @since 0.0.1\n   * @example 'image/jpeg', 'application/pdf', 'video/mp4'\n   */\n  mimeType?: string;\n\n  /**\n   * Additional form parameters to send with the upload request.\n   * These will be included as form data in multipart uploads.\n   *\n   * @since 0.0.1\n   */\n  parameters?: { [key: string]: string };\n\n  /**\n   * The maximum number of times to retry the upload if it fails.\n   *\n   * @since 0.0.1\n   * @default 0\n   */\n  maxRetries?: number;\n\n  /**\n   * The type of upload to perform.\n   * - 'binary': Uploads the file as raw binary data in the request body\n   * - 'multipart': Uploads the file as multipart/form-data\n   *\n   * @default 'binary' when `method` is `'PUT'`, otherwise `'multipart'`\n   * @since 0.0.2\n   */\n  uploadType?: 'binary' | 'multipart';\n\n  /**\n   * The form field name for the file when using multipart upload type.\n   * Only used when uploadType is 'multipart'.\n   *\n   * For multi-file uploads via `files`, this is used as the default field name\n   * when a file entry does not specify `fieldName`.\n   *\n   * @default 'file'\n   * @since 0.0.2\n   */\n  fileField?: string;\n}\n\n/**\n * Event emitted during the upload lifecycle.\n *\n * @since 0.0.1\n */\nexport interface UploadEvent {\n  /**\n   * The current status of the upload.\n   * - 'uploading': Upload is in progress\n   * - 'completed': Upload finished successfully\n   * - 'failed': Upload encountered an error\n   *\n   * @since 0.0.1\n   */\n  name: 'uploading' | 'completed' | 'failed';\n\n  /**\n   * Additional data about the upload event.\n   *\n   * @since 0.0.1\n   */\n  payload: {\n    /**\n     * Upload progress percentage from 0 to 100.\n     * Only present during 'uploading' events.\n     *\n     * @since 0.0.1\n     */\n    percent?: number;\n\n    /**\n     * Error message if the upload failed.\n     * Only present during 'failed' events.\n     *\n     * @since 0.0.1\n     */\n    error?: string;\n\n    /**\n     * HTTP status code returned by the server.\n     * Present during 'completed' and 'failed' events.\n     *\n     * @since 0.0.1\n     */\n    statusCode?: number;\n  };\n\n  /**\n   * Unique identifier for this upload task.\n   *\n   * @since 0.0.1\n   */\n  id: string;\n}\n\n/**\n * Capacitor Uploader Plugin for uploading files with background support and progress tracking.\n *\n * @since 0.0.1\n */\nexport interface UploaderPlugin {\n  /**\n   * Start uploading a file to a server.\n   *\n   * The upload will continue in the background even if the app is closed or backgrounded.\n   * Listen to upload events to track progress, completion, or failure.\n   *\n   * @param options - Configuration for the upload\n   * @returns Promise that resolves with the upload ID\n   * @throws Error if the upload fails to start\n   * @since 0.0.1\n   * @example\n   * ```typescript\n   * const { id } = await Uploader.startUpload({\n   *   filePath: 'file:///path/to/file.jpg',\n   *   serverUrl: 'https://example.com/upload',\n   *   headers: {\n   *     'Authorization': 'Bearer token'\n   *   },\n   *   method: 'POST',\n   *   uploadType: 'multipart',\n   *   fileField: 'photo'\n   * });\n   * console.log('Upload started with ID:', id);\n   * ```\n   *\n   * @example\n   * ```typescript\n   * const { id } = await Uploader.startUpload({\n   *   serverUrl: 'https://api.example.com/upload',\n   *   method: 'POST',\n   *   uploadType: 'multipart',\n   *   files: [\n   *     { filePath: 'file:///...photo1.jpg', fieldName: 'images[]', mimeType: 'image/jpeg' },\n   *     { filePath: 'file:///...photo2.jpg', fieldName: 'images[]', mimeType: 'image/jpeg' },\n   *   ],\n   *   parameters: { albumId: '7' },\n   *   headers: { Authorization: 'Bearer token' },\n   * });\n   * console.log('Upload started with ID:', id);\n   * ```\n   */\n  startUpload(options: uploadOption): Promise<{ id: string }>;\n\n  /**\n   * Cancel and remove an ongoing upload.\n   *\n   * This will stop the upload if it's in progress and clean up resources.\n   *\n   * @param options - Object containing the upload ID to remove\n   * @returns Promise that resolves when the upload is removed\n   * @throws Error if the upload ID is not found\n   * @since 0.0.1\n   * @example\n   * ```typescript\n   * await Uploader.removeUpload({ id: 'upload-123' });\n   * ```\n   */\n  removeUpload(options: { id: string }): Promise<void>;\n\n  /**\n   * Listen for upload progress and status events.\n   *\n   * Events are fired for:\n   * - Upload progress updates (with percent)\n   * - Upload completion (with statusCode)\n   * - Upload failure (with error and statusCode)\n   *\n   * @param eventName - Must be 'events'\n   * @param listenerFunc - Callback function to handle upload events\n   * @returns Promise that resolves with a listener handle for removal\n   * @since 0.0.1\n   * @example\n   * ```typescript\n   * const listener = await Uploader.addListener('events', (event) => {\n   *   if (event.name === 'uploading') {\n   *     console.log(`Upload ${event.id}: ${event.payload.percent}%`);\n   *   } else if (event.name === 'completed') {\n   *     console.log(`Upload ${event.id} completed`);\n   *   } else if (event.name === 'failed') {\n   *     console.error(`Upload ${event.id} failed:`, event.payload.error);\n   *   }\n   * });\n   *\n   * // Remove listener when done\n   * await listener.remove();\n   * ```\n   */\n  addListener(eventName: 'events', listenerFunc: (state: UploadEvent) => void): Promise<PluginListenerHandle>;\n\n  /**\n   * Get the native Capacitor plugin version.\n   *\n   * @returns Promise that resolves with the plugin version\n   * @throws Error if getting the version fails\n   * @since 0.0.1\n   * @example\n   * ```typescript\n   * const { version } = await Uploader.getPluginVersion();\n   * console.log('Plugin version:', version);\n   * ```\n   */\n  getPluginVersion(): Promise<{ version: string }>;\n}\n"]}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["import type { PluginListenerHandle } from '@capacitor/core';\n\n/**\n * Configuration options for uploading a file.\n *\n * @since 0.0.1\n */\nexport interface UploadFileOption {\n  /**\n   * The local file path of the file to upload.\n   * Can be a file:// URL or an absolute path.\n   *\n   * @since 0.0.3\n   */\n  filePath: string;\n\n  /**\n   * The form field name for the file part when using multipart upload.\n   *\n   * If omitted, `uploadOption.fileField` is used (defaults to `'file'`).\n   *\n   * @since 0.0.3\n   */\n  fieldName?: string;\n\n  /**\n   * The MIME type of this file.\n   * If not specified, the plugin will attempt to determine it automatically.\n   *\n   * @since 0.0.3\n   */\n  mimeType?: string;\n}\n\nexport interface uploadOption {\n  /**\n   * The local file path of the file to upload.\n   * Can be a file:// URL or an absolute path.\n   *\n   * If you need to upload multiple files in a single multipart request, use `files`.\n   *\n   * @since 0.0.1\n   */\n  filePath?: string;\n\n  /**\n   * Multiple files to upload in a single request.\n   *\n   * When provided, uploads are sent as `multipart/form-data` with one part per file.\n   * Use `fieldName` to control each part name (e.g. `images[]`).\n   *\n   * Note: `PUT` uploads (e.g. presigned S3 URLs) only support a single file.\n   *\n   * @since 0.0.3\n   */\n  files?: UploadFileOption[];\n\n  /**\n   * The server URL endpoint where the file should be uploaded.\n   *\n   * @since 0.0.1\n   */\n  serverUrl: string;\n\n  /**\n   * The title of the upload notification shown to the user.\n   * Android only.\n   *\n   * @default 'Uploading'\n   * @since 0.0.1\n   */\n  notificationTitle?: string;\n\n  /**\n   * HTTP headers to send with the upload request.\n   * Useful for authentication tokens, content types, etc.\n   *\n   * @since 0.0.1\n   * @example\n   * ```typescript\n   * headers: {\n   *   'Authorization': 'Bearer token123',\n   *   'X-Custom-Header': 'value'\n   * }\n   * ```\n   */\n  headers: {\n    [key: string]: string;\n  };\n\n  /**\n   * The HTTP method to use for the upload request.\n   *\n   * @default 'POST'\n   * @since 0.0.1\n   */\n  method?: 'PUT' | 'POST';\n\n  /**\n   * The MIME type of the file being uploaded.\n   * If not specified, the plugin will attempt to determine it automatically.\n   *\n   * @since 0.0.1\n   * @example 'image/jpeg', 'application/pdf', 'video/mp4'\n   */\n  mimeType?: string;\n\n  /**\n   * Additional form parameters to send with the upload request.\n   * These will be included as form data in multipart uploads.\n   *\n   * @since 0.0.1\n   */\n  parameters?: { [key: string]: string };\n\n  /**\n   * The maximum number of times to retry the upload if it fails.\n   *\n   * @since 0.0.1\n   * @default 0\n   */\n  maxRetries?: number;\n\n  /**\n   * The type of upload to perform.\n   * - 'binary': Uploads the file as raw binary data in the request body\n   * - 'multipart': Uploads the file as multipart/form-data\n   *\n   * @default 'binary' when `method` is `'PUT'`, otherwise `'multipart'`\n   * @since 0.0.2\n   */\n  uploadType?: 'binary' | 'multipart';\n\n  /**\n   * The form field name for the file when using multipart upload type.\n   * Only used when uploadType is 'multipart'.\n   *\n   * For multi-file uploads via `files`, this is used as the default field name\n   * when a file entry does not specify `fieldName`.\n   *\n   * @default 'file'\n   * @since 0.0.2\n   */\n  fileField?: string;\n}\n\n/**\n * Event emitted during the upload lifecycle.\n *\n * @since 0.0.1\n */\nexport interface UploadEvent {\n  /**\n   * The current status of the upload.\n   * - 'uploading': Upload is in progress\n   * - 'completed': Upload finished successfully\n   * - 'failed': Upload encountered an error\n   *\n   * @since 0.0.1\n   */\n  name: 'uploading' | 'completed' | 'failed';\n\n  /**\n   * Additional data about the upload event.\n   *\n   * @since 0.0.1\n   */\n  payload: {\n    /**\n     * Upload progress percentage from 0 to 100.\n     * Only present during 'uploading' events.\n     *\n     * @since 0.0.1\n     */\n    percent?: number;\n\n    /**\n     * Error message if the upload failed.\n     * Only present during 'failed' events.\n     *\n     * @since 0.0.1\n     */\n    error?: string;\n\n    /**\n     * HTTP status code returned by the server.\n     * Present during 'completed' and 'failed' events.\n     *\n     * @since 0.0.1\n     */\n    statusCode?: number;\n  };\n\n  /**\n   * Unique identifier for this upload task.\n   *\n   * @since 0.0.1\n   */\n  id: string;\n}\n\n/**\n * Capacitor Uploader Plugin for uploading files with background support and progress tracking.\n *\n * ### iOS setup\n *\n * On iOS the native layer uses a background `URLSession` with the identifier\n * `CapacitorUploaderBackgroundSession`. Many apps can upload without adding\n * `UIBackgroundModes`; add `fetch` when you need uploads to continue after the app\n * is suspended.\n *\n * App Store Connect rejects builds that declare `UIBackgroundModes` → `processing`\n * without `BGTaskSchedulerPermittedIdentifiers`. This plugin does not schedule\n * `BGTaskScheduler` work, so avoid `processing` unless another feature needs it.\n * If `processing` is present (for example from older setup guides), include\n * `CapacitorUploaderBackgroundSession` in `BGTaskSchedulerPermittedIdentifiers`\n * in your app's `Info.plist`.\n *\n * @example\n * ```xml\n * <key>UIBackgroundModes</key>\n * <array>\n *   <string>fetch</string>\n * </array>\n * <key>BGTaskSchedulerPermittedIdentifiers</key>\n * <array>\n *   <string>CapacitorUploaderBackgroundSession</string>\n * </array>\n * ```\n *\n * @since 0.0.1\n */\nexport interface UploaderPlugin {\n  /**\n   * Start uploading a file to a server.\n   *\n   * The upload will continue in the background even if the app is closed or backgrounded.\n   * Listen to upload events to track progress, completion, or failure.\n   *\n   * @param options - Configuration for the upload\n   * @returns Promise that resolves with the upload ID\n   * @throws Error if the upload fails to start\n   * @since 0.0.1\n   * @example\n   * ```typescript\n   * const { id } = await Uploader.startUpload({\n   *   filePath: 'file:///path/to/file.jpg',\n   *   serverUrl: 'https://example.com/upload',\n   *   headers: {\n   *     'Authorization': 'Bearer token'\n   *   },\n   *   method: 'POST',\n   *   uploadType: 'multipart',\n   *   fileField: 'photo'\n   * });\n   * console.log('Upload started with ID:', id);\n   * ```\n   *\n   * @example\n   * ```typescript\n   * const { id } = await Uploader.startUpload({\n   *   serverUrl: 'https://api.example.com/upload',\n   *   method: 'POST',\n   *   uploadType: 'multipart',\n   *   files: [\n   *     { filePath: 'file:///...photo1.jpg', fieldName: 'images[]', mimeType: 'image/jpeg' },\n   *     { filePath: 'file:///...photo2.jpg', fieldName: 'images[]', mimeType: 'image/jpeg' },\n   *   ],\n   *   parameters: { albumId: '7' },\n   *   headers: { Authorization: 'Bearer token' },\n   * });\n   * console.log('Upload started with ID:', id);\n   * ```\n   */\n  startUpload(options: uploadOption): Promise<{ id: string }>;\n\n  /**\n   * Cancel and remove an ongoing upload.\n   *\n   * This will stop the upload if it's in progress and clean up resources.\n   *\n   * @param options - Object containing the upload ID to remove\n   * @returns Promise that resolves when the upload is removed\n   * @throws Error if the upload ID is not found\n   * @since 0.0.1\n   * @example\n   * ```typescript\n   * await Uploader.removeUpload({ id: 'upload-123' });\n   * ```\n   */\n  removeUpload(options: { id: string }): Promise<void>;\n\n  /**\n   * Listen for upload progress and status events.\n   *\n   * Events are fired for:\n   * - Upload progress updates (with percent)\n   * - Upload completion (with statusCode)\n   * - Upload failure (with error and statusCode)\n   *\n   * @param eventName - Must be 'events'\n   * @param listenerFunc - Callback function to handle upload events\n   * @returns Promise that resolves with a listener handle for removal\n   * @since 0.0.1\n   * @example\n   * ```typescript\n   * const listener = await Uploader.addListener('events', (event) => {\n   *   if (event.name === 'uploading') {\n   *     console.log(`Upload ${event.id}: ${event.payload.percent}%`);\n   *   } else if (event.name === 'completed') {\n   *     console.log(`Upload ${event.id} completed`);\n   *   } else if (event.name === 'failed') {\n   *     console.error(`Upload ${event.id} failed:`, event.payload.error);\n   *   }\n   * });\n   *\n   * // Remove listener when done\n   * await listener.remove();\n   * ```\n   */\n  addListener(eventName: 'events', listenerFunc: (state: UploadEvent) => void): Promise<PluginListenerHandle>;\n\n  /**\n   * Get the native Capacitor plugin version.\n   *\n   * @returns Promise that resolves with the plugin version\n   * @throws Error if getting the version fails\n   * @since 0.0.1\n   * @example\n   * ```typescript\n   * const { version } = await Uploader.getPluginVersion();\n   * console.log('Plugin version:', version);\n   * ```\n   */\n  getPluginVersion(): Promise<{ version: string }>;\n}\n"]}

package/ios/Sources/UploaderPlugin/UploaderPlugin.swift

@@ -3,7 +3,7 @@ import Capacitor
 
 @objc(UploaderPlugin)
 public class UploaderPlugin: CAPPlugin, CAPBridgedPlugin {
-    private let pluginVersion: String = "8.2.11"
+    private let pluginVersion: String = "8.2.13"
     public let identifier = "UploaderPlugin"
     public let jsName = "Uploader"
     public let pluginMethods: [CAPPluginMethod] = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capgo/capacitor-uploader",
-  "version": "8.2.11",
+  "version": "8.2.13",
   "description": "Upload file natively",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",