From f59f7eb3ff686b3e80c7b5ff3df8078ce2c3d604 Mon Sep 17 00:00:00 2001 From: Michael Bui <25263378+MaikuB@users.noreply.github.com> Date: Thu, 5 Oct 2023 22:27:43 +1100 Subject: [PATCH] [flutter_local_notifications] updated presentSound and defaultPresentSound API docs around background app behaviour (#2112) * added more details on background sound behaviour to presentSound and defaultPresentSound * added changelog entry --- flutter_local_notifications/CHANGELOG.md | 1 + .../darwin/initialization_settings.dart | 10 ++++++++++ .../darwin/notification_details.dart | 9 +++++++++ 3 files changed, 20 insertions(+) diff --git a/flutter_local_notifications/CHANGELOG.md b/flutter_local_notifications/CHANGELOG.md index 08b99c6e0..50dfddcd1 100644 --- a/flutter_local_notifications/CHANGELOG.md +++ b/flutter_local_notifications/CHANGELOG.md @@ -6,6 +6,7 @@ * [Android] bumped Java desugaring dependency and updated readme accordingly to also mention Gradle version that is used by plugin * [Android] fixed issue an issue similar to [2033](https://github.com/MaikuB/flutter_local_notifications/issues/2033) that was addressed in 15.0.1 where notifications on scheduled using older version of the plugin via the `periodicallyShow()` method would fail to have the next subsequent ones scheduled. This issue started occuring in 14.0 where support for inexact notifications was added using the `ScheduleMode` enum that was added and resulted in the deprecation of `androidAllowWhileIdle`. A mechanism was added to help "migrate" old notifications that had `androidAllowWhileIdle` specified but didn't account for how there are recurring notifications that were scheduled using older versions of the plugin prior to `androidAllowWhile` being added. This was also released as part of the 15.1.1 and 14.1.3 hotfix releases * [Android] fixed issue [2106](https://github.com/MaikuB/flutter_local_notifications/issues/2106) where calling `getNotificationChannels()` reports the wrong importance level or result in an exception if the importance level was unspecified. This was also released as part of the 15.1.2 and 14.1.4 hotfix releases +* [iOS][macOS] addresses issue [2097](https://github.com/MaikuB/flutter_local_notifications/issues/2097) by updating API docs for the `presentSound` and `defaultPresentSound` properties that belong to the `DarwinNotificationDetails` and `DarwinInitializationSettings` classes respectively to clarify the background behaviour and how have a sound play even when app is the background yet these properties are set to false * Updated example app so that the Android side specifies minimum SDK version version that aligns with what's specified by the Flutter SDK * Fixed Dart API docs for `DarwinNotificationDetails` class where `this This` was being repeated. Thanks to the PR from [Adrian Jagielak](https://github.com/adrianjagielak) * Fixed example code shown at the "Handling notifications whilst the app is in the foreground" section of the readme. Thanks to the PR from [Tinh Huynh](https://github.com/TinhHuynh) diff --git a/flutter_local_notifications/lib/src/platform_specifics/darwin/initialization_settings.dart b/flutter_local_notifications/lib/src/platform_specifics/darwin/initialization_settings.dart index 74515deb8..362bba288 100644 --- a/flutter_local_notifications/lib/src/platform_specifics/darwin/initialization_settings.dart +++ b/flutter_local_notifications/lib/src/platform_specifics/darwin/initialization_settings.dart @@ -76,6 +76,16 @@ class DarwinInitializationSettings { /// /// Default value is true. /// + /// If this is set to false to indicate that the notification shouldn't play + /// a sound in the foreground then note that for consistency, the notification + /// won't play a sound when the app is in the background. If the intention in + /// this scenario is to have the app also play the default notification sound + /// whilst the app is in the background as well, then the + /// [DarwinNotificationDetails.sound] should be set to an arbitrary value + /// (e.g. empty string) that doesn't match a custom sound file. This way the + /// platform fails to find a custom sound file to fallback to the default + /// notification sound. + /// /// On iOS, this property is only applicable to iOS 10 or newer. /// On macOS, this property is only applicable to macOS 10.14 or newer. final bool defaultPresentSound; diff --git a/flutter_local_notifications/lib/src/platform_specifics/darwin/notification_details.dart b/flutter_local_notifications/lib/src/platform_specifics/darwin/notification_details.dart index 12bad6e39..3dc01c81f 100644 --- a/flutter_local_notifications/lib/src/platform_specifics/darwin/notification_details.dart +++ b/flutter_local_notifications/lib/src/platform_specifics/darwin/notification_details.dart @@ -41,6 +41,15 @@ class DarwinNotificationDetails { /// When this is set to `null`, it will use the default setting given /// to [DarwinInitializationSettings.defaultPresentSound]. /// + /// If this is set to false to indicate that the notification shouldn't play + /// a sound in the foreground then note that for consistency, the notification + /// won't play a sound when the app is in the background. If the intention in + /// this scenario is to have the app also play the default notification sound + /// whilst the app is in the background as well, then the [sound] should be + /// set to an arbitrary value (e.g. empty string) that doesn't match a custom + /// sound file. This way the platform fails to find a custom sound file to + /// fallback to the default notification sound. + /// /// This property is only applicable to iOS 10 or newer. final bool? presentSound;