Local Notifications In Flutter
Notifications are an excellent way to engage your users to go back to your application or to make them to pay attention to something while in the application.
There are two types of notifications:
- Push Notifications
- Local Notifications
As the title of this article suggests, we won’t be focusing on Push notifications (also because it is something that has been documented heavily). Instead, we will only focus on local notifications. The difference between the two stem from one major point:
Local notifications originate from the application itself, as opposed to Push notifications which are triggered from a remote server.
For this article’s purpose we will be using the vanilla project that is created when you open a new Flutter application (the one with the counter)., minus all the related counter bits.
As of writing this article, the latest version is 5.0.0+1, so for any future readers, please bear this in mind.
Setup
To allow our application to use local notifications, we need to add the flutter_local_notifications package to our project. Add the following to your pubspec.yaml file, under dependencies:
Run the command :
Pub getSince the local notifications package needs to be initialized, we will be creating a service class to handle this logic for our entire application. This class will also expose methods to create/send/cancel notifications. Create a new dart file named notification_service.dart with the following code:
The code above translates to a Singleton object in dart. Make sure to import the local notification package at the top of this file.
Integration
Due to the fact that Flutter is a cross platform framework, every package that is created for it needs to support both iOS and Android devices. Because notifications are handled very differently between iOS and Android, there are several calibrations that need to be made when using the local notifications package.
First we need to create an instance for the FlutterLocalNotificationPlugin. We will use this object to initialize settings for Android and iOS and also for other notification purposes.
We now need to initialize the local notification plugin with specific settings for Android and for iOS. To do so, we need to create an InitializationSettings object. It accepts arguments for the following operating systems: Android, iOS and MacOS.
We won’t be discussing MacOS here as it is similar to configuring iOS
Android
Here, it is fairly simple as there is only one mandatory argument to pass, defaultIcon(String). It represents the icon that will be displayed in the notification. Here you need to pass the name of the icon you want to be used. You must place this icon inside the drawable directory. The full path to it is:
YOUR_APPLICATION_NAME\android\app\src\main\res\drawable\YOUR_APP_ICON.png
There is no need for requesting any permissions.
iOS
As with most subjects related to iOS, things here get a bit more complicated. Due to the nature of how notifications are handled between different versions of the operating system, there is a need here for some extra configurations.
Inside the AppDelegate file you need to add the following lines of code:
It is required to ask permission from the user for various issues related to notifications. Therefore, the initializer object for iOS has the following arguments:
Each of them is self explanatory but relates to a different aspect in a notification. To correspond with these permissions are also default values you can set for each of them.
These options are there, since the initialization of the local notifications plugin may cause the operating system to present permissions dialogs to the user at a time when you don’t want them to show up. If you don’t want this behavior, you can set all of these values to false.
One more caveat in iOS has to do with the difference in behavior between notifications being presented to the user when your application is in the foreground or when it is in the background. Out of the box, the operating system will not display a notification to the user if the application is in the foreground. The plugin itself will take care of displaying a notification when the application is in the foreground, but below iOS10, there is a need to give a callback method onDidReceiveLocalNotification that will handle the user’s interaction with the notification.
After configuring specific platform initializations, its time to wrap all this logic into a method in our notification service. Our best approach here is to create an init method which will get called from our main.dart file when the application first launches.
Notice that after creating instances for platform specific initialization settings, we also need to create an InitializationSettings object which we pass in our platform specific initialization settings objects.
Our last step here is to call the initialize method on the FlutterLocalNotificationsPlugin object. Besides the initialization settings from above, it also has another argument called onSelectNotification. This argument represents the callback that will be called once a notification has been tapped and it is an optional argument. This callback has one argument called payload which will hold any data that is passed through the notification.
In our main.dart file, we will call the init method like this:
Use Cases - Showing A Notification
To display a notification, you need to create an appropriate notification details instance(Android/iOS). Each platform has its own specific arguments that need to be passed in.
The example above shows only several of the arguments you can pass to AndroidNotificationDetails. The list is a lot longer and you can check it out here.
Next, we will create a NotificationDetails object and pass it our platform specific notification details object.
Then we need to call the show method of the FlutterLocalNotificationPlugin.
The parameters here are more self explanatory, but we will go over them:
- id - the identifier of the notification. Each notification must have a unique identifier
- title - the title of the notification
- body - what we want to display as the main message of our notification
- notificationDetails - the notification details object we discussed above
- payload - the data that we want to pass with this notification so that it can be used later when the notification is tapped on and our application opens up again
An example looks like this:
Use Cases - Scheduling A Notification
Scheduling a notification requires passing in a time and date relative to the timezone of the user’s device. This is to overcome differences in time that can be caused by daylight savings. Since the local notifications plugin already contains the timezone library, we don’t need to add any other dependency in our pubspec.yaml file. We do need to import it to our notification service and to also initialize it.
To schedule a notification, we need to use the zoneSchedule method:
It shares several similarities with the show method, but has arguments that relate to when the notification should be sent. Let’s look at them one by one:
- scheduledDate - this is the parameter that tells the notification when to be sent. You can get the date today and add to it the amount of time you wish
- uiLocalNotificationDateInterpretation - used in iOS versions below 10 (for lack of support) to interpret the time as absolute time or wall clock time
- androidAllowWhileIdle - specifies if the notification should be sent even when the device is in low power idle mode
An example looks like this:
Canceling A Notification
When cancelling a notification you have two options:
- You can cancel a specific notification
- You can cancel all pending notifications
To cancel a specific notification, you have to use the notification id.
To cancel all notifications, you use the cancelAll method:
There’s a lot more that can be done with the local notification package and I urge you to read more about it and check out the documentation.
To see a real world example of an application using local notifications, you can head over here:
To see the source code, head over here:
Follow Flutter Community on Twitter: https://www.twitter.com/FlutterComm
