Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(android_alarm_manager_plus): Update information about SCHEDULE_EXACT_ALARM permission #2716

Merged
merged 4 commits into from
Mar 17, 2024
Merged

docs(android_alarm_manager_plus): Update information about SCHEDULE_EXACT_ALARM permission #2716

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
36a8332
docs(android_alarm_manager_plus): Update information about SCHEDULE_E…
vbuberen Mar 17, 2024
a60fc3f
Update API docs
vbuberen Mar 17, 2024
d9b5e36
Update README.md
vbuberen Mar 17, 2024
58e1430
Update usage.mdx
vbuberen Mar 17, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
20 changes: 15 additions & 5 deletions docs/android_alarm_manager_plus/usage.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,19 @@ sidebar_label: Usage
hide_title: true
---

After importing this plugin to your project as usual, add the following to your
`AndroidManifest.xml` within the `<manifest></manifest>` tags:
Before using the plugin you would also need a plugin to request [SCHEDULE_EXACT_ALARM](https://developer.android.com/reference/android/Manifest.permission#SCHEDULE_EXACT_ALARM) permission when your app targets Android 14 and newer.
Google introduced SCHEDULE_EXACT_ALARM permission in [Android 12](https://developer.android.com/about/versions/12/behavior-changes-12#exact-alarm-permission). In Android 13 it was granted by default.
Since Android 14 this permission [is denied by default](https://developer.android.com/about/versions/14/changes/schedule-exact-alarms) and apps need to ask user to provide it.
`android_alarm_manager_plus` does not provide a way to work with this permission, so be sure to handle such logic yourself.
To do so you would need an additional plugin, like [`permission_handler`](https://pub.dev/packages/permission_handler).

After importing `android_alarm_manager_plus` plugin into your project, add the following lines to your
`AndroidManifest.xml` file inside `<manifest></manifest>` tags:

```xml
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
<uses-permission android:name="android.permission.WAKE_LOCK"/>
<!-- For apps with targetSDK=31 (Android 12) -->
<!-- For apps with targetSDK 31 (Android 12) and newer -->
<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM"/>
```

Expand Down Expand Up @@ -39,7 +45,7 @@ Then in Dart code add:
```dart
import 'package:android_alarm_manager_plus/android_alarm_manager_plus.dart';

// Be sure to annotate your callback function to avoid issues in release mode on Flutter >= 3.3.0
// It is required to annotate your callback function like this to avoid issues in release mode on Flutter >= 3.3.0
@pragma('vm:entry-point')
void printHello() {
final DateTime now = DateTime.now();
Expand All @@ -54,12 +60,16 @@ main() async {
await AndroidAlarmManager.initialize();
runApp(...);
final int helloAlarmID = 0;

// Handle SCHEDULE_EXACT_ALARM permission before trying to schedule any alarm with the plugin
// Otherwise an exception will happen. Check Note below for more information

await AndroidAlarmManager.periodic(const Duration(minutes: 1), helloAlarmID, printHello);
}
```

:::note
If your app has targetSDK=31 (Android 12) and you would like to create alarms with `alarmClock=true` or `exact=true`
If your app has targetSDK=31 (Android 12) or newer and you would like to create alarms with `alarmClock=true` or `exact=true`
be aware that user or system might cancel such alarms by revoking `SCHEDULE_EXACT_ALARM` permission.
More info can be found in [the official documentation](https://developer.android.com/training/scheduling/alarms#exact-permission-declare)

Expand Down
11 changes: 9 additions & 2 deletions packages/android_alarm_manager_plus/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
[![pub points](https://img.shields.io/pub/points/android_alarm_manager_plus?color=2E8B57&label=pub%20points)](https://pub.dev/packages/android_alarm_manager_plus/score)
[![android_alarm_manager_plus](https://github.com/fluttercommunity/plus_plugins/actions/workflows/android_alarm_manager_plus.yaml/badge.svg)](https://github.com/fluttercommunity/plus_plugins/actions/workflows/android_alarm_manager_plus.yaml)

<center><a href="https://flutter.dev/docs/development/packages-and-plugins/favorites" target="_blank" rel="noreferrer noopener"><img src="../../website/static/img/flutter-favorite-badge.png" width="100" alt="build"></a></center>
<div style="text-align: center;"><a href="https://flutter.dev/docs/development/packages-and-plugins/favorites" target="_blank" rel="noreferrer noopener"><img src="../../website/static/img/flutter-favorite-badge.png" width="100" alt="build"></a></div>

A Flutter plugin for accessing the Android AlarmManager service, and running
Dart code in the background when alarms fire.
Expand All @@ -19,13 +19,20 @@ Dart code in the background when alarms fire.

## Getting Started

> [!IMPORTANT]
> You would also need a plugin to request [SCHEDULE_EXACT_ALARM](https://developer.android.com/reference/android/Manifest.permission#SCHEDULE_EXACT_ALARM) permission if your app targets Android 14 and newer.
> Google introduced SCHEDULE_EXACT_ALARM permission in [Android 12](https://developer.android.com/about/versions/12/behavior-changes-12#exact-alarm-permission). In Android 13 it was granted by default.
> Since Android 14 this permission [is denied by default](https://developer.android.com/about/versions/14/changes/schedule-exact-alarms) and apps need to ask user to provide it.
> `android_alarm_manager_plus` does not provide a way to work with this permission, so be sure to handle such logic yourself.
> To do so you would need an additional plugin, like [`permission_handler`](https://pub.dev/packages/permission_handler).

After importing this plugin to your project as usual, add the following to your
`AndroidManifest.xml` within the `<manifest></manifest>` tags:

```xml
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
<uses-permission android:name="android.permission.WAKE_LOCK"/>
<!-- For apps with targetSDK=31 (Android 12) -->
<!-- For apps with targetSDK 31 (Android 12) and newer -->
<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM"/>
```

Expand Down
10 changes: 5 additions & 5 deletions packages/android_alarm_manager_plus/lib/android_alarm_manager_plus.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,8 +137,8 @@ class AndroidAlarmManager {
/// If `exact` is passed as `true`, the timer will be created with Android's
/// `AlarmManagerCompat.setExact`. When `exact` is `false` (the default), the
/// timer will be created with `AlarmManager.set`.
/// For apps with `targetSDK=31` before scheduling an exact alarm a check for
/// `SCHEDULE_EXACT_ALARM` permission is required. Otherwise, an exeption will
/// For apps with `targetSDK=31` and newer before scheduling an exact alarm a check for
/// `SCHEDULE_EXACT_ALARM` permission is required. Otherwise, an exception will
/// be thrown and alarm won't schedule.
///
/// If `wakeup` is passed as `true`, the device will be woken up when the
Expand Down Expand Up @@ -207,7 +207,7 @@ class AndroidAlarmManager {
/// If `exact` is passed as `true`, the timer will be created with Android's
/// `AlarmManagerCompat.setExact`. When `exact` is `false` (the default), the
/// timer will be created with `AlarmManager.set`.
/// For apps with `targetSDK=31` before scheduling an exact alarm a check for
/// For apps with `targetSDK=31` and newer before scheduling an exact alarm a check for
/// `SCHEDULE_EXACT_ALARM` permission is required. Otherwise, an exception
/// will be thrown and alarm won't schedule.
///
Expand Down Expand Up @@ -290,8 +290,8 @@ class AndroidAlarmManager {
/// If `exact` is passed as `true`, the timer will be created with Android's
/// `AlarmManager.setRepeating`. When `exact` is `false` (the default), the
/// timer will be created with `AlarmManager.setInexactRepeating`.
/// For apps with `targetSDK=31` before scheduling an exact alarm a check for
/// `SCHEDULE_EXACT_ALARM` permission is required. Otherwise, an exeption will
/// For apps with `targetSDK=31` and newer before scheduling an exact alarm a check for
/// `SCHEDULE_EXACT_ALARM` permission is required. Otherwise, an exception will
/// be thrown and alarm won't schedule.
///
/// If `wakeup` is passed as `true`, the device will be woken up when the
Expand Down