js_notifications

An extended NotificationsAPI for Dart Web notifications.

UI Examples

Examples of notifications on different platforms.

Simple Notification

Example of a simple notification:

JsNotificationsPlatform.instance.showNotification("Test Notification", tag: "test");

macOS

Windows

Linux

Coming soon

Notification with action

Example of a notification with actions:

JsNotificationsPlatform.instance.showNotification(
    "Oh no!",
    body: "Subverted expectations result in expected unexpected expectations. Anyway, check the icon...",
    tag: "inquisition",
    icon: "https://pbs.twimg.com/media/CtCG_f4WcAAJY-1.jpg",
    actions: [
        JSNotificationAction(action: "dismiss", title: "Whatever"),
        JSNotificationAction(action: "unexpected", title: "Didn't expect that"),
    ],
    requireInteraction: true,
);

macOS

Note: when hovering over the notification to display actions, the image is not displayed.

Windows

Linux

Coming soon

Inspiration

The Dart Web package is limited in showing notifications, one can only show a title, body, and icon. This package extends the NotificationsAPI to allow for more customization.

Setup

Imports

Add the following to your pubspec.yaml file:

dependencies:
  js_notifications: ^0.0.3

Copy service worker

Copy the service worker file named js_notifications-sw.js from the example directory to your web directory. The name is very important, so make sure to have the file named js_notifications-sw.js.

Usage

import the package

import 'package:js_notifications/js_notifications.dart';

Grab instance


final _jsNotificationsPlugin = JsNotificationsPlatform.instance;

Requesting permission

_jsNotificationsPlugin.requestPermission().then((permission) {
    print(permission);
});

Creating a notification

_jsNotificationsPlugin.showNotification('Title', {
    body: 'Body',
    icon: 'icon.png',
    badge: 'badge.png',
    image: 'image.png',
    tag: 'tag',
    data: {
      'key': 'value'
    },
  }
);

_Note: the tag is used to identify the notification, if a notification with the same tag is shown, the previous notification is replaced.

For convenient notification access, provide a tag or one will be generated via the uuid package, specifically uuid.v4()._

Creating a notification with actions

Here, we use the actions parameter to add actions to the notification. These are filled with JSNotificationAction objects.

JsNotificationsPlatform.instance.showNotification(
    "Click me",
    body: "An interactive notification",
    tag: "interactive",
    actions: [
        JSNotificationAction(action: "dismiss", title: "Click me"),
        JSNotificationAction(action: "click-me", title: "No, click me!"),
    ],
    requireInteraction: true,
);

There are convenience methods to create actions, fromAction, fromTitle and simpleWithIcon.

Platform limitations:

  • macOS: Limited to 2 actions (text only) with Settings automatically added as a 3rd option.
  • Windows: Limited to 3 actions, fully customizable.
  • Linux: Usually limited to 3 actions, customizability based on distro & desktop environment.

Creating a "heads up" notification

For this, we use the requireInteraction: true option

JsNotificationsPlatform.instance.showNotification(
    "Attention",
    body: "I just wanted your attention",
    tag: "attention",
    actions: [
        JSNotificationAction(action: "dismiss", title: "Go away"),
    ],
    requireInteraction: true,
);

Handling notification click or close events

_jsNotificationsPlugin.actionStream.listen((event) {
    print(event);
    switch (event.action) {
        case "unexpected": {
            _sendBasicNotification("I know, neither did they.");
            break;
        }
        //... other actions
    }
});

_jsNotificationsPlugin.dismissStream.listen((event) {
    print(event);
});

Get a list of all notifications

_jsNotificationsPlugin.getAllNotifications().then((notifications) {
    notifications.forEach((notification) {
      print(notification);
    });
});

Get a specific notification

_jsNotificationsPlugin.getNotification('my-awesome-notification-tag-here').then((notification) {
    print(notification);
});

Features and bugs

Any and all feedback, PRs are welcome.

Libraries

const/const
const/sw_events
core/core
core/notification_action
core/notification_action_result
core/notification_payload
core/serializable
core/user_agent
interop/interop
interop/js_notification/enums
interop/js_notification/js_notification
interop/js_notification/js_notification_action
interop/js_notification/js_notification_options
interop/notifications_api/notification_api
js_notifications
js_notifications_web
managers/service_worker_manager
method_channel/js_notifications_method_channel
platform_interface/js_notifications_platform_interface
utils/utils