[flutter_local_locations] added ability to request permission to schedule exact alarms and updated permissions and receivers in plugins' manifest file (#2052)

* added the ability to request the permission to schedule exact alarms

* updated Android side of plugin to only request the minimum permissions via the AndroidManifest.xml file

* Google Java Format

* added details to AndroidManifest.xml section of readme that developers can refer to example app

* updated details underneath Android setup section of readme to draw attention to Android 14 changes

* added test to verify requestExactAlarmsPermission call

* added note to changelog around Android 14 changes to do with exact alarms and link to issue raised on GitHub repo

---------

Co-authored-by: github-actions <>

Author: MaikuB

flutter_local_notifications/CHANGELOG.md

@@ -1,3 +1,9 @@
+# [16.0.0-dev.1]
+
+* [Android] **Breaking changes** the plugin now only declares the bare minimum in its `AndroidManifest.xml`. This means applications making use of either scheduled notifications, full-screen intent notifications or notification actions will now require changes in the application's own `AndroidManifest.xml` file. Please check the [AndroidManifest.xml setup](https://pub.dev/packages/flutter_local_notifications#androidmanifestxml-setup) section of the readme for more details. The reason this was done was because not all applications will leverage all of the plugin's features. Doing this will now allow applications to only request the appropriate permissions needed for their application. This addresses issue [1687](https://github.com/MaikuB/flutter_local_notifications/issues/1687)
+* [Android] added the ability to request permission to schedule exact alarms via the `requestExactAlarmsPermission()` method that has been added to the `AndroidFlutterLocalNotificationsPlugin` class that represents the Android implementation of the plugin. This has been done in response to behaviour changes introduced in Android 14 (API level 34) when comes to using exact alarms. See the official documentation about these changes [here](https://developer.android.com/about/versions/14/changes/schedule-exact-alarms). This change addresses issue [1906](https://github.com/MaikuB/flutter_local_notifications/issues/1906)
+
+
 # [15.1.0+1]
 
 * Fixed formatting of 15.1.0 changelog entry

flutter_local_notifications/README.md

@@ -23,6 +23,7 @@ A cross platform plugin for displaying local notifications.
 - **[👏 Acknowledgements](#-acknowledgements)**
 - **[🔧 Android Setup](#-android-setup)**
    - [Gradle setup](#gradle-setup)
+   - [AndroidManifest.xml setup](#androidmanifestxml-setup)
    - [Requesting permissions on Android 13 or higher](#requesting-permissions-on-android-13-or-higher)
    - [Custom notification icons and sounds](#custom-notification-icons-and-sounds)
    - [Scheduled notifications](#scheduling-a-notification)
@@ -171,7 +172,7 @@ Due to some limitations on iOS with how it treats null values in dictionaries, a
 
 ## 🔧 Android Setup
 
-Before proceeding, please make sure you are using the latest version of the plugin. The reason for this is that since version 3.0.1+4, the amount of setup needed has been reduced. Previously, applications needed changes done to the `AndroidManifest.xml` file and there was a bit more setup needed for release builds. If for some reason, your application still needs to use an older version of the plugin then make use of the release tags to refer back to older versions of readme.
+Before proceeding, please make sure you are using the latest version of the plugin. Note that there have been differences in the setup depending on the version of the plugin used. Please make use of the release tags to refer back to older versions of readme. Applications that schedule notifications should pay close attention to the [AndroidManifest.xml setup](#androidmanifestxml-setup) section of the readme since Android 14 has brought about some behavioural changes.
 
 ### Gradle setup
 
@@ -230,6 +231,35 @@ android {
 }
 ```
 
+### AndroidManifest.xml setup
+
+Previously the plugin would specify all the permissions required all of the features that the plugin support in its own `AndroidManifest.xml` file so that developers wouldn't need to do this in their own app's `AndroidManifest.xml` file. Since version 16 onwards, the plugin will now only specify the bare minimum and these [`POST_NOTIFICATIONS`] (https://developer.android.com/reference/android/Manifest.permission#POST_NOTIFICATIONS) and [`VIBRATE`](https://developer.android.com/reference/android/Manifest.permission#VIBRATE) permissions.
+
+For apps that need the following functionality please the following in your app's `AndroidManifest.xml`
+
+* To schedule notifications the following changes are needed
+    * Specify the appropriate permissions between the `<manifest>` tags.
+        * `<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>`: this is required so the plugin can known when the device is rebooted. This is required so that the plugin can reschedule notifications upon a reboot
+        * If the app requires scheduling notifications with exact timings (aka exact alarms), there are two options since Android 14 brought about behavioural changes (see [here](https://developer.android.com/about/versions/14/changes/schedule-exact-alarms) for more details)
+            * specify `<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />` and call the `requestExactAlarmsPermission()` exposed by the `AndroidFlutterNotificationsPlugin` class so that the user can grant the permission via the app or
+            * specify `<uses-permission android:name="android.permission.USE_EXACT_ALARM" />`. Users will not be prompted to grant permission, however as per the official Android documentation on the `USE_EXACT_ALARM` permission (refer to [here](https://developer.android.com/about/versions/14/changes/schedule-exact-alarms#calendar-alarm-clock) and [here](https://developer.android.com/reference/android/Manifest.permission#USE_EXACT_ALARM)), this requires the app to target Android 13 (API level 33) or higher and could be subject to approval and auditing by the app store(s) used to publish theapp
+    * Specify the following between the `<application>` tags so that the plugin can actually show the scheduled notification(s)
+    ```xml
+    <receiver android:exported="false" android:name="com.dexterous.flutterlocalnotifications.ScheduledNotificationReceiver" />
+    <receiver android:exported="false" android:name="com.dexterous.flutterlocalnotifications.ScheduledNotificationBootReceiver">
+        <intent-filter>
+            <action android:name="android.intent.action.BOOT_COMPLETED"/>
+            <action android:name="android.intent.action.MY_PACKAGE_REPLACED"/>
+            <action android:name="android.intent.action.QUICKBOOT_POWERON" />
+            <action android:name="com.htc.intent.action.QUICKBOOT_POWERON"/>
+        </intent-filter>
+    </receiver>
+    ```
+* To use full-screen intent notifications, specify the `<uses-permission android:name="android.permission.USE_FULL_SCREEN_INTENT" />` permission between the `<manifest>` tags.
+* To use notification actions, specify `<receiver android:exported="false" android:name="com.dexterous.flutterlocalnotifications.ActionBroadcastReceiver" />` between the `<application>` tags so that the plugin can process the actions and trigger the appropriate callback(s)
+
+Developers can refer to the example app's `AndroidManifest.xml` to help see what the end result may look like. Do note that the example app covers all the plugin's supported functionality so will request more permissions than your own app may need
+
 ### Requesting permissions on Android 13 or higher
 
 From Android 13 (API level 33) onwards, apps now have the ability to display a prompt where users can decide if they want to grant an app permission to show notifications. For further reading on this matter read https://developer.android.com/guide/topics/ui/notifiers/notification-permission. To support this applications need target their application to Android 13 or higher and the compile SDK version needs to be at least 33 (Android 13). For example, to target Android 13, update your app's `build.gradle` file to have a `targetSdkVersion` of `33`. Applications can then call the following code to request the permission where the `requestPermission` method is associated with the `AndroidFlutterLocalNotificationsPlugin` class (i.e. the Android implementation of the plugin)

flutter_local_notifications/android/src/main/AndroidManifest.xml

@@ -1,20 +1,5 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
   package="com.dexterous.flutterlocalnotifications">
-    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
     <uses-permission android:name="android.permission.VIBRATE" />
-    <uses-permission android:name="android.permission.USE_FULL_SCREEN_INTENT" />
-    <uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />
     <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
-    <application>
-        <receiver android:exported="false" android:name="com.dexterous.flutterlocalnotifications.ActionBroadcastReceiver" />
-        <receiver android:exported="false" android:name="com.dexterous.flutterlocalnotifications.ScheduledNotificationReceiver" />
-        <receiver android:exported="false" android:name="com.dexterous.flutterlocalnotifications.ScheduledNotificationBootReceiver">
-            <intent-filter>
-                <action android:name="android.intent.action.BOOT_COMPLETED"/>
-                <action android:name="android.intent.action.MY_PACKAGE_REPLACED"/>
-                <action android:name="android.intent.action.QUICKBOOT_POWERON" />
-                <action android:name="com.htc.intent.action.QUICKBOOT_POWERON"/>
-            </intent-filter>
-        </receiver>
-    </application>
 </manifest>

flutter_local_notifications/android/src/main/java/com/dexterous/flutterlocalnotifications/FlutterLocalNotificationsPlugin.java

@@ -1,5 +1,7 @@
 package com.dexterous.flutterlocalnotifications;
 
+import static android.provider.Settings.ACTION_REQUEST_SCHEDULE_EXACT_ALARM;
+
 import android.Manifest;
 import android.annotation.SuppressLint;
 import android.app.Activity;
@@ -34,6 +36,7 @@
 
 import androidx.annotation.Keep;
 import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
 import androidx.core.app.ActivityCompat;
 import androidx.core.app.AlarmManagerCompat;
 import androidx.core.app.NotificationCompat;
@@ -111,6 +114,7 @@ public class FlutterLocalNotificationsPlugin
     implements MethodCallHandler,
         PluginRegistry.NewIntentListener,
         PluginRegistry.RequestPermissionsResultListener,
+        PluginRegistry.ActivityResultListener,
         FlutterPlugin,
         ActivityAware {
 
@@ -155,6 +159,8 @@ public class FlutterLocalNotificationsPlugin
   private static final String GET_NOTIFICATION_APP_LAUNCH_DETAILS_METHOD =
       "getNotificationAppLaunchDetails";
   private static final String REQUEST_PERMISSION_METHOD = "requestPermission";
+  private static final String REQUEST_EXACT_ALARMS_PERMISSION_METHOD =
+      "requestExactAlarmsPermission";
   private static final String METHOD_CHANNEL = "dexterous.com/flutter/local_notifications";
   private static final String INVALID_ICON_ERROR_CODE = "invalid_icon";
   private static final String INVALID_LARGE_ICON_ERROR_CODE = "invalid_large_icon";
@@ -194,8 +200,12 @@ public class FlutterLocalNotificationsPlugin
   private Context applicationContext;
   private Activity mainActivity;
   static final int NOTIFICATION_PERMISSION_REQUEST_CODE = 1;
+
+  static final int EXACT_ALARM_PERMISSION_REQUEST_CODE = 2;
+
   private PermissionRequestListener callback;
-  private boolean permissionRequestInProgress = false;
+
+  private PermissionRequestProgress permissionRequestProgress = PermissionRequestProgress.None;
 
   static void rescheduleNotifications(Context context) {
     ArrayList<NotificationDetails> scheduledNotifications = loadScheduledNotifications(context);
@@ -1335,6 +1345,8 @@ public void onDetachedFromEngine(@NonNull FlutterPluginBinding binding) {
   public void onAttachedToActivity(ActivityPluginBinding binding) {
     binding.addOnNewIntentListener(this);
     binding.addRequestPermissionsResultListener(this);
+    binding.addActivityResultListener(this);
+
     mainActivity = binding.getActivity();
     Intent mainActivityIntent = mainActivity.getIntent();
     if (!launchedActivityFromHistory(mainActivityIntent)) {
@@ -1355,6 +1367,7 @@ public void onDetachedFromActivityForConfigChanges() {
   public void onReattachedToActivityForConfigChanges(ActivityPluginBinding binding) {
     binding.addOnNewIntentListener(this);
     binding.addRequestPermissionsResultListener(this);
+    binding.addActivityResultListener(this);
     mainActivity = binding.getActivity();
   }
 
@@ -1395,6 +1408,20 @@ public void fail(String message) {
               }
             });
         break;
+      case REQUEST_EXACT_ALARMS_PERMISSION_METHOD:
+        requestExactAlarmsPermission(
+            new PermissionRequestListener() {
+              @Override
+              public void complete(boolean granted) {
+                result.success(granted);
+              }
+
+              @Override
+              public void fail(String message) {
+                result.error(PERMISSION_REQUEST_IN_PROGRESS_ERROR_CODE, message, null);
+              }
+            });
+        break;
       case PERIODICALLY_SHOW_METHOD:
         repeat(call, result);
         break;
@@ -1715,7 +1742,7 @@ private void cancelAllNotifications(Result result) {
   }
 
   public void requestPermission(@NonNull PermissionRequestListener callback) {
-    if (permissionRequestInProgress) {
+    if (permissionRequestProgress != PermissionRequestProgress.None) {
       callback.fail(PERMISSION_REQUEST_IN_PROGRESS_ERROR_MESSAGE);
       return;
     }
@@ -1729,27 +1756,53 @@ public void requestPermission(@NonNull PermissionRequestListener callback) {
               == PackageManager.PERMISSION_GRANTED;
 
       if (!permissionGranted) {
-        permissionRequestInProgress = true;
+        permissionRequestProgress = PermissionRequestProgress.RequestingNotificationPermission;
         ActivityCompat.requestPermissions(
             mainActivity, new String[] {permission}, NOTIFICATION_PERMISSION_REQUEST_CODE);
       } else {
         this.callback.complete(true);
-        permissionRequestInProgress = false;
+        permissionRequestProgress = PermissionRequestProgress.None;
       }
     } else {
       NotificationManagerCompat notificationManager = NotificationManagerCompat.from(mainActivity);
       this.callback.complete(notificationManager.areNotificationsEnabled());
     }
   }
 
+  public void requestExactAlarmsPermission(@NonNull PermissionRequestListener callback) {
+    if (permissionRequestProgress != PermissionRequestProgress.None) {
+      callback.fail(PERMISSION_REQUEST_IN_PROGRESS_ERROR_MESSAGE);
+      return;
+    }
+
+    this.callback = callback;
+
+    if (Build.VERSION.SDK_INT >= VERSION_CODES.S) {
+      AlarmManager alarmManager = getAlarmManager(applicationContext);
+      boolean permissionGranted = alarmManager.canScheduleExactAlarms();
+
+      if (!permissionGranted) {
+        permissionRequestProgress = PermissionRequestProgress.RequestingExactAlarmsPermission;
+        mainActivity.startActivityForResult(
+            new Intent(ACTION_REQUEST_SCHEDULE_EXACT_ALARM), EXACT_ALARM_PERMISSION_REQUEST_CODE);
+      } else {
+        this.callback.complete(true);
+        permissionRequestProgress = PermissionRequestProgress.None;
+      }
+    } else {
+      this.callback.complete(true);
+    }
+  }
+
   @Override
   public boolean onRequestPermissionsResult(
       int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
-    if (permissionRequestInProgress && requestCode == NOTIFICATION_PERMISSION_REQUEST_CODE) {
+    if (permissionRequestProgress == PermissionRequestProgress.RequestingNotificationPermission
+        && requestCode == NOTIFICATION_PERMISSION_REQUEST_CODE) {
       boolean granted =
           grantResults.length > 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED;
       callback.complete(granted);
-      permissionRequestInProgress = false;
+      permissionRequestProgress = PermissionRequestProgress.None;
       return granted;
     } else {
       return false;
@@ -2059,6 +2112,21 @@ private void setCanScheduleExactNotifications(Result result) {
     }
   }
 
+  @Override
+  public boolean onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
+    if (requestCode != NOTIFICATION_PERMISSION_REQUEST_CODE
+        && requestCode != EXACT_ALARM_PERMISSION_REQUEST_CODE) {
+      return false;
+    }
+
+    if (requestCode == EXACT_ALARM_PERMISSION_REQUEST_CODE && VERSION.SDK_INT >= VERSION_CODES.S) {
+      AlarmManager alarmManager = getAlarmManager(applicationContext);
+      this.callback.complete(alarmManager.canScheduleExactAlarms());
+    }
+
+    return true;
+  }
+
   private static class PluginException extends RuntimeException {
     public final String code;
 
@@ -2073,4 +2141,10 @@ public ExactAlarmPermissionException() {
       super(EXACT_ALARMS_PERMISSION_ERROR_CODE, "Exact alarms are not permitted");
     }
   }
+
+  enum PermissionRequestProgress {
+    None,
+    RequestingNotificationPermission,
+    RequestingExactAlarmsPermission
+  }
 }

flutter_local_notifications/example/android/app/src/main/AndroidManifest.xml

@@ -1,5 +1,10 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
     package="com.dexterous.flutter_local_notifications_example">
+   <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
+   <uses-permission android:name="android.permission.VIBRATE" />
+   <uses-permission android:name="android.permission.USE_FULL_SCREEN_INTENT" />
+   <uses-permission android:name="android.permission.USE_EXACT_ALARM" />
+   <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
    <application
         android:label="flutter_local_notifications_example"
         android:icon="@mipmap/ic_launcher">
@@ -38,6 +43,16 @@
             android:name="com.dexterous.flutterlocalnotifications.ForegroundService"        
             android:exported="false"
             android:stopWithTask="false"/>
+        <receiver android:exported="false" android:name="com.dexterous.flutterlocalnotifications.ActionBroadcastReceiver" />
+        <receiver android:exported="false" android:name="com.dexterous.flutterlocalnotifications.ScheduledNotificationReceiver" />
+        <receiver android:exported="false" android:name="com.dexterous.flutterlocalnotifications.ScheduledNotificationBootReceiver">
+            <intent-filter>
+                <action android:name="android.intent.action.BOOT_COMPLETED"/>
+                <action android:name="android.intent.action.MY_PACKAGE_REPLACED"/>
+                <action android:name="android.intent.action.QUICKBOOT_POWERON" />
+                <action android:name="com.htc.intent.action.QUICKBOOT_POWERON"/>
+            </intent-filter>
+        </receiver>
     </application>
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
 </manifest>

flutter_local_notifications/example/lib/main.dart

@@ -303,9 +303,10 @@ class _HomePageState extends State<HomePage> {
           flutterLocalNotificationsPlugin.resolvePlatformSpecificImplementation<
               AndroidFlutterLocalNotificationsPlugin>();
 
-      final bool? granted = await androidImplementation?.requestPermission();
+      final bool? grantedNotificationPermission =
+          await androidImplementation?.requestPermission();
       setState(() {
-        _notificationsEnabled = granted ?? false;
+        _notificationsEnabled = grantedNotificationPermission ?? false;
       });
     }
   }

flutter_local_notifications/lib/src/flutter_local_notifications_plugin.dart

@@ -327,6 +327,10 @@ class FlutterLocalNotificationsPlugin {
   /// 10:00 and the value of the [matchDateTimeComponents] is
   /// [DateTimeComponents.time], then the next time a notification will
   /// appear is 2020-10-20 10:00.
+  ///
+  /// On Android, this will also require additional setup for the app,
+  /// especially in the app's `AndroidManifest.xml` file. Please see check the
+  /// readme for further details.
   Future<void> zonedSchedule(
     int id,
     String? title,
@@ -395,6 +399,10 @@ class FlutterLocalNotificationsPlugin {
   /// future majorrelease in favour of the [androidScheduledMode] parameter that
   /// provides the same functionality in addition to being able to schedule
   /// notifications with inexact timings.
+  ///
+  /// On Android, this will also require additional setup for the app,
+  /// especially in the app's `AndroidManifest.xml` file. Please see check the
+  /// readme for further details.
   Future<void> periodicallyShow(
     int id,
     String? title,