alarm

Android behaviour change:

• #418 an alarm whose time passed while the device was off is discarded at boot
  instead of ringing hours late, and reported as AlarmDropped/staleAtBoot.
  Cutoff is AlarmSettings.androidStaleAfter, 15 minutes by default; null keeps
  the old behaviour. Contributed by @samyak1409.

New API:

• Alarm.acknowledgeEvent and Alarm.init(acknowledgeEventsAutomatically: false),
  so an app can hold a host event's marker until it has durably recorded it
  (#429). Opt-in; automatic acknowledgement stays the default, because
  Alarm.snoozed carries no handle to acknowledge with. Contributed by
  @samyak1409.

Verified on a Pixel 8a: stale alarm discarded and reported through
Alarm.events, a non-stale one still ringing through the #424 boot-window
deferral, and an explicit null never discarding.

• [Android] An alarm whose time passed while the device was off is now discarded instead of ringing at boot (#418). Reported on Alarm.events as an AlarmDropped with cause staleAtBoot.
• Added AlarmSettings.androidStaleAfter, the cutoff for that: 15 minutes by default, null never discards.
• Added Alarm.acknowledgeEvent() and Alarm.init(acknowledgeEventsAutomatically: false), so an app can keep a host event until it has durably recorded it (#429).

Android reliability:

• #424 an alarm due within ~45s of a reboot never rang; the refused ring is now
  retried past the boot window, and dropped visibly if the retry is refused too.

New API:

• Alarm.events, reporting deferrals and discards the host decided on its own.
• Alarm.snoozed is now buffered and derived from it.

• [Android] Fixed an alarm due within ~45s of a reboot never ringing (#424).
• Added Alarm.events, reporting deferrals and discards the host made on its own.
• Alarm.snoozed is now buffered, so listeners subscribing after Alarm.init() still get replayed deferrals.

Android reliability fixes, all reported by @samyak1409:

• #419 an alarm that was due but not yet audible is no longer cancelled by Alarm.init()
• #420 a failed alarm arm is reported to Flutter instead of silently succeeding
• #421 androidStopAlarmOnDismiss: false restores the ring notification instead of ignoring the swipe

• [Android] Fixed Alarm.init() cancelling an alarm that was due but had not started ringing yet, which silently lost the alarm. Past-due alarms are now left alone for 30 seconds before being stopped.
• [Android] A failed alarm arm is now reported to Flutter as an error instead of success, and no longer leaves an alarm stored that the platform never armed. Alarm.set() now throws AlarmException where it previously returned true. A failed re-arm after a reboot keeps the alarm stored instead, so a later Alarm.init() can retry it.
• [Android] NotificationSettings.androidStopAlarmOnDismiss: false now re-posts the notification while the alarm is still ringing, instead of letting the swipe remove the only on-screen control over a sounding alarm.

• [Android] Added NotificationSettings.androidStopAlarmOnDismiss to control whether swiping the notification away also stops the alarm. Enabled by default, matching the behavior added in 5.0.3.

• [Android] Fixed the lock screen asking for authentication before the alarm could be stopped: the keyguard is now only dismissed on devices without a PIN, pattern or password.

• [Android] Added a snooze action to the alarm notification, via AlarmSettings.androidSnoozeDuration and NotificationSettings.androidSnoozeButton. Snoozing defers the alarm rather than stopping it, and is reported on the new Alarm.snoozed stream as well as through Alarm.scheduled. A snooze taken with no Flutter engine running is applied on the next Alarm.init().
• [Android] Alarms can now be presented on the app's own activity by declaring an intent filter for com.gdelataillade.alarm.action.RING, instead of always opening the launcher activity.
• Fixed build_runner being unable to regenerate lib/model/*.g.dart, which also removes the only dart format violation in the package.

• [Android] Added support for Android Gradle Plugin 9, while keeping AGP 8 compatibility.
• [Android] Fixed several alarm scheduling, foreground service, and audio playback crashes.
• [Android] Stop actions now dismiss the alarm notification when the alarm service is not running.
• [iOS] Fixed alarm timing precision, volume fades, and background refresh scheduling.
• [iOS] Migrated the example app from CocoaPods to Swift Package Manager.
• Fixed AlarmSettings.copyWith not clearing payload, and a debug-mode assert in NotificationSettings.copyWith; deprecated legacy copyWith parameters that were silently ignored.
• Fixed the v4 → v5 migration misparsing fadeDuration.
• Added a Dart unit test suite, now run in CI.

• [iOS] Added Swift Package Manager support.
• Added AlarmSettings.allowSameSecondScheduling to allow multiple alarms to ring in the same second.
• Requires Flutter 3.41.0 or later. Older Flutter projects will continue to resolve to 5.4.1.

• [Android] Added AlarmSettings.preferConnectedAudioDevice to route alarm audio through connected earphones or Bluetooth.
• [Android] Fixed androidStopAlarmOnTermination not persisting across app restarts.

• [Android] Added VolumeSettings.showSystemUI to suppress the system volume bar when the alarm sets or restores volume.

• [Android] Route alarm audio through the alarm volume stream so it responds to the alarm slider instead of media volume.

• [iOS] Added NotificationSettings.keepNotificationAfterAlarmEnds to control whether the notification should stay after alarm ends or not.

• Using device's default alarm sound when assetAudioPath is null.
• [Android] Added support for Android Gradle Plugin 8.

• [Android] Fixed stream not firing.

• [Android] Simplified plugin lifecycle.

• [Android] Added androidStopAlarmOnTermination parameter.
• [Android] Improved installation steps.

• Updated AlarmSettings.assetAudioPath documentation.

• [Android] Added icon color parameter for notification.

• [iOS] Added native refactoring to fix alarm that didn't ring.
• [Android] Fixed imports.

• Added CodeCanvas diagram to documentation (see here).
• [Android] Added alarm stop on notification dismiss.

• [Android] Improved stop alarm process.

• Updated README.

💥 Breaking Changes 🔧 Android installation steps were updated here.

• Some API parameters have been renamed.
• Fixed multiple minor bugs.

• Added payload parameter.
• Updated dependencies.
• Improved alarm events streams.
• Fixed duplicated alarms issue.

• Fixed backward compatibility for v4 Dart JSON structures.

• Fixed backward compatibility for v4 Dart JSON structures.

• Added debug logs to understand why backward compatibility fails.

• [Android] Fixed collition between package and FCM.

• Updated README.

• [iOS] Added iOSBackgroundAudio parameter to disable background silent audio player, which is not necessary if your app already has a background process that keeps app active in the background.

• Added backward compatibility with package versions below 5.

• [Android] Fixed build error & downgrade datastore.

• Handles stopAll on the platform side for improved reliability.

💥 Breaking Changes

• Old alarms (alarms created pre v5) will be deleted and some API parameters have been renamed, this update requires a small amount of refactoring for users. No features have been removed.
• Added support for fading the alarm volume using a staircase function.
• Fixed a bug where isRinging might return FALSE immediately after alarm starts to ring.
• Handled alarm events on the platform side, increasing efficiency.

• [Android] Show app on lock screen when alarm rings.

• Migrated to Pigeon.

• [iOS] Fixed isRinging method for specific id.

• [iOS] Fixed isRinging method.

• [Android] Fixed androidFullScreenIntent parameter.

• Added new alarm parameter volumeEnforced.
• [iOS] Reopen killed app when tap on notification stop button.

• Fixed and improved isRinging method.
• [iOS] Add support for longer volume fade durations.
• [iOS] Dismiss notification on alarm stop.

• [iOS] Added iOS notification category handling.
• [iOS] Fixed handleMethodCall cast error in IOSAlarm.

• [iOS] Fixed vibration interruption during overlapping alarms.

• [Android] Fixed crash when incoming alarm is ignored.

• [Android] Fixed crash on older Android versions.

• [Android] Fixed error when rescheduling old version alarm after reboot.

• [iOS] Improve thread safety.
• [Android] Add native backward compatibility with older versions.

• [iOS] Fixed crash on iOS when setting warning notification on kill.

💥 Breaking Changes

• Added notification action stop button.
• Refactored AlarmSettings model.
• Ignore oncoming alarm if another alarm is ringing.
• [Android] Updated kotlin version to 1.8.0.
• [Android] Added customizable notification icon.
• [Android] Reschedule alarms after device reboot.
• [iOS] Removed notification permission request. Must be handled in-app to match Android behaviour.

💥 Breaking Changes

• [iOS] Removed notification permission request. Must be handled in-app to match Android behaviour.

• [Android] Reschedule alarms after device reboot.

💥 Breaking Changes

• Refactored AlarmSettings model.
• Ignore oncoming alarm if another alarm is ringing.
• [Android] Add customizable notification icon.
• [Android] Update kotlin version to 1.8.0.

• [Android] Fix native GSON parsing error.
• Update flutter_fgbg dependency.

• Add notification action stop button.

• [Android] Update kotlin version to 1.7.10.

• Update flutter_fgbg dependency to 0.6.0.
• Update shared_preferences dependency to 2.3.2.

• [Android] Fix volume/focus post-alarm.
• Export AlarmSettings class in Alarm class.

• [Android] Add more type safety.

🔧 Android installation steps were updated here.

• [Android] Remove notification large icon.

• [Android] Fix alarm stop on app open.