Mobile Permissions Support

[mcmah309]

Feature Request

Currently, there is no way to request or manage permissions on mobile platforms in Dioxus applications. This affects critical functionality such as camera access, location services, file system access, and other platform capabilities that require user permission.

Background

Mobile applications require permissions to access sensitive device features and user data. Both Android and iOS have their own permission systems that differ significantly in implementation but serve the same purpose of protecting user privacy.

Platform Requirements

Android Permission System

Android uses a dual-layer permission system:

1. Manifest Declaration: All permissions must be declared in AndroidManifest.xml

2. Runtime Requests: Permissions are categorized by protection level:

   • Normal Permissions (automatically granted at install, no runtime request needed):

     • android.permission.INTERNET
     • android.permission.ACCESS_NETWORK_STATE
     • android.permission.VIBRATE
     • android.permission.SET_ALARM

   • Dangerous Permissions (require runtime request):

     • android.permission.CAMERA
     • android.permission.READ_CONTACTS
     • android.permission.ACCESS_FINE_LOCATION
     • android.permission.READ_EXTERNAL_STORAGE
     • android.permission.RECORD_AUDIO

   • Special Permissions (require specific handling):

     • android.permission.SYSTEM_ALERT_WINDOW
     • android.permission.WRITE_SETTINGS

Android provides a unified permission request API that works consistently across different permission types.

iOS Permission System

iOS has a different approach:

1. Info.plist Declarations: All privacy-sensitive permissions must be declared in Info.plist with appropriate usage description strings (explaining why the app needs the permission)

2. Per-Permission APIs: Unlike Android, iOS uses separate APIs for each permission type:

   • Camera access uses AVCaptureDevice.requestAccess(for:)
   • Location uses CLLocationManager.requestWhenInUseAuthorization()
   • Photo library uses PHPhotoLibrary.requestAuthorization()
   • Each with their own callback patterns

3. Usage Descriptions: Every permission requires a corresponding entry in Info.plist:

   • NSCameraUsageDescription
   • NSPhotoLibraryUsageDescription
   • NSLocationWhenInUseUsageDescription
   • And many others

4. Special Entitlements: Some iOS capabilities require additional entitlements beyond Info.plist entries:

   • Push Notifications
   • Apple Pay
   • iCloud
   • App Groups
   • Background Modes

Platform-Specific Permissions

Each platform has unique permissions that don't exist on the other:

Android-only Permissions:

• android.permission.SYSTEM_ALERT_WINDOW
• android.permission.READ_SMS / android.permission.RECEIVE_SMS
• android.permission.READ_PHONE_STATE
• android.permission.WRITE_SETTINGS
• android.permission.REQUEST_INSTALL_PACKAGES

iOS-only Permissions:

• Tracking Authorization (NSUserTrackingUsageDescription)
• Local Network (NSLocalNetworkUsageDescription)
• Critical Alerts (UNAuthorizationOptionCriticalAlert)
• Face ID/Touch ID (NSFaceIDUsageDescription)
• Photo Library Additions (NSPhotoLibraryAddUsageDescription)

Proposed Implementation

Due to the specific platform needs and evolving technologies, it may be best to expose AndroidManifest.xml and Info.plist to be used in the compiled platform projects. There should be a unified native experience for permissions. Maybe something like

let result = dioxus::mobile::android::require_permission(AndroidPermission::SystemAlertWindow); // platform specific
...
let result = dioxus::mobile::ios::require_permission(IosPermission::TrackingAuthorization); // platform specifc, corresponds to NSUserTrackingUsageDescription in Info.plist
...
let result = dioxus::mobile::require_permission(Permission::CAMERA); // cross platform

Which is can be used as guards that prompt the user for permission if not already granted.

Documentation Strategy

We should provide:

• Comprehensive API documentation for all permission-related functions
• Feature-based guides (e.g., "Using the Camera in Dioxus Mobile")
• Platform-specific permission best practices
• Examples demonstrating proper permission flow handling

Alternative Implementation

A fully unified permission API in Cargo.toml or dioxus.toml would be simpler for developers but wouldn't adequately address platform-specific requirements. Even with a unified configuration approach for common permissions, exposing direct access to platform configuration files is necessary for advanced use cases. Also the merging of generated platform files with user-provided configurations introduces complexity and potential conflicts.

Unanswered Questions

How should libraries that require permissions interact with downstream applications? Maybe simply recommending including a section in the README for configuring AndroidManifest.xml and Info.plist is enough.

Prior Art

• https://crates.io/crates/crossbow
• https://v2.tauri.app/security/permissions/
• Config for setting Android Manifest permissions  #3535

[DogeDark]

We've thought about this lately and my own thoughts are that we need to expose the files themselves (AndroidManifest.xml & Info.plist), but I would also like a way to merge and propagate permission requirements automatically from dependencies (such as SDK). The latter would likely require Manganis.

It is good to know that Info.plist requires permission usage descriptors.

[mcmah309]

Some considerations -

On android, uses-permission/permission is a direct descendant of manifest and on IOS permissions are also a direct descendant of dict so merging would not be too complex. For both android and IOS, I believe when duplicates are encountered, the last one takes Precedence. Beyond duplicates it would probably be best if the entries themselves could be merged, though the correct behavior of merging may be complicated. E.g. Assume two libraries with the following

<uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation" />

<uses-permission android:name="android.permission.BLUETOOTH_SCAN"  />

These can't really be merged since the later may use bluetooth for location. Another consideration is Info.plist descriptors on IOS are also shown to the user.

Thus for merging solution, the most correct and maintainable solution might be to fail building on such conflicts with a conflict reason and have the user manually specify them in their config file. This would also mean that resolution needs to be done in reverse breadth first order. A downside to this is that permission files start to become spaghetti with some permissions needed by the application, some needed for conflict resolution from libraries, and others not specified but will be applied when merging.

That said, maybe the easiest and most correct solution is not to do merging and propagation. Another reason for this: E.g. A library may have have bluetooth functionality, but a downstream application never uses that, so it actually does not need <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />. Also considering libraries will likely have feature flags where some permissions may be needed and others not, this is probable.