DOCSEARCHbyAlgolia
Submit Docs

permission_handler

repository·main·Indexed 24 days ago

https://github.com/baseflow/flutter-permission-handler

A Flutter plugin for managing runtime permissions across Android, iOS, Web, and Windows using a federated architecture. It allows developers to request permissions, check current permission status, open device app settings, and show permission rationales on Android.

Tokens
4.5K
Snippets
11
Records
29
Agent score
79%

What's inside permission_handler

  1. Overview of flutter_permission_handler

    main

    The permission_handler plugin provides a cross-platform (iOS, Android) API for managing runtime permissions. It allows developers to:

    • Request permissions from the user while the app is running.
    • Check the current status of a permission.
    • Open the device's app settings so users can manually grant or revoke permissions.
    • Show a rationale for requesting permission on Android.

    This is necessary because most modern operating systems do not grant all permissions at install time; they must be requested during app execution.

  2. Understand the federated plugin architecture of permission_handler

    main

    The permission_handler plugin uses a federated plugin architecture. This means the functionality is split across multiple packages to allow for better platform-specific scaling:

    1. permission_handler: This is the primary app-facing package. This is the only package you need to depend on in your Flutter project to use the plugin. It currently includes the Android and iOS platform implementations.
    2. permission_handler_platform_interface: This package defines the interface that all platform-specific implementations must follow. It ensures compatibility between the app-facing package and various platform packages.
    3. Platform Packages: Future support for other platforms will be provided via individual platform packages that implement the interface defined in the permission_handler_platform_interface package.

  3. Implement a new platform for permission_handler

    main

    To add support for a new platform in the permission_handler ecosystem, you must implement the platform interface.

    1. Extend the PermissionHandlerPlatform class with your platform-specific implementation.
    2. Implement the required platform-specific behaviors within your class.
    3. Register your implementation by setting it as the default instance during plugin registration using PermissionHandlerPlatform.instance = YourPlatformImplementation().

  6. Configure Android permissions and AndroidX

    main

    To use permission_handler on Android, you must ensure your project is configured for AndroidX and has the necessary permissions in your AndroidManifest.xml.

    1. AndroidX Setup

    Add the following to your gradle.properties file:

    android.useAndroidX=true
android.enableJetifier=true

    Ensure your android/app/build.gradle file has a compileSdkVersion of at least 35:

    android {
  compileSdkVersion 35
  ...
}

    2. Add Permissions

    Add the required permissions to your AndroidManifest.xml (typically the main version). You can find a complete list of possible permissions in the plugin's example AndroidManifest.xml.

  7. Install permission_handler_windows via permission_handler

    main
    Starting from version 9.2.0 of the permission_handler plugin, permission_handler_windows is the endorsed Windows implementation. It is automatically added to your project's dependencies when you include permission_handler: ^9.2.0 in your pubspec.yaml file. You do not need to add permission_handler_windows manually if you are using a compatible version of the main plugin.

  8. Configure iOS permissions with CocoaPods

    main

    When using CocoaPods, you must explicitly enable permissions using macros in your Podfile and add the corresponding usage descriptions to your Info.plist.

    1. Update Podfile

    Add the desired permissions to the post_install block in your Podfile. Set the value to 1 to enable a permission and 0 to disable it.

    2. Update Info.plist

    For every permission enabled in the Podfile (set to 1), you must add the corresponding usage description key to your Info.plist. If you enable a permission in the Podfile but omit the key in Info.plist, your app may fail Apple's static analysis during submission.

    3. Clean and Rebuild

    After modifying the Podfile, perform a clean and rebuild of your project.

    post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)

    target.build_configurations.each do |config|
      config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
        '$(inherited)',

        ## dart: PermissionGroup.camera
        'PERMISSION_CAMERA=1',

        ## dart: PermissionGroup.microphone
        'PERMISSION_MICROPHONE=1',
      ]
    end
  end
end

  9. Configure iOS permissions with Swift Package Manager (SPM)

    main

    If you are using Flutter 3.24.0+ and Xcode 15.0+ with Swift Package Manager, permissions are enabled automatically by detecting the usage description keys in your Info.plist.

    1. Add Info.plist Keys

    Add the corresponding key for the permission you need to your Info.plist. For example, to use the camera, add NSCameraUsageDescription.

    2. Handle Special Cases

    Some permissions require environment variables during the build process:

    • PermissionGroup.notification: Enabled by default. To disable it, set PERMISSION_NOTIFICATIONS=0.
    • PermissionGroup.criticalAlerts: Disabled by default. To enable it, set PERMISSION_CRITICAL_ALERTS=1.

    Build Commands:

    From Terminal:

    # To disable notifications
export PERMISSION_NOTIFICATIONS=0

# To enable critical alerts
export PERMISSION_CRITICAL_ALERTS=1

    From Xcode GUI:

    # To disable notifications
launchctl setenv PERMISSION_NOTIFICATIONS 0

# To enable critical alerts
launchctl setenv PERMISSION_CRITICAL_ALERTS 1

    Note: After changing environment variables or Info.plist keys, clear the Xcode cache with rm -rf ~/Library/Developer/Xcode/DerivedData before rebuilding.

    export PERMISSION_NOTIFICATIONS=0

  11. Customize the iOS launch screen assets

    main

    To change the launch screen image for the iOS version of your Flutter app, you can use one of two methods:

    1. Direct File Replacement: Replace the existing image files located in the permission_handler/example/ios/Runner/Assets.xcassets/LaunchImage.imageset/ directory with your own assets.
    2. Xcode Interface:
      • Open your Flutter project's iOS workspace using open ios/Runner.xcworkspace.
      • In the Xcode Project Navigator, navigate to Runner/Assets.xcassets.
      • Drag and drop your desired images into the asset catalog.
    open ios/Runner.xcworkspace