feat: Return Content URI in saveMedia for Android #104

Description

Currently, the saveMedia method in the Capacitor-Media plugin returns only the file's absolute path (file://). However, Android restricts the use of file:// URIs for sharing files between apps, requiring a content:// URI instead. This feature request proposes adding support for returning a content:// URI when saving media on Android.

Use Case

1. File Sharing Between Apps:

   • When media is saved via saveMedia, it is often shared with other apps. Returning a content:// URI would make it easier to share files securely without triggering a FileUriExposedException.

2. Compliance with Android Scoped Storage:

   • content:// URIs align with Android's Scoped Storage policies, ensuring compatibility with modern Android versions.

3. Reduce Overhead for Developers:

   • Currently, developers need to manually generate a content:// URI from the returned file path. Returning a content:// URI directly simplifies the workflow.

Suggested Implementation

Android Implementation

Modify the saveMedia method to return both the absolute file path (file://) and the content:// URI.

import androidx.core.content.FileProvider;

try {
    File expFile = copyFile(inputFile, albumDir, fileName);
    scanPhoto(expFile);

    // Generate the content URI using FileProvider
    Uri contentUri = FileProvider.getUriForFile(
        getContext(),
        getContext().getPackageName() + ".fileprovider",
        expFile
    );

    // Return both file path and content URI
    JSObject result = new JSObject();
    result.put("filePath", expFile.toString());  // Absolute file path
    result.put("contentUri", contentUri.toString());  // Content URI
    call.resolve(result);
} catch (RuntimeException e) {
    call.reject("Error saving media", e);
}

Example Return Value

When the method resolves successfully, the returned object could look like this:

{
  "filePath": "/storage/emulated/0/Android/media/com.example.app/Example/IMG_20241213_165249028.jpeg",
  "contentUri": "content://com.example.app.fileprovider/media_files/IMG_20241213_165249028.jpeg"
}

API Changes

No breaking changes are introduced. The existing filePath property remains, and a new property contentUri is added for additional functionality.

Expected Behavior

• Existing functionality: The method continues to return the absolute file path (filePath) for backward compatibility.
• New functionality: Adds the contentUri field to provide a content:// URI for better compatibility and ease of use.

Platform Support

• Android: Full support for content:// URIs using FileProvider.
• iOS: Not applicable, as iOS doesn't use content URIs.

Conclusion

Adding support for returning content:// URIs in saveMedia enhances the Capacitor-Media plugin by aligning it with modern Android storage policies. It simplifies file-sharing workflows for developers and ensures better compatibility with other apps and Android versions.

If you need further clarification or additional details, feel free to ask! 😊