flutter-force-permission

Show permission disclosure page and allows required permissions and their associated services before the user can proceed.

This package shows a prominent in-app disclosure page for getting permissions as required by Google Play . Also support iOS to ensure a consistent experience.

In addition, permissions and their associated services (e.g. GPS) can be set as "required". If this is set, those required permissions will be required and if users denied it, this package will show a customizable dialog and redirect user to the appropriate settings page provided by the native OS.

Setup

1. Add the following to pubspec.yaml

dependencies:
  flutter_force_permission: ^0.1.0
  # Currently this package depends on our `flutter-permission-handler` package to fix an iOS issue.
  # Directly depends on our packages to avoid any pubspec dependency resolving failure.
  # Track the PR at: https://github.com/Baseflow/flutter-permission-handler/pull/967
  # TODO replace once we upload our packages and our PR merged by Baseflow.
  permission_handler:
     git:
        url: https://github.com/gogovan/flutter-permission-handler.git
        ref: master
        path: permission_handler
  permission_handler_apple:
     git:
        url: https://github.com/gogovan/flutter-permission-handler.git
        ref: master
        path: permission_handler_apple

# TODO replace once we upload our packages and our PR merged by Baseflow.
dependency_overrides:
   permission_handler_apple:
      git:
         url: https://github.com/gogovan/flutter-permission-handler.git
         ref: master
         path: permission_handler_apple

2. This package depends on permission_handler. Perform setup according to that package.
3. On Android, if you use POST_NOTIFICATIONS permission, update the targetSdkVersion in build.gradle to at least 33 so that the permission request dialog is shown correctly. Refer to relevant Android Developer page for details.

android {
    // ...
    defaultConfig {
        compileSdkVersion 33
        targetSdkVersion 33
        // ...
    }
    // ...
}

4. If any features is required, it is highly recommended to also set the <uses-feature> tag in AndroidManifest.xml. Refer to relevant Android Developers page for details.

Usage

1. Create an instance of FlutterForcePermission, providing configuration. Refer to documentation of [FlutterForcePermissionConfig] for configuration details. Use a single instance of FlutterForcePermission throughout your app.

final perm = FlutterForcePermission(
  FlutterForcePermissionConfig(
    title: 'Title',
    permissionItemConfigs: [
      PermissionItemConfig(
        permissions: [Permission.locationWhenInUse],
        required: PermissionRequiredOption.required,
        itemText: PermissionItemText(
          header: 'Foreground Location',
          rationaleText: 'Rationale for Foreground location. Required.',
          forcedPermissionDialogConfig: ForcedPermissionDialogConfig(
            title: 'Please enable location permission',
            text: 'Please enable location permission for proper usage.',
            buttonText: 'Settings',
          ),
        ),
      ),
      PermissionItemConfig(
        permissions: [Permission.locationAlways],
        itemText: PermissionItemText(
          header: 'Background Location',
          rationaleText: 'Rationale for Background location. lorem ipsum dolor sit amet.',
        ),
      ),
    ],
  ),
);

2. Show the disclosure page as needed. This method will handle showing the disclosure page and requesting permissions. This function takes a BuildContext. This is an async function. Wrap the function in an async block as needed. Returns a map of permission and their requested status ( granted/denied/etc), service status and whether they are requested by this plugin.

final result = await perm.show(context);

Styling

You can set the styles by providing a ThemeData in the configuration.

• elevatedButtonTheme.style is used for the primary button.
• primaryColor is used for as the color of the icons.
• Title uses titleLarge text style.
• Item header use titleMedium text style.
• Item body use bodyMedium text style.

Advanced Usage

Customize the required permission denied prompt

If you wish to customize the dialog shown when the required permission is denied, provide a showDialogCallback which to show your dialog. Parameters are included for you to compose the appropriate dialog. In your callback, you SHOULD:

1. Display a non-dismissable dialog. This can be typically achieved by setting barrierDismissible to false and provide an empty callback e.g. (() async => false) to willPopCallback for your dialog.
2. Call the provided callback parameter in your callback when the user click the confirm button, and dismiss your dialog by Navigator.pop.

final config = FlutterForcePermissionConfig(
  title: 'Title',
  confirmText: 'Confirm',
  permissionItemConfigs: [
    PermissionItemConfig(
      permissions: [
        Permission.location,
      ],
      itemText: PermissionItemText(
        header: 'Foreground location',
        rationaleText: 'Rationale',
        forcedPermissionDialogConfig: ForcedPermissionDialogConfig(
          title: 'Location required',
          text: 'Location needed for proper operation',
          buttonText: 'Settings',
        ),
      ),
      required: PermissionRequiredOption.required,
    ),
  ],
  showDialogCallback: (context, option, permConfig, callback) {
    // Show your dialog.
    showDialog(context: context,
      barrierDismissible: false,
      builder: (context) =>
          WillPopScope(
            onWillPop: () async => false, // Prevent dismissing dialog by tapping outside the dialog or the back button.
            child: AlertDialog(
              title: Text(permConfig.forcedPermissionDialogConfig.title),
              content: Text(permConfig.forcedPermissionDialogConfig.text),
              actions: [
                TextButton(
                  onPressed: () {
                    // Remember to invoke `callback` after confirm action to show the OS settings page as appropriate. 
                    callback();
                    // !IMPORTANT!: You MUST use the BuildContext provided by the dialog when using the navigator, NOT the BuildContext provided by the callback.
                    // Failure of doing so will result in unintended behavior.
                    Navigator.pop(context);
                  },
                  child: Text(permConfig.forcedPermissionDialogConfig.buttonText),
                ),
              ],
            ),
          ),
    );
  },
);

Known Issues

• Currently it depends on our fork of flutter-permission-handler instead of the original to fix an issue for iOS. You may track the issue and pull request here.

Issues

Contributing