doc uodates and clean up sample

Author: MaikuB

CHANGELOG.md

@@ -1,3 +1,8 @@
+# [0.4.1]
+* [Android/iOS] New `onShowNotification` callback for when a notification is shown that can handled when calling the `initialize` function. This uses the latest changes to the Flutter engine that supports headless execution i.e. the ability to execute Dart code without the app running. See [here](https://github.com/flutter/flutter/issues/6192) for a link to the issue in the main Flutter repository about this. Note that the function handling this callback must be top-level function as this is requirement for executing headless Dart code. The example for the plugin has been updated to provide sample code on to handle the callback.
+* **BREAKING CHANGE** renamed the `selectNotification` callback exposed by the `initialize` function to `onSelectNotification`
+* Address issue [115](https://github.com/MaikuB/flutter_local_notifications/issues/115) by adding validation to the notification ID values. This ensure they're within the range of a 32-bit integer as notification IDs on Android need to be within that range. Note that an `ArgumentError` is thrown when a value is out of range. 
+
 # [0.4.0]
 * [Android] Fix issue [112](https://github.com/MaikuB/flutter_local_notifications/issues/112) where big picture notifications wouldn't show
 

README.md

@@ -20,6 +20,7 @@ A cross platform plugin for displaying local notifications.
 * Specify a custom notification sound
 * Ability to handle when a user has tapped on a notification, when the app is the foreground, background or terminated
 * Determine if an app was launched due to tapping on a notification
+* [Android/iOS 10+] Receive callback when a notification is shown
 * [Android] Configuring the importance level
 * [Android] Configuring the priority
 * [Android] Customising the vibration pattern for notifications
@@ -67,10 +68,11 @@ var initializationSettings = new InitializationSettings(
     initializationSettingsAndroid, initializationSettingsIOS);
 flutterLocalNotificationsPlugin = new FlutterLocalNotificationsPlugin();
 flutterLocalNotificationsPlugin.initialize(initializationSettings,
-    selectNotification: onSelectNotification);
+    onSelectNotification: onSelectNotification
+    onShowNotification: onShowNotification);
 ```
 
-Here we specify we have specified the default icon to use for notifications on Android (refer to the Android Integration section) and designated the function (onSelectNotification) that should fire when a notification has been tapped on. Specifying this callback is entirely optional. In this example, it will trigger navigation to another page and display the payload associated with the notification. 
+Here we specify we have specified the default icon to use for notifications on Android (refer to the Android Integration section) and designated the function (onSelectNotification) that should fire when a notification has been tapped on. Specifying this callback is entirely optional. In this example, it will trigger navigation to another page and display the payload associated with the notification. It is also possible to handle the `onShowNotification` that will invoke code when a notification is shown. Note that the function handling this callback must be top-level function as this is requirement for executing headless Dart code.
 
 ```
 Future onSelectNotification(String payload) async {
@@ -256,22 +258,28 @@ This should cover the basic functionality. Please check out the `example` direct
 
 ## Android Integration
 
-If your application needs the ability to schedule notifications then you need to request permissions to be notified when the phone has been booted as scheduled notifications uses AlarmManager to determine when notifications should be displayed. However, they are cleared when a phone has been turned off. Requesting permission requires adding the following to the manifest
+If your application needs the ability to schedule notifications then you need to request permissions to be notified when the phone has been booted as scheduled notifications uses the `AlarmManager` API to determine when notifications should be displayed. However, they are cleared when a phone has been turned off. Requesting permission requires adding the following to the manifest
 
 ```xml
 <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
 ```
 
-Developers will also need to add the following so that plugin can handle displaying scheduled notifications and reschedule notifications upon a reboot
+Developers will also need to add the following so that plugin can handle displaying scheduled notifications
 
 ```xml
 <receiver android:name="com.dexterous.flutterlocalnotifications.ScheduledNotificationReceiver" />
+```
+
+As Android normally will not keep anything scheduled via the `AlarmManager` API upon reboot, the following is also needed to ensure scheduled notifications remain scheduled upon a reboot 
+
+```xml
 <receiver android:name="com.dexterous.flutterlocalnotifications.ScheduledNotificationBootReceiver">
     <intent-filter>
         <action android:name="android.intent.action.BOOT_COMPLETED"></action>
     </intent-filter>
 </receiver>
 ```
+
 If the vibration pattern of an Android notification will be customised then add the following
 
 ```xml

example/lib/main.dart

@@ -10,9 +10,11 @@ import 'package:path_provider/path_provider.dart';
 import 'package:shared_preferences/shared_preferences.dart';
 import 'package:rxdart/rxdart.dart';
 
-FlutterLocalNotificationsPlugin flutterLocalNotificationsPlugin;
-Future<SharedPreferences> sharedPrefs = SharedPreferences.getInstance();
+var flutterLocalNotificationsPlugin;
+var sharedPrefs = SharedPreferences.getInstance();
 var counterSubject = PublishSubject<int>();
+var portName = 'notification_shown_port';
+var shownCounterSharedPrefKey = 'shownCounter';
 
 /// IMPORTANT: running the following code on its own won't work as there is setup required for each platform head project.
 /// Please download the complete example app from the GitHub repository where all the setup has been done
@@ -30,20 +32,21 @@ void main() async {
   );
 }
 
-Future onNotification(int id, String title, String body, String payload) async {
+/// Top-level function to handle when a notification is shown
+Future onShowNotification(
+    int id, String title, String body, String payload) async {
   print(
       'on notification callback triggered with id: $id, title: $title, body: $body, payload: $payload');
   // update a counter in shared preferences to track how many times a notification has been shown
   // this example app will only display the counter on a cold start of the app to demonstrate headless execution
   if (Platform.isAndroid) {
     // IMPORTANT: Flutter currently only supports executing headless Dart code that uses other plugins on Android
     var sharedPreferences = await sharedPrefs;
-    var shown = (sharedPreferences.getInt('shownCounter') ?? 0) + 1;
-    sharedPreferences.setInt('shownCounter', shown);
+    var shown = (sharedPreferences.getInt(shownCounterSharedPrefKey) ?? 0) + 1;
+    sharedPreferences.setInt(shownCounterSharedPrefKey, shown);
 
-    // use to send updates that can be handled in the UI
-    final SendPort send =
-        IsolateNameServer.lookupPortByName('notification_shown_port');
+    // required so updates can be handled in the UI
+    final SendPort send = IsolateNameServer.lookupPortByName(portName);
     send?.send(shown);
   }
 }
@@ -67,14 +70,14 @@ class _HomePageState extends State<HomePage> {
         initializationSettingsAndroid, initializationSettingsIOS);
     flutterLocalNotificationsPlugin.initialize(initializationSettings,
         onSelectNotification: onSelectNotification,
-        onNotification: onNotification);
+        onShowNotification: onShowNotification);
     sharedPrefs.then((sharedPreferences) {
-      var counter = sharedPreferences.getInt('shownCounter') ?? 0;
+      var counter = sharedPreferences.getInt(shownCounterSharedPrefKey) ?? 0;
       counterSubject.sink.add(counter);
     });
 
-    IsolateNameServer.registerPortWithName(
-        port.sendPort, 'notification_shown_port');
+    // used to handle that a notification was shown while app was running and we need to update the counter
+    IsolateNameServer.registerPortWithName(port.sendPort, portName);
     port.listen((dynamic data) {
       counterSubject.sink.add(data);
     });
@@ -100,23 +103,6 @@ class _HomePageState extends State<HomePage> {
                         'Tap on a notification when it appears to trigger navigation'),
                   ),
                   // NOTE: the following text is demonstrate headless execution with plugins work in Android
-                  /*new Padding(
-                      padding: new EdgeInsets.fromLTRB(0.0, 0.0, 0.0, 8.0),
-                      child: new FutureBuilder(
-                        future: sharedPrefs,
-                        builder:
-                            (BuildContext context, AsyncSnapshot snapshot) {
-                          if (snapshot.hasData) {
-                            SharedPreferences sharedPreferences = snapshot.data;
-                            var counter =
-                                sharedPreferences.getInt('shownCounter') ?? 0;
-                            return new Text(
-                                'Shown ${counter.toString()} Android notifications since the last cold start');
-                          } else {
-                            return CircularProgressIndicator();
-                          }
-                        },
-                      )),*/
                   new Padding(
                       padding: new EdgeInsets.fromLTRB(0.0, 0.0, 0.0, 8.0),
                       child: new StreamBuilder(

lib/src/flutter_local_notifications.dart

@@ -6,7 +6,7 @@ typedef Future<dynamic> SelectNotificationCallback(String payload);
 /// Signature of callback passed to [initialize].
 /// Callback is triggered when a notification is shown. Note that on iOS this only works on iOS 10+.
 /// The callback must be a top-level or static method
-typedef Future<dynamic> NotificationCallback(
+typedef Future<dynamic> ShowNotificationCallback(
     int id, String title, String body, String payload);
 
 /// The available intervals for periodically showing notifications
@@ -78,7 +78,7 @@ class FlutterLocalNotificationsPlugin {
   /// Initializes the plugin. Call this method on application before using the plugin further
   Future<bool> initialize(InitializationSettings initializationSettings,
       {SelectNotificationCallback onSelectNotification,
-      NotificationCallback onNotification}) async {
+      ShowNotificationCallback onShowNotification}) async {
     onSelectNotification = onSelectNotification;
     var serializedPlatformSpecifics =
         _retrievePlatformSpecificInitializationSettings(initializationSettings);
@@ -91,11 +91,11 @@ class FlutterLocalNotificationsPlugin {
     var headlessInitializationSettings = <String, dynamic>{
       'callbackDispatcher': callback.toRawHandle()
     };
-    if (onNotification != null) {
+    if (onShowNotification != null) {
       headlessInitializationSettings['onNotificationCallbackDispatcher'] =
-          PluginUtilities.getCallbackHandle(onNotification).toRawHandle();
+          PluginUtilities.getCallbackHandle(onShowNotification).toRawHandle();
     }
-    print(result.toString());
+
     await _channel.invokeMethod(
         'initializeHeadlessService', headlessInitializationSettings);
     return result;
@@ -111,6 +111,7 @@ class FlutterLocalNotificationsPlugin {
   Future show(int id, String title, String body,
       NotificationDetails notificationDetails,
       {String payload}) async {
+    _validateId(id);
     var serializedPlatformSpecifics =
         _retrievePlatformSpecificNotificationDetails(notificationDetails);
     await _channel.invokeMethod('show', <String, dynamic>{
@@ -124,6 +125,7 @@ class FlutterLocalNotificationsPlugin {
 
   /// Cancel/remove the notification with the specified id. This applies to notifications that have been scheduled and those that have already been presented.
   Future cancel(int id) async {
+    _validateId(id);
     await _channel.invokeMethod('cancel', id);
   }
 
@@ -136,6 +138,7 @@ class FlutterLocalNotificationsPlugin {
   Future schedule(int id, String title, String body, DateTime scheduledDate,
       NotificationDetails notificationDetails,
       {String payload}) async {
+    _validateId(id);
     var serializedPlatformSpecifics =
         _retrievePlatformSpecificNotificationDetails(notificationDetails);
     await _channel.invokeMethod('schedule', <String, dynamic>{
@@ -153,6 +156,7 @@ class FlutterLocalNotificationsPlugin {
   Future periodicallyShow(int id, String title, String body,
       RepeatInterval repeatInterval, NotificationDetails notificationDetails,
       {String payload}) async {
+    _validateId(id);
     var serializedPlatformSpecifics =
         _retrievePlatformSpecificNotificationDetails(notificationDetails);
     await _channel.invokeMethod('periodicallyShow', <String, dynamic>{
@@ -170,6 +174,7 @@ class FlutterLocalNotificationsPlugin {
   Future showDailyAtTime(int id, String title, String body,
       Time notificationTime, NotificationDetails notificationDetails,
       {String payload}) async {
+    _validateId(id);
     var serializedPlatformSpecifics =
         _retrievePlatformSpecificNotificationDetails(notificationDetails);
     await _channel.invokeMethod('showDailyAtTime', <String, dynamic>{
@@ -188,6 +193,7 @@ class FlutterLocalNotificationsPlugin {
   Future showWeeklyAtDayAndTime(int id, String title, String body, Day day,
       Time notificationTime, NotificationDetails notificationDetails,
       {String payload}) async {
+    _validateId(id);
     var serializedPlatformSpecifics =
         _retrievePlatformSpecificNotificationDetails(notificationDetails);
     await _channel.invokeMethod('showWeeklyAtDayAndTime', <String, dynamic>{
@@ -228,4 +234,11 @@ class FlutterLocalNotificationsPlugin {
   Future _handleMethod(MethodCall call) {
     return onSelectNotification(call.arguments);
   }
+
+  void _validateId(int id) {
+    if (id > 0x7FFFFFFF || id < -0x80000000) {
+      throw ArgumentError(
+          'id must fit within the size of a 32-bit integer i.e. in the range [-2^31, 2^31 - 1]');
+    }
+  }
 }

pubspec.yaml

@@ -1,6 +1,6 @@
 name: flutter_local_notifications
 description: A cross platform plugin for displaying and scheduling local notifications for Flutter applications with the ability to customise for each platform.
-version: 0.4.0
+version: 0.4.1
 author: Michael Bui <[email protected]>
 homepage: https://github.com/MaikuB/flutter_local_notifications
 
@@ -9,6 +9,7 @@ dependencies:
     sdk: flutter
   meta: ^1.0.4
   platform: ^2.0.0
+  fixnum: ^0.10.8
 
 dev_dependencies:
   flutter_test: