9 changed files with 1176 additions and 20 deletions
@ -0,0 +1,251 @@ |
|||
# Android File Saver Plugin Implementation Guide |
|||
|
|||
## Overview |
|||
|
|||
This document outlines the implementation of the `AndroidFileSaver` Capacitor plugin that provides Storage Access Framework (SAF) and MediaStore functionality for direct file saving on Android devices. |
|||
|
|||
## Plugin Purpose |
|||
|
|||
The `AndroidFileSaver` plugin enables two key file operations: |
|||
1. **`saveToDownloads`**: Direct save to Downloads folder using MediaStore (API 29+) |
|||
2. **`saveAs`**: User-chosen location using Storage Access Framework (SAF) |
|||
|
|||
## Implementation Requirements |
|||
|
|||
### 1. Plugin Structure |
|||
|
|||
```typescript |
|||
// Plugin interface |
|||
interface AndroidFileSaverPlugin { |
|||
saveToDownloads(options: { |
|||
fileName: string; |
|||
content: string; |
|||
mimeType: string |
|||
}): Promise<{ |
|||
success: boolean; |
|||
path?: string; |
|||
error?: string |
|||
}>; |
|||
|
|||
saveAs(options: { |
|||
fileName: string; |
|||
content: string; |
|||
mimeType: string |
|||
}): Promise<{ |
|||
success: boolean; |
|||
path?: string; |
|||
error?: string |
|||
}>; |
|||
} |
|||
``` |
|||
|
|||
### 2. Android Implementation |
|||
|
|||
#### MediaStore for Downloads (API 29+) |
|||
|
|||
```java |
|||
@PluginMethod |
|||
public void saveToDownloads(PluginCall call) { |
|||
String fileName = call.getString("fileName"); |
|||
String content = call.getString("content"); |
|||
String mimeType = call.getString("mimeType"); |
|||
|
|||
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) { |
|||
// Use MediaStore for Downloads |
|||
ContentValues values = new ContentValues(); |
|||
values.put(MediaStore.Downloads.DISPLAY_NAME, fileName); |
|||
values.put(MediaStore.Downloads.MIME_TYPE, mimeType); |
|||
values.put(MediaStore.Downloads.IS_PENDING, 1); |
|||
|
|||
ContentResolver resolver = getContext().getContentResolver(); |
|||
Uri uri = resolver.insert(MediaStore.Downloads.EXTERNAL_CONTENT_URI, values); |
|||
|
|||
if (uri != null) { |
|||
try (ParcelFileDescriptor pfd = resolver.openFileDescriptor(uri, "w")) { |
|||
if (pfd != null) { |
|||
try (FileOutputStream fos = new FileOutputStream(pfd.getFileDescriptor())) { |
|||
fos.write(content.getBytes()); |
|||
fos.flush(); |
|||
|
|||
// Mark as no longer pending |
|||
values.clear(); |
|||
values.put(MediaStore.Downloads.IS_PENDING, 0); |
|||
resolver.update(uri, values, null, null); |
|||
|
|||
call.resolve(new JSObject() |
|||
.put("success", true) |
|||
.put("path", uri.toString())); |
|||
return; |
|||
} |
|||
} |
|||
} catch (IOException e) { |
|||
resolver.delete(uri, null, null); |
|||
} |
|||
} |
|||
|
|||
call.resolve(new JSObject() |
|||
.put("success", false) |
|||
.put("error", "Failed to save file")); |
|||
} else { |
|||
// Fallback for older Android versions |
|||
call.resolve(new JSObject() |
|||
.put("success", false) |
|||
.put("error", "Requires Android API 29+")); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
#### Storage Access Framework (SAF) for Save As |
|||
|
|||
```java |
|||
@PluginMethod |
|||
public void saveAs(PluginCall call) { |
|||
String fileName = call.getString("fileName"); |
|||
String content = call.getString("content"); |
|||
String mimeType = call.getString("mimeType"); |
|||
|
|||
// Store call for later use |
|||
bridge.saveCall(call); |
|||
|
|||
// Create intent for SAF |
|||
Intent intent = new Intent(Intent.ACTION_CREATE_DOCUMENT); |
|||
intent.addCategory(Intent.CATEGORY_OPENABLE); |
|||
intent.setType(mimeType); |
|||
intent.putExtra(Intent.EXTRA_TITLE, fileName); |
|||
|
|||
// Start activity for result |
|||
bridge.startActivityForResult(call, intent, "saveAsResult"); |
|||
} |
|||
|
|||
@ActivityCallback |
|||
private void saveAsResult(PluginCall call, ActivityResult result) { |
|||
if (result.getResultCode() == Activity.RESULT_OK && result.getData() != null) { |
|||
Uri uri = result.getData().getData(); |
|||
String content = call.getString("content"); |
|||
|
|||
try (ParcelFileDescriptor pfd = getContext().getContentResolver() |
|||
.openFileDescriptor(uri, "w")) { |
|||
if (pfd != null) { |
|||
try (FileOutputStream fos = new FileOutputStream(pfd.getFileDescriptor())) { |
|||
fos.write(content.getBytes()); |
|||
fos.flush(); |
|||
|
|||
call.resolve(new JSObject() |
|||
.put("success", true) |
|||
.put("path", uri.toString())); |
|||
return; |
|||
} |
|||
} |
|||
} catch (IOException e) { |
|||
// Handle error |
|||
} |
|||
|
|||
call.resolve(new JSObject() |
|||
.put("success", false) |
|||
.put("error", "Failed to save file")); |
|||
} else { |
|||
call.resolve(new JSObject() |
|||
.put("success", false) |
|||
.put("error", "User cancelled or failed")); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### 3. Plugin Registration |
|||
|
|||
```java |
|||
@CapacitorPlugin(name = "AndroidFileSaver") |
|||
public class AndroidFileSaverPlugin extends Plugin { |
|||
// Implementation methods here |
|||
} |
|||
``` |
|||
|
|||
## Integration Steps |
|||
|
|||
### 1. Create Plugin Project |
|||
|
|||
```bash |
|||
# Create new Capacitor plugin |
|||
npx @capacitor/cli plugin:generate android-file-saver |
|||
cd android-file-saver |
|||
``` |
|||
|
|||
### 2. Add to Android Project |
|||
|
|||
```bash |
|||
# In your main project |
|||
npm install ./android-file-saver |
|||
npx cap sync android |
|||
``` |
|||
|
|||
### 3. Update Android Manifest |
|||
|
|||
Ensure the following permissions are present: |
|||
|
|||
```xml |
|||
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" |
|||
android:maxSdkVersion="28" /> |
|||
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" |
|||
android:maxSdkVersion="32" /> |
|||
``` |
|||
|
|||
## Fallback Behavior |
|||
|
|||
When the plugin is not available, the system falls back to: |
|||
1. **Web**: Browser download mechanism |
|||
2. **Electron**: Native file save via IPC |
|||
3. **Capacitor**: Share dialog (existing behavior) |
|||
|
|||
## Testing |
|||
|
|||
### 1. Plugin Availability |
|||
|
|||
```typescript |
|||
// Check if plugin is available |
|||
if (AndroidFileSaver) { |
|||
// Plugin available - use native methods |
|||
} else { |
|||
// Plugin not available - use fallback |
|||
} |
|||
``` |
|||
|
|||
### 2. Error Handling |
|||
|
|||
```typescript |
|||
try { |
|||
const result = await AndroidFileSaver.saveToDownloads({ |
|||
fileName: "test.json", |
|||
content: '{"test": "data"}', |
|||
mimeType: "application/json" |
|||
}); |
|||
|
|||
if (result.success) { |
|||
logger.info("File saved:", result.path); |
|||
} else { |
|||
logger.error("Save failed:", result.error); |
|||
} |
|||
} catch (error) { |
|||
logger.error("Plugin error:", error); |
|||
} |
|||
``` |
|||
|
|||
## Security Considerations |
|||
|
|||
1. **Content Validation**: Validate file content before saving |
|||
2. **MIME Type Verification**: Ensure MIME type matches file content |
|||
3. **Permission Handling**: Request storage permissions appropriately |
|||
4. **Error Logging**: Log errors without exposing sensitive data |
|||
|
|||
## Future Enhancements |
|||
|
|||
1. **Progress Callbacks**: Add progress reporting for large files |
|||
2. **Batch Operations**: Support saving multiple files |
|||
3. **Custom Locations**: Allow saving to app-specific directories |
|||
4. **File Compression**: Add optional file compression |
|||
|
|||
## References |
|||
|
|||
- [Android Storage Access Framework](https://developer.android.com/guide/topics/providers/document-provider) |
|||
- [MediaStore Downloads](https://developer.android.com/reference/android/provider/MediaStore.Downloads) |
|||
- [Capacitor Plugin Development](https://capacitorjs.com/docs/plugins/android) |
|||
- [Android Scoped Storage](https://developer.android.com/training/data-storage) |
|||
Loading…
Reference in new issue