Add support for platform-specific app permissions

[freakboy3742]

Is your feature request related to a problem? Please describe.

Some platforms (most notably mobile platforms, but desktop platforms are moving in a similar direction) have explicit permissions for accessing certain hardware features, such as:

• Geolocation
• Network access
• File system access
• Camera access
• Accelerometer
• Push notifications

At present, Briefcase provides no way to customise these permissions when rolling out an app.

Describe the solution you'd like

We should add a configuration parameter that can be used to inject permissions into the app template. Suggested format:

[tool.briefcase.app.helloworld.iOS.permissions]

NSCameraUsageDescription = "Helloworld will use your camera to take pictures of cats"

In this example asking for access to the camera on iOS, the key is the platform-specific permission, and the value is a short explanation for why the permission is required. The explanatory text is required on iOS and macOS; it does not appear to be required on Android, but could still serve as useful documentation.

These definitions would then be passed to the app template, and injected as required.

Two "stretch" goals that might be worth considering:

1. "Universal" permission aliases Every platform has permissions for accessing the camera, geolocation, and so on. It may be worth establishing a "Briefcase alias" for these universal permissions, which is mapped to the platform specific name (or names) as required. That way, you could ask for camera permission, rather than needing to know the platform-specific name of each permission.

2. Extracting required permissions from library metadata Manually defining permissions is simple from an implementation perspective, but doesn't lead to a good user experience. It is reasonable to expect that first-time app developers won't understand why their app doesn't work when they're calling a camera API, but haven't manually added permissions. Ideally, we would be able to determine the permissions required based on the libraries that are used. For example, a toga-camera library would declare in library metadata that it requires the camera permission, and that would be automatically injected into the app template. The explanatory text associated with that permission would need to be a placeholder; however, we can provide placeholder text, and warn the user that placeholder text has been provided and should be overridden (in a similar way to how default icons are currently used and a warning provided).

However, regardless of whether we hit these stretch goals, a framework for platform-specific permissions will be required. This is because OS release schedules are decoupled from Briefcase release schedules; a new OS may introduce new permissions (or alter permission semantics); and we need to be able to support those permissions without requiring a new Briefcase release.

Describe alternatives you've considered

The current alternative is to:

1. manually modify the generated project generated by briefcase create
2. develop a custom platform template that includes the required permissions

(1) isn't persistent between app builds; (2) requires more effort than should be required.

[ecmel]

This is a much needed feature

[gauravghodinde]

isn't there a way to give permissions to apps on android?

[mhsmith]

@gauravghodinde: Currently the only way is to manually edit the AndroidManifest file in the generated project. Note that this will be overwritten every time you run briefcase create android.

[mhsmith]

#472 contains ideas for how we could update a template without regenerating the whole project and forcing a full rebuild.

[yousifamanuel]

I would like to know if this feature will be added within next year

[mhsmith]

That depends on how many people need it. If anyone wants this feature, please post the following information:

• which platform your app runs on
• what you're trying to achieve
• which permission you need

[yousifamanuel]

Thank you for responding.

• which platform your app runs on Android
• what you're trying to achieve Accessing the camera to read bar and QR codes
• which permission you need Camera and Memory permission

[mhsmith]

Thanks: that's a common use case, so it'll be one of the first things we look at in this area.

[yousifamanuel]

thank you; that would be great. I would like to use the Beeware framework in an university course to teach student agile project management. This decision was made so we can move from Android Studio which needs more resources and computational power to run.

[mhsmith]

We could support Android permissions and various other customizations by adding a manifest_extra_content option in the pyproject.toml file, similar to build_gradle_extra_content which was added in https://github.com/beeware/briefcase-android-gradle-template/pull/57.

However, this would be more difficult than the Dockerfile and build.gradle cases, because you can't simply concatenate two XML files: they would need to be merged.

Also, simply adding a permission to the manifest isn't enough: you also need ask the user to grant it at runtime. So this would be much easier if there was a higher-level API as mentioned above.