@capgo/capacitor-file-picker 8.1.7 → 8.1.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +31 -6
- package/android/src/main/java/app/capgo/capacitor/filepicker/CapgoFilePickerPlugin.java +1 -1
- package/dist/docs.json +3 -3
- package/dist/esm/definitions.d.ts +13 -3
- package/dist/esm/definitions.js.map +1 -1
- package/ios/Sources/CapgoFilePickerPlugin/CapgoFilePickerPlugin.swift +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -50,6 +50,24 @@ npx cap sync
|
|
|
50
50
|
- Android: API 24+ (Android 7.0+)
|
|
51
51
|
- Web: Modern browsers with File API support
|
|
52
52
|
|
|
53
|
+
## Android media permissions and Google Play review
|
|
54
|
+
|
|
55
|
+
This plugin is designed around user-selected picker flows such as `pickFiles()`, `pickImages()`, `pickVideos()`, `pickMedia()`, and `pickDirectory()`. For one-time or infrequent file, image, or video selection, use these picker methods and avoid adding broad media permissions to your app manifest.
|
|
56
|
+
|
|
57
|
+
Google Play only allows `READ_MEDIA_IMAGES` and `READ_MEDIA_VIDEO` when photo or video access is directly related to your app's core purpose and picker alternatives are not sufficient. Do not request or retain these permissions only to let a user choose files, images, or videos.
|
|
58
|
+
|
|
59
|
+
Before publishing an app that declares these permissions:
|
|
60
|
+
|
|
61
|
+
- Make sure broad photo or video library access is required for the app's core functionality.
|
|
62
|
+
- Be ready to justify why Android Photo Picker or this plugin's picker methods are not sufficient.
|
|
63
|
+
- Remove broad media permissions if the app can work with user-selected files only.
|
|
64
|
+
|
|
65
|
+
If Google Play review rejects the app with a message like `Photo and Video Permissions policy: Permission use is not directly related to your app's core purpose`, remove the broad media permissions and rely on this plugin's picker APIs instead.
|
|
66
|
+
|
|
67
|
+
For apps coming from `@capgo/capacitor-file`, a custom media browser, or another broad-storage flow, the recommended alternative is `@capgo/capacitor-file-picker` with `pickImages()`, `pickVideos()`, `pickMedia()`, or `pickFiles()`.
|
|
68
|
+
|
|
69
|
+
See Google's [Photo and Video Permissions policy](https://support.google.com/googleplay/android-developer/answer/14115180) for the current review requirements.
|
|
70
|
+
|
|
53
71
|
## API
|
|
54
72
|
|
|
55
73
|
<docgen-index>
|
|
@@ -214,7 +232,9 @@ Copy a file to a new location.
|
|
|
214
232
|
checkPermissions() => Promise<PermissionStatus>
|
|
215
233
|
```
|
|
216
234
|
|
|
217
|
-
Check
|
|
235
|
+
Check broad storage or media permission state.
|
|
236
|
+
Picker-only flows should not gate `pickFiles()`, `pickImages()`,
|
|
237
|
+
`pickVideos()`, or `pickMedia()` on this permission on Android 13+.
|
|
218
238
|
Android only.
|
|
219
239
|
|
|
220
240
|
**Returns:** <code>Promise<<a href="#permissionstatus">PermissionStatus</a>></code>
|
|
@@ -230,7 +250,12 @@ Android only.
|
|
|
230
250
|
requestPermissions() => Promise<PermissionStatus>
|
|
231
251
|
```
|
|
232
252
|
|
|
233
|
-
Request
|
|
253
|
+
Request broad storage or media permissions.
|
|
254
|
+
Do not request or declare `READ_MEDIA_IMAGES` or `READ_MEDIA_VIDEO`
|
|
255
|
+
only to use picker APIs. Google Play allows these permissions only
|
|
256
|
+
when picker alternatives are not sufficient for core app functionality.
|
|
257
|
+
Use `@capgo/capacitor-file-picker` picker methods instead for
|
|
258
|
+
user-selected file, image, or video access.
|
|
234
259
|
Android only.
|
|
235
260
|
|
|
236
261
|
**Returns:** <code>Promise<<a href="#permissionstatus">PermissionStatus</a>></code>
|
|
@@ -385,10 +410,10 @@ Options for copying a file.
|
|
|
385
410
|
|
|
386
411
|
Permission status for file access.
|
|
387
412
|
|
|
388
|
-
| Prop | Type | Description
|
|
389
|
-
| ------------------------- | ----------------------------------------------------------- |
|
|
390
|
-
| **`readExternalStorage`** | <code><a href="#permissionstate">PermissionState</a></code> | Whether
|
|
391
|
-
| **`accessMediaLocation`** | <code><a href="#permissionstate">PermissionState</a></code> | Whether permission to access media location is granted
|
|
413
|
+
| Prop | Type | Description |
|
|
414
|
+
| ------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
415
|
+
| **`readExternalStorage`** | <code><a href="#permissionstate">PermissionState</a></code> | Whether broad external storage or media permission is granted. Picker APIs that return user-selected files usually do not require this on Android 13+. |
|
|
416
|
+
| **`accessMediaLocation`** | <code><a href="#permissionstate">PermissionState</a></code> | Whether permission to access media location is granted |
|
|
392
417
|
|
|
393
418
|
|
|
394
419
|
#### PluginListenerHandle
|
package/dist/docs.json
CHANGED
|
@@ -269,7 +269,7 @@
|
|
|
269
269
|
"text": "```typescript\nconst status = await CapgoFilePicker.checkPermissions();\nconsole.log('Read permission:', status.readExternalStorage);\n```"
|
|
270
270
|
}
|
|
271
271
|
],
|
|
272
|
-
"docs": "Check
|
|
272
|
+
"docs": "Check broad storage or media permission state.\nPicker-only flows should not gate `pickFiles()`, `pickImages()`,\n`pickVideos()`, or `pickMedia()` on this permission on Android 13+.\nAndroid only.",
|
|
273
273
|
"complexTypes": [
|
|
274
274
|
"PermissionStatus"
|
|
275
275
|
],
|
|
@@ -294,7 +294,7 @@
|
|
|
294
294
|
"text": "```typescript\nconst status = await CapgoFilePicker.requestPermissions();\nif (status.readExternalStorage === 'granted') {\n console.log('Permission granted');\n}\n```"
|
|
295
295
|
}
|
|
296
296
|
],
|
|
297
|
-
"docs": "Request permissions for
|
|
297
|
+
"docs": "Request broad storage or media permissions.\nDo not request or declare `READ_MEDIA_IMAGES` or `READ_MEDIA_VIDEO`\nonly to use picker APIs. Google Play allows these permissions only\nwhen picker alternatives are not sufficient for core app functionality.\nUse `@capgo/capacitor-file-picker` picker methods instead for\nuser-selected file, image, or video access.\nAndroid only.",
|
|
298
298
|
"complexTypes": [
|
|
299
299
|
"PermissionStatus"
|
|
300
300
|
],
|
|
@@ -729,7 +729,7 @@
|
|
|
729
729
|
{
|
|
730
730
|
"name": "readExternalStorage",
|
|
731
731
|
"tags": [],
|
|
732
|
-
"docs": "Whether
|
|
732
|
+
"docs": "Whether broad external storage or media permission is granted.\nPicker APIs that return user-selected files usually do not require this on Android 13+.",
|
|
733
733
|
"complexTypes": [
|
|
734
734
|
"PermissionState"
|
|
735
735
|
],
|
|
@@ -149,7 +149,10 @@ export interface PickDirectoryResult {
|
|
|
149
149
|
* @since 8.0.0
|
|
150
150
|
*/
|
|
151
151
|
export interface PermissionStatus {
|
|
152
|
-
/**
|
|
152
|
+
/**
|
|
153
|
+
* Whether broad external storage or media permission is granted.
|
|
154
|
+
* Picker APIs that return user-selected files usually do not require this on Android 13+.
|
|
155
|
+
*/
|
|
153
156
|
readExternalStorage: PermissionState;
|
|
154
157
|
/** Whether permission to access media location is granted */
|
|
155
158
|
accessMediaLocation?: PermissionState;
|
|
@@ -287,7 +290,9 @@ export interface CapgoFilePickerPlugin {
|
|
|
287
290
|
*/
|
|
288
291
|
copyFile(options: CopyFileOptions): Promise<void>;
|
|
289
292
|
/**
|
|
290
|
-
* Check
|
|
293
|
+
* Check broad storage or media permission state.
|
|
294
|
+
* Picker-only flows should not gate `pickFiles()`, `pickImages()`,
|
|
295
|
+
* `pickVideos()`, or `pickMedia()` on this permission on Android 13+.
|
|
291
296
|
* Android only.
|
|
292
297
|
*
|
|
293
298
|
* @returns Promise that resolves with the permission status
|
|
@@ -300,7 +305,12 @@ export interface CapgoFilePickerPlugin {
|
|
|
300
305
|
*/
|
|
301
306
|
checkPermissions(): Promise<PermissionStatus>;
|
|
302
307
|
/**
|
|
303
|
-
* Request
|
|
308
|
+
* Request broad storage or media permissions.
|
|
309
|
+
* Do not request or declare `READ_MEDIA_IMAGES` or `READ_MEDIA_VIDEO`
|
|
310
|
+
* only to use picker APIs. Google Play allows these permissions only
|
|
311
|
+
* when picker alternatives are not sufficient for core app functionality.
|
|
312
|
+
* Use `@capgo/capacitor-file-picker` picker methods instead for
|
|
313
|
+
* user-selected file, image, or video access.
|
|
304
314
|
* Android only.
|
|
305
315
|
*
|
|
306
316
|
* @returns Promise that resolves with the permission status
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["import type { PluginListenerHandle } from '@capacitor/core';\n\n/**\n * Options for picking files.\n *\n * @since 8.0.0\n */\nexport interface PickFilesOptions {\n /**\n * List of accepted MIME types or file extensions.\n * On iOS, only MIME types are supported.\n * Examples: ['image/*'], ['application/pdf'], ['.pdf', '.doc']\n */\n types?: string[];\n /**\n * Maximum number of files to pick.\n * Set to 0 for unlimited (platform default).\n * @default 0\n */\n limit?: number;\n /**\n * Whether to read the file data as base64.\n * Note: Reading large files may cause memory issues.\n * @default false\n */\n readData?: boolean;\n}\n\n/**\n * Options for picking media (images/videos).\n *\n * @since 8.0.0\n */\nexport interface PickMediaOptions {\n /**\n * Maximum number of files to pick.\n * Set to 0 for unlimited (platform default).\n * @default 0\n */\n limit?: number;\n /**\n * Whether to read the file data as base64.\n * Note: Reading large files may cause memory issues.\n * @default false\n */\n readData?: boolean;\n /**\n * iOS only: Skip transcoding of videos.\n * @default false\n */\n skipTranscoding?: boolean;\n /**\n * iOS 15+ only: Show ordered selection badges.\n * @default false\n */\n ordered?: boolean;\n}\n\n/**\n * Options for converting HEIC to JPEG.\n *\n * @since 8.0.0\n */\nexport interface ConvertHeicToJpegOptions {\n /** The path to the HEIC file to convert */\n path: string;\n /**\n * The compression quality for JPEG (0.0 - 1.0).\n * @default 0.9\n */\n quality?: number;\n}\n\n/**\n * Result of HEIC to JPEG conversion.\n *\n * @since 8.0.0\n */\nexport interface ConvertHeicToJpegResult {\n /** The path to the converted JPEG file */\n path: string;\n}\n\n/**\n * Options for copying a file.\n *\n * @since 8.0.0\n */\nexport interface CopyFileOptions {\n /** Source file path */\n from: string;\n /** Destination file path */\n to: string;\n /**\n * Whether to overwrite if destination exists.\n * @default false\n */\n overwrite?: boolean;\n}\n\n/**\n * Represents a picked file.\n *\n * @since 8.0.0\n */\nexport interface PickedFile {\n /** The name of the file */\n name: string;\n /** The path to the file */\n path?: string;\n /** The MIME type of the file */\n mimeType: string;\n /** The size of the file in bytes */\n size: number;\n /**\n * The base64 encoded data of the file.\n * Only present if readData was true.\n */\n data?: string;\n /**\n * The Blob instance of the file.\n * Web only.\n */\n blob?: Blob;\n /** Width in pixels (images/videos only) */\n width?: number;\n /** Height in pixels (images/videos only) */\n height?: number;\n /** Duration in seconds (videos only) */\n duration?: number;\n /** Last modified timestamp in milliseconds */\n modifiedAt?: number;\n}\n\n/**\n * Result of picking files.\n *\n * @since 8.0.0\n */\nexport interface PickFilesResult {\n /** Array of picked files */\n files: PickedFile[];\n}\n\n/**\n * Result of picking a directory.\n *\n * @since 8.0.0\n */\nexport interface PickDirectoryResult {\n /** The path to the selected directory */\n path: string;\n}\n\n/**\n * Permission status for file access.\n *\n * @since 8.0.0\n */\nexport interface PermissionStatus {\n
|
|
1
|
+
{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["import type { PluginListenerHandle } from '@capacitor/core';\n\n/**\n * Options for picking files.\n *\n * @since 8.0.0\n */\nexport interface PickFilesOptions {\n /**\n * List of accepted MIME types or file extensions.\n * On iOS, only MIME types are supported.\n * Examples: ['image/*'], ['application/pdf'], ['.pdf', '.doc']\n */\n types?: string[];\n /**\n * Maximum number of files to pick.\n * Set to 0 for unlimited (platform default).\n * @default 0\n */\n limit?: number;\n /**\n * Whether to read the file data as base64.\n * Note: Reading large files may cause memory issues.\n * @default false\n */\n readData?: boolean;\n}\n\n/**\n * Options for picking media (images/videos).\n *\n * @since 8.0.0\n */\nexport interface PickMediaOptions {\n /**\n * Maximum number of files to pick.\n * Set to 0 for unlimited (platform default).\n * @default 0\n */\n limit?: number;\n /**\n * Whether to read the file data as base64.\n * Note: Reading large files may cause memory issues.\n * @default false\n */\n readData?: boolean;\n /**\n * iOS only: Skip transcoding of videos.\n * @default false\n */\n skipTranscoding?: boolean;\n /**\n * iOS 15+ only: Show ordered selection badges.\n * @default false\n */\n ordered?: boolean;\n}\n\n/**\n * Options for converting HEIC to JPEG.\n *\n * @since 8.0.0\n */\nexport interface ConvertHeicToJpegOptions {\n /** The path to the HEIC file to convert */\n path: string;\n /**\n * The compression quality for JPEG (0.0 - 1.0).\n * @default 0.9\n */\n quality?: number;\n}\n\n/**\n * Result of HEIC to JPEG conversion.\n *\n * @since 8.0.0\n */\nexport interface ConvertHeicToJpegResult {\n /** The path to the converted JPEG file */\n path: string;\n}\n\n/**\n * Options for copying a file.\n *\n * @since 8.0.0\n */\nexport interface CopyFileOptions {\n /** Source file path */\n from: string;\n /** Destination file path */\n to: string;\n /**\n * Whether to overwrite if destination exists.\n * @default false\n */\n overwrite?: boolean;\n}\n\n/**\n * Represents a picked file.\n *\n * @since 8.0.0\n */\nexport interface PickedFile {\n /** The name of the file */\n name: string;\n /** The path to the file */\n path?: string;\n /** The MIME type of the file */\n mimeType: string;\n /** The size of the file in bytes */\n size: number;\n /**\n * The base64 encoded data of the file.\n * Only present if readData was true.\n */\n data?: string;\n /**\n * The Blob instance of the file.\n * Web only.\n */\n blob?: Blob;\n /** Width in pixels (images/videos only) */\n width?: number;\n /** Height in pixels (images/videos only) */\n height?: number;\n /** Duration in seconds (videos only) */\n duration?: number;\n /** Last modified timestamp in milliseconds */\n modifiedAt?: number;\n}\n\n/**\n * Result of picking files.\n *\n * @since 8.0.0\n */\nexport interface PickFilesResult {\n /** Array of picked files */\n files: PickedFile[];\n}\n\n/**\n * Result of picking a directory.\n *\n * @since 8.0.0\n */\nexport interface PickDirectoryResult {\n /** The path to the selected directory */\n path: string;\n}\n\n/**\n * Permission status for file access.\n *\n * @since 8.0.0\n */\nexport interface PermissionStatus {\n /**\n * Whether broad external storage or media permission is granted.\n * Picker APIs that return user-selected files usually do not require this on Android 13+.\n */\n readExternalStorage: PermissionState;\n /** Whether permission to access media location is granted */\n accessMediaLocation?: PermissionState;\n}\n\n/**\n * Permission state values.\n *\n * @since 8.0.0\n */\nexport type PermissionState = 'prompt' | 'prompt-with-rationale' | 'granted' | 'denied';\n\n/**\n * Listener callback for picker dismissed event.\n *\n * @since 8.0.0\n */\nexport type PickerDismissedListener = (event: null) => void;\n\n/**\n * Capacitor File Picker Plugin interface for selecting files, images, videos, and directories.\n *\n * @since 8.0.0\n */\nexport interface CapgoFilePickerPlugin {\n /**\n * Pick one or more files from the device.\n *\n * @param options - Options for picking files\n * @returns Promise that resolves with the picked files\n * @since 8.0.0\n * @example\n * ```typescript\n * const result = await CapgoFilePicker.pickFiles({\n * types: ['application/pdf', 'image/*'],\n * limit: 5,\n * readData: false\n * });\n * console.log('Picked files:', result.files);\n * ```\n */\n pickFiles(options?: PickFilesOptions): Promise<PickFilesResult>;\n\n /**\n * Pick one or more images from the gallery.\n * Android/iOS only.\n *\n * @param options - Options for picking images\n * @returns Promise that resolves with the picked images\n * @since 8.0.0\n * @example\n * ```typescript\n * const result = await CapgoFilePicker.pickImages({\n * limit: 10,\n * readData: false\n * });\n * console.log('Picked images:', result.files);\n * ```\n */\n pickImages(options?: PickMediaOptions): Promise<PickFilesResult>;\n\n /**\n * Pick one or more videos from the gallery.\n * Android/iOS only.\n *\n * @param options - Options for picking videos\n * @returns Promise that resolves with the picked videos\n * @since 8.0.0\n * @example\n * ```typescript\n * const result = await CapgoFilePicker.pickVideos({\n * limit: 3,\n * skipTranscoding: true\n * });\n * console.log('Picked videos:', result.files);\n * ```\n */\n pickVideos(options?: PickMediaOptions): Promise<PickFilesResult>;\n\n /**\n * Pick one or more images or videos from the gallery.\n * Android/iOS only.\n *\n * @param options - Options for picking media\n * @returns Promise that resolves with the picked media files\n * @since 8.0.0\n * @example\n * ```typescript\n * const result = await CapgoFilePicker.pickMedia({\n * limit: 5,\n * readData: true\n * });\n * console.log('Picked media:', result.files);\n * ```\n */\n pickMedia(options?: PickMediaOptions): Promise<PickFilesResult>;\n\n /**\n * Pick a directory from the device.\n * Android/iOS only.\n *\n * @returns Promise that resolves with the picked directory path\n * @since 8.0.0\n * @example\n * ```typescript\n * const result = await CapgoFilePicker.pickDirectory();\n * console.log('Selected directory:', result.path);\n * ```\n */\n pickDirectory(): Promise<PickDirectoryResult>;\n\n /**\n * Convert a HEIC image to JPEG format.\n * iOS only.\n *\n * @param options - Options for the conversion\n * @returns Promise that resolves with the converted file path\n * @since 8.0.0\n * @example\n * ```typescript\n * const result = await CapgoFilePicker.convertHeicToJpeg({\n * path: '/path/to/image.heic',\n * quality: 0.9\n * });\n * console.log('Converted file:', result.path);\n * ```\n */\n convertHeicToJpeg(options: ConvertHeicToJpegOptions): Promise<ConvertHeicToJpegResult>;\n\n /**\n * Copy a file to a new location.\n *\n * @param options - Options for copying the file\n * @returns Promise that resolves when the copy is complete\n * @since 8.0.0\n * @example\n * ```typescript\n * await CapgoFilePicker.copyFile({\n * from: '/source/file.pdf',\n * to: '/destination/file.pdf',\n * overwrite: true\n * });\n * ```\n */\n copyFile(options: CopyFileOptions): Promise<void>;\n\n /**\n * Check broad storage or media permission state.\n * Picker-only flows should not gate `pickFiles()`, `pickImages()`,\n * `pickVideos()`, or `pickMedia()` on this permission on Android 13+.\n * Android only.\n *\n * @returns Promise that resolves with the permission status\n * @since 8.0.0\n * @example\n * ```typescript\n * const status = await CapgoFilePicker.checkPermissions();\n * console.log('Read permission:', status.readExternalStorage);\n * ```\n */\n checkPermissions(): Promise<PermissionStatus>;\n\n /**\n * Request broad storage or media permissions.\n * Do not request or declare `READ_MEDIA_IMAGES` or `READ_MEDIA_VIDEO`\n * only to use picker APIs. Google Play allows these permissions only\n * when picker alternatives are not sufficient for core app functionality.\n * Use `@capgo/capacitor-file-picker` picker methods instead for\n * user-selected file, image, or video access.\n * Android only.\n *\n * @returns Promise that resolves with the permission status\n * @since 8.0.0\n * @example\n * ```typescript\n * const status = await CapgoFilePicker.requestPermissions();\n * if (status.readExternalStorage === 'granted') {\n * console.log('Permission granted');\n * }\n * ```\n */\n requestPermissions(): Promise<PermissionStatus>;\n\n /**\n * Add a listener for the picker dismissed event.\n * iOS only.\n *\n * @param eventName - The event name\n * @param listenerFunc - The listener function\n * @returns Promise that resolves with the listener handle\n * @since 8.0.0\n */\n addListener(eventName: 'pickerDismissed', listenerFunc: PickerDismissedListener): Promise<PluginListenerHandle>;\n\n /**\n * Remove all listeners for this plugin.\n *\n * @since 8.0.0\n */\n removeAllListeners(): Promise<void>;\n\n /**\n * Get the native Capacitor plugin version.\n *\n * @returns Promise that resolves with the plugin version\n * @since 8.0.0\n * @example\n * ```typescript\n * const { version } = await CapgoFilePicker.getPluginVersion();\n * console.log('Plugin version:', version);\n * ```\n */\n getPluginVersion(): Promise<{ version: string }>;\n}\n"]}
|
|
@@ -11,7 +11,7 @@ import UniformTypeIdentifiers
|
|
|
11
11
|
*/
|
|
12
12
|
@objc(CapgoFilePickerPlugin)
|
|
13
13
|
public class CapgoFilePickerPlugin: CAPPlugin, CAPBridgedPlugin {
|
|
14
|
-
private let pluginVersion: String = "8.1.
|
|
14
|
+
private let pluginVersion: String = "8.1.9"
|
|
15
15
|
public let identifier = "CapgoFilePickerPlugin"
|
|
16
16
|
public let jsName = "CapgoFilePicker"
|
|
17
17
|
public let pluginMethods: [CAPPluginMethod] = [
|
package/package.json
CHANGED