awesome_notifications 0.0.6+5
awesome_notifications: ^0.0.6+5 copied to clipboard

A complete solution to create Local Notifications and Push Notifications (Media Notifications, Big Picture, Big text, etc), through Firebase or another services, using Flutter.

Awesome Notifications - Flutter #

Features #

  • Create Local Notifications on Android, iOS and Web using Flutter.
  • Easy to integrate with Push notification's service as Firebase Messaging or any another one;
  • Easy to use and highly customizable.
  • Add images, sounds, emoticons, buttons and different layouts on your notifications.
  • Notifications could be created at any moment (on Foreground, Background or even when the application is terminated/killed).
  • High trustworthy on receive notifications in any Application lifecycle.
  • Notifications are received on Flutter level code when they are created, displayed, dismissed or even tapped by the user.
  • Notifications could be scheduled repeatedly or not, with seconds precision.

Some android notification examples:

Some iOS notification examples (work in progress):

Notification Types Available #

  • Basic notification
  • Big picture notification
  • Media notification
  • Big Text notification
  • Inbox notification
  • Notifications with action buttons
  • Grouped notifications
  • Progress bar notifications

All notifications could be created locally or via Firebase services, with all the features.


Working progress percentages of awesome notifications plugin

Next steps #

  • Include Firebase Cloud Message support for iOS (Finished)
  • Finish notifications layouts for iOS (Finished)
  • Finish notifications schedules for iOS (Finished)
  • Expiration date for notifications (not accomplished due to iOS limitations) (
  • Add an option to choose if a notification action should bring the app to foreground or not.
  • Include Web support
  • Include support for another push notification services (Wonderpush, One Signal, IBM, AWS, Azure, etc) (Finished)
  • Video layout for notifications
  • Carousel layout for notifications
  • Increase the tolerance in the json deserialization process, to accept different types and convert them to the expected.

Main Philosophy #

Considering all the many different devices available, with different hardware and software resources, this plugin ALWAYS shows the notification, trying to use the maximum resources available. If the resource is not available, the notification ignores that specific resource, but shows the rest of notification anyway.

Example: If the device has LED colored lights, use it. Otherwise, ignore the lights, but shows the notification with all another resources available. In last case, shows at least the most basic notification.

Also, the Notification Channels follows the same rule. If there is no channel segregation of notifications, use the channel configuration as only defaults configuration. If the device has channels, use it as expected to be.

And all notifications sent while the app was killed are registered and delivered as soon as possible to the Application, after the plugin initialization, respecting the delivery order.

This way, your Application will receive all notifications at Flutter level code.

How to show Local Notifications #

  1. Add awesome_notifications as a dependency in your pubspec.yaml file.
awesome_notifications: any # Any attribute updates automatically your source to the last version
  1. import the plugin package to your dart code
import 'package:awesome_notifications/awesome_notifications.dart';
  1. Initialize the plugin on main.dart, with at least one native icon and one channel
    // set the icon to null if you want to use the default app icon
            channelKey: 'basic_channel',
            channelName: 'Basic notifications',
            channelDescription: 'Notification channel for basic tests',
            defaultColor: Color(0xFF9D50DD),
            ledColor: Colors.white
  1. Request the user authorization to send local and push notifications (Remember to show a dialog alert to the user before call this request)
AwesomeNotifications().isNotificationAllowed().then((isAllowed) {
  if (!isAllowed) {
    // Insert here your friendly dialog box before call the request method
    // This is very important to not harm the user experience
  1. On your main page, starts to listen the notification actions (to detect tap)

            arguments: { id: } // your page params. I recommend to you to pass all *receivedNotification* object

  1. In any place of your app, create a new notification
  content: NotificationContent(
      id: 10,
      channelKey: 'basic_channel',
      title: 'Simple Notification',
      body: 'Simple body'


Example Apps #

With the examples bellow, you can check all the features and how to use the Awesome Notifications in your app.
Complete example with all the features available
An simple but excellent app example of how to implement FCM with Awesome Notifications, created by bayuramadeza

To run the examples, follow the steps bellow:

  1. Install GitHub software in your local machine. I strongly recommend to use GitHub Desktop.
  2. Go to one of the GitHub repositories
  3. Clone the project to your local machine
  4. Open the project with Android Studio or any other IDE
  5. Sync the project dependencies running flutter pub get
  6. On iOS, run pod install to sync the native dependencies
  7. Debug the application with a real device or emulator

Schedule Limitations #

Due to the way that background task and notification schedules works on iOS, wasn't possible yet to enable all the schedule features on iOS while the app is in Background and even when the app is terminated (Killed). Thanks to this, the scheduling for android has also regressed to the iOS limitations level, to ensure for the developer the same behaviour in any platform. But it could be manually reactivated in java native code.

A support ticket was opened for Apple in order to resolve this issue. You can follow the progress of the process here.

Using Firebase Services (Optional) #

The service used for this tutorial is Firebase Messaging, but you could use any other of your choice.

1 - To activate the Firebase Cloud Messaging service, please follow the respective step for your desired platform:

Android #

First things first, to create your Firebase Cloud Message and send notifications even when your app is terminated (killed), go to the Firebase Console and create a new project.

After that, go to "Cloud Messaging" option and add an "Android app", put the packge name of your project (certifies to put the correct one) to generate the file google-services.json.

Download the file and place it inside your [app]/android/app/ folder.

Add the classpath to the [project]/android/build.gradle file. (Firebase ones was already added by the plugin)

dependencies {
    classpath ''
    // Add the google services classpath
    classpath ''

Add the apply plugin to the [project]/android/app/build.gradle file.

apply plugin: ''

iOS #

Based on

Go to "Cloud Messaging" option and add an "iOS app", put the package name of your project (certifies to put the correct one) to generate the file GoogleService-info.plist.

Download the file and place it inside your [app]/ios/Runner/ folder using XCode. (Do not use Finder to copy and paste the file, use the XCode)

After that, in your Google Console, go to General (Gear icon) -> Cloud Messaging -> iOS configuration and send your APNs key and include your iOS Team ID. To generate your APNs keys, follow the tutorial bellow:

Enabling Push Notifications in your Dart/Flutter code #

(those steps are based on instructions)

2 - Add the firebase_core and firebase_messaging dependency to your pubspec.yaml file.

    sdk: flutter
  firebase_core: "^1.0.4"
  firebase_messaging: "^9.1.2"

3 - Download the dependencies with $ flutter pub get.

4 - Inside your main.dart file, add the follow lines:

void main() async {

        // Your notification channels go here

  // Create the initialization for your desired push service here
  FirebaseApp firebaseApp = await Firebase.initializeApp();


// Declared as global, outside of any class
Future<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async {

  // If you're going to use other Firebase services in the background, such as Firestore,
  // make sure you call `initializeApp` before using other Firebase services.
  await Firebase.initializeApp();

  print("Handling a background message: ${message.messageId}");

  // Use this method to automatically convert the push data, in case you gonna use our data standard

Now, firebase messaging should work at any application lifecycle, for any supported platform.

Notification Life Cycle #

Notifications are received by local code or Push service using native code, so the messages will appears immediately or at schedule time, independent of your application state.

Flutter Streams #

The Flutter code will be called as soon as possible using Dart Streams.

createdStream: Fires when a notification is created displayedStream: Fires when a notification is displayed on system status bar actionStream: Fires when a notification is tapped by the user dismissedStream: Fires when a notification is dismissed by the user

PlatformApp in ForegroundApp in BackgroundApp Terminated (Killed)
AndroidFires all streams immediately after occursFires all streams immediately after occursFires createdStream, displayedStream and dismissedStream after the plugin initializes on Foreground, but fires actionStream immediately after occurs
iOSFires all streams immediately after occursFires createdStream, displayedStream and dismissedStream after the app returns to Foreground, but fires actionStream immediately after occursFires createdStream, displayedStream and dismissedStream after the plugin initializes on Foreground, but fires actionStream immediately after occurs

Notification Structures #

Notification Layout Types #

To show any images on notification, at any place, you need to include the respective source prefix before the path.

Layouts can be defined using 4 prefix types:

  • Default: The default layout. Also is the layout used in case of any failure found on other ones
  • BigPicture: Is the layout that shows a big picture and/or a small image.
  • BigText: Is the layout that shows more than 2 lines of text.
  • Inbox: Is the layout who lists messages or items separated by lines
  • ProgressBar: Is the layout that shows a progress bar, such as download progress bar
  • Messaging: (in construction)
  • MediaPlayer: Is the layout that shows a media controller with action buttons, that allows the user to send commands without brings the application to foreground.

Media Source Types #

To show any images on notification, at any place, you need to include the respective source prefix before the path.

Images can be defined using 4 prefix types:

  • Asset: images access through Flutter asset method. Example: asset://path/to/image-asset.png
  • Network: images access through internet connection. Example: http(s)://
  • File: images access through files stored on device. Example: file://path/to/image-asset.png
  • Resource: images access through drawable native resources. On Android, those files are stored inside [project]/android/app/src/main/drawabe folder. Example: resource://drawable/res_image-asset.png

OBS: Unfortunately, icons and sounds can be only resource media types.
OBS 2: To protect your native resources on Android against minification, please include the prefix "res_" in your resource file names. The use of the tag shrinkResources false inside build.gradle or the command flutter build apk --no-shrink is not recommended. To know more about it, please visit Shrink, obfuscate, and optimize your app

Notification Importance (Android's channel) #

Defines the notification's importance level and how it should be displayed to the user. The possible importance levels are the following:

  • Max: Makes a sound and appears as a heads-up notification.
  • Higher: shows everywhere, makes noise and peeks. May use full screen intents.
  • Default: shows everywhere, makes noise, but does not visually intrude.
  • Low: Shows in the shade, and potentially in the status bar (see shouldHideSilentStatusBarIcons()), but is not audibly intrusive.
  • Min: only shows in the shade, below the fold.
  • None: disable the respective channel.

OBS: Unfortunately, the channel's importance can only be defined on first time. After that, it cannot be changed.

Notification Action Button Types #

Notifications action buttons could be classified in 4 types:

  • Default: after user taps, the notification bar is closed and an action event is fired.
  • InputField: after user taps, a input text field is displayed to capture input by the user.
  • DisabledAction: after user taps, the notification bar is closed, but the respective action event is not fired.
  • KeepOnTop: after user taps, the notification bar is not closed, but an action event is fired.

AndroidApp in ForegroundApp in BackgroundApp Terminated (Killed)
Defaultkeeps the app in foregroundbrings the app to foregroundbrings the app to foreground
InputFieldkeeps the app in foregroundbrings the app to foregroundbrings the app to foreground
DisabledActionkeeps the app in foregroundkeeps the app in backgroundkeeps the app terminated
KeepOnTopkeeps the app in foregroundkeeps the app in backgroundkeeps the app terminated

If the app is terminated (killed):

  • Default: Wake up the app.
  • InputField: Wake up the app.
  • DisabledAction: Does not Wake up the app.
  • KeepOnTop: Does not Wake up the app.

Scheduling a notification #

Notifications could be scheduled into two exclusive types:

  • Interval: represents a interval of seconds that the notification should wait to be displayed
  • Calendar: represents a simple set of date rules that the notification should obey to be displayed

Also, both of then could be configured using:

  • allowWhileIdle: Determines if notification will send, even when the device is in critical situation, such as low battery.
  • repeats: Determines if the schedule should be repeat after be displayed. If there is no more valid date compatible with the schedule rules, the notification is automatically canceled.

Emojis (Emoticons) #

To send emojis in your local notifications, concatenate the class Emoji with your text. For push notifications, copy the emoji (unicode text) from and send it or use the format \u{1f6f8}.

OBS: not all emojis work with all platforms. Please, test the specific emoji before using it in production.

  await AwesomeNotifications().createNotification(
      content: NotificationContent(
          id: id,
          channelKey: 'basic_channel',
          title: 'Emojis are awesome too! '+ Emojis.smille_face_with_tongue + Emojis.smille_rolling_on_the_floor_laughing + Emojis.emotion_red_heart,
          body: 'Simple body with a bunch of Emojis! ${Emojis.transport_police_car} ${Emojis.animals_dog} ${Emojis.flag_UnitedStates} ${Emojis.person_baby}',
          bigPicture: '',
          notificationLayout: NotificationLayout.BigPicture,

How to send Push Notifications using Firebase Cloud Messaging (FCM) #

To send a notification using Awesome Notifications and FCM Services, you need to send a POST request to the address Due to limitations on Android and iOS, you should send a empty notification field and use only the data field to send your data, as bellow:

OBS: actionButtons and schedule are optional
OBS 2: you should not implement any native code to use FCM with Awesome Notifications. All of then was already implemented inside the plugin.
OBS 3: data only messages are classed as "low priority". Devices can throttle and ignore these messages if your application is in the background, terminated, or a variety of other conditions such as low battery or currently high CPU usage. To help improve delivery, you can bump the priority of messages. Note; this does still not guarantee delivery. More info here

    "to" : "[YOUR APP TOKEN]",
    "mutable_content" : true,
    "content_available": true,
    "priority": "high",
    "data" : {
        "content": {
            "id": 100,
            "channelKey": "big_picture",
            "title": "Huston!\nThe eagle has landed!",
            "body": "A small step for a man, but a giant leap to Flutter's community!",
            "notificationLayout": "BigPicture",
            "largeIcon": "",
            "bigPicture": "",
            "showWhen": true,
            "autoCancel": true,
            "privacy": "Private"
        "actionButtons": [
                "key": "REPLY",
                "label": "Reply",
                "autoCancel": true,
                "buttonType":  "InputField"
                "key": "ARCHIVE",
                "label": "Archive",
                "autoCancel": true
        "schedule": {
            "hour": "10",
            "minute": "0",
            "second": "0",
            "allowWhileIdle": true,
            "repeat": true

Using this pattern, you can create a notification just by calling the method below:


You can download a example of how to send Push Notifications through FCM using "Postman" here

Notification channels #

Notification channels are means by which notifications are send, defining the characteristics that will be common among all notifications on that same channel. A notification can be created, deleted and updated at any time in the application, however it is required that at least one exists during the initialization of this plugin. If a notification is created using a invalid channel key, the notification is discarded. After a notification being created, especially for Android Oreo devices and above, most of his definitions cannot be updated any more. To update all channel's definitions, it is necessary to use the ´forceUpdate´ option, which has the negative effect of automatically closing all active notifications on that channel.

Main methods to manipulate a notification channel:

  • AwesomeNotifications().setChannel: Create or update a notification channel.
  • AwesomeNotifications().removeChannel: Remove a notification channel, closing all current notifications on that same channel.

AttributeRequiredDescriptionTypeUpdatable without force modeValue LimitsDefault value
channelKeyYESString key that identifies a channel where notStringNOT AT ALLchannel must be enabledbasic_channel
channelNameYESThe title of the channel (is visible for the user on Android)StringYESunlimited
channelDescriptionYESThe channel description (is visible for the user on Android)StringYESunlimited
channelShowBadgeNOThe notification should automatically increment the badge counterboolYEStrue or falsefalse
importanceNOThe notification should automatically increment the badge counterNotificationImportanceNOEnumeratorNormal
playSoundNODetermines if the notification should play soundboolNOtrue or falsetrue
soundSourceNOSpecify a custom sound to be played (must be a native resource file)StringNOunlimited
defaultRingtoneTypeNODetermines what default sound type should be played (only for Android)DefaultRingtoneTypeYESEnumeratorNotification
enableVibrationNOActivate / deactivate the vibration functionalityboolNOtrue or falsetrue
enableLightsNODetermines that the LED lights should be on in notificationsboolNOtrue or falsetrue
ledColorNODetermines the LED lights color to be played on notificationsColorNOunlimitedColors.white
ledOnMsNODetermines the time, in milliseconds, that the LED lights must be onintNO1 - 2.147.483.647
ledOffMsNODetermines the time, in milliseconds, that the LED lights must be offintNO1 - 2.147.483.647
groupKeyNODetermines the common key used to group notifications in a compact formStringNOunlimited
groupSortNODetermines the notifications sort order inside the groupingGroupSortNOEnumeratorDesc
groupAlertBehaviorNODetermines the alert type for notifications in same groupingGroupAlertBehaviorNOEnumeratorAll
defaultPrivacyNODetermines the privacy level to be applied when the device is lockedNotificationPrivacyNOEnumeratorPrivate
iconNODetermines the notification small top icon on status barStringNOunlimited
defaultColorNODetermines the notification global color (only for Android)
lockedNODetermines if the user cannot manually dismiss the notificationboolNOtrue or falsefalse
onlyAlertOnceNODetermines if the notification should alert once, when createdboolNOtrue or falsefalse

Notification types, values and defaults #

NotificationContent ("content" in Push data) - (required) #

AttributeRequiredDescriptionTypeValue LimitsDefault value
idYESNumber that identifies a unique notificationint1 - 2.147.483.647
channelKeyYESString key that identifies a channel where not. will be displayedStringchannel must be enabledbasic_channel
titleNOThe title of notificationStringunlimited
bodyNOThe body content of notificationStringunlimited
summaryNOA summary to be displayed when the content is protected by privacyStringunlimited
showWhenNOHide/show the time elapsed since notification was displayedbooltrue or falsetrue
displayOnForegroundNOHide/show the notification if the app is in the Foreground (streams are preserved )booltrue or falsetrue
displayOnBackgroundNOHide/show the notification if the app is in the Background (streams are preserved )booltrue or falsetrue
iconNOSmall icon to be displayed on the top of notification (Android only)Stringmust be a resource image
largeIconNOLarge icon displayed at right middle of compact notificationStringunlimited
bigPictureNOBig image displayed on expanded notificationStringunlimited
autoCancelNONotification should auto cancel when gets tapped by the userbooltrue or falsetrue
colorNONotification text colorColor0x00000000 to 0xFFFFFFFF0xFF000000 (
backgroundColorNONotification background colorColor0x00000000 to 0xFFFFFFFF0xFFFFFFFF (Colors.white)
payloadNOHidden payload contentMap<String, String>Only String for valuesnull
notificationLayoutNOLayout type of notificationEnumeratorNotificationLayoutDefault
hideLargeIconOnExpandNOHide/show the large icon when notification gets expandedbooltrue or falsefalse
lockedNOBlocks the user to dismiss the notificationbooltrue or falsefalse
progressNOCurrent value of progress bar (percentage). Null for indeterminate.int0 - 100null
tickerNOText to be displayed on top of the screen when a notification arrivesStringunlimited

NotificationActionButton ("actionButtons" in Push data) - (optional) #

  • Is necessary at least one *required attribute
AttributeRequiredDescriptionTypeValue LimitsDefault value
keyYESText key to identifies what action the user took when tapped the notificationStringunlimited
label*YESText to be displayed over the action buttonStringunlimited
icon*YESIcon to be displayed inside the buttonStringmust be a resource image
enabledNOOn Android, deactivates the button. On iOS, the button disappearbooltrue or falsetrue
autoCancelNONotification should auto cancel when gets tapped by the userbooltrue or falsetrue
buttonTypeNOButton action response typeEnumeratorActionButtonTypeDefault

NotificationInterval ("schedule" in Push data) - (optional) #

AttributeRequiredDescriptionTypeValue LimitsDefault value
interval*YESMandatory initial notification fire dateInt (seconds)Positive unlimited
allowWhileIdleNODisplays the notification, even when the device is low batterybooltrue or falsefalse
repeatsNOList of precise notification fire datesbooltrue or falsefalse

NotificationCalendar ("schedule" in Push data) - (optional) #

  • Is necessary at least one *required attribute
  • Cron expression must respect the format (with seconds precision) as described in this article
AttributeRequiredDescriptionTypeValue LimitsDefault value
era,*YESSchedule era conditionIntegerPositive unlimited
year,*YESSchedule year conditionIntegerPositive unlimited
month,*YESSchedule month conditionIntegerPositive unlimited
day,*YESSchedule day conditionIntegerPositive unlimited
hour,*YESSchedule hour conditionIntegerPositive unlimited
minute,*YESSchedule minute conditionIntegerPositive unlimited
second,*YESSchedule second conditionIntegerPositive unlimited
millisecond,*YESSchedule millisecond conditionIntegerPositive unlimited
weekday,*YESSchedule weekday conditionIntegerPositive unlimited
weekOfMonth,*YESSchedule weekOfMonth conditionIntegerPositive unlimited
weekOfYear,*YESSchedule weekOfYear conditionIntegerPositive unlimited
allowWhileIdleNODisplays the notification, even when the device is low batterybooltrue or falsefalse
repeatsNOList of precise notification fire datesbooltrue or falsefalse

Common Known Issues #

Issue: The name 'DateUtils' is defined in the libraries 'package:awesome_notifications/src/utils/date_utils.dart (via package:awesome_notifications/awesome_notifications.dart)' and 'package:flutter/src/material/date.dart (via package:flutter/material.dart)'.

Fix: Use a prefix while importing or hide one of the DateUtils declarations:

import 'package:flutter/material.dart' hide DateUtils;
import 'package:flutter/material.dart' as Material show DateUtils;



Issue: So, because myApp depends on both awesome_notifications and "OtherPackageName" from sdk, version solving failed. pub get failed

Fix: The awesome_notifications plugin must be limited to all other last plugin versions in the stable bracket, to be the most compatible as possible to any flutter application in production stage. Sometimes, one of our dependencies getting older and need to be updated. Please, open a issue with this error on our GitHub community, and we gonna update it as fast as possible. But, case necessary, you can manually upgrade those dependencies into your local files. Just change the pubspec.yaml inside your awesome_notifications local folder and you should be ready to go.

To see an example of how to solve it, please go to


Issue: Invalid notification content

Fix: The notification sent via FCM services MUST respect the types of the respective Notification elements. Otherwise, your notification will be discarded as invalid one. Also, all the payload elements MUST be a String, as the same way as you do in Local Notifications using dart code.

To see more information about each type, please go to


Issue: Undefined symbol: OBJC_CLASS$_FlutterStandardTypedData / OBJC_CLASS$_FlutterError / OBJC_CLASS$_FlutterMethodChannel

Fix: Please, remove the old target extensions and update your awesome_notification plugin to the last version available

pub points


A complete solution to create Local Notifications and Push Notifications (Media Notifications, Big Picture, Big text, etc), through Firebase or another services, using Flutter.

Repository (GitHub)
View/report issues


API reference


Apache-2.0 (LICENSE)


flutter, intl, platform


Packages that depend on awesome_notifications