https://github.com/cybex-dev/js_notifications
An extended NotificationsAPI for Dart Web notifications
https://github.com/cybex-dev/js_notifications
flutter flutter-package flutter-plugin flutter-ui flutter-web javascript notifications notifications-api notifications-plugin service-worker web
Last synced: 25 days ago
JSON representation
An extended NotificationsAPI for Dart Web notifications
- Host: GitHub
- URL: https://github.com/cybex-dev/js_notifications
- Owner: cybex-dev
- License: mit
- Created: 2024-09-19T08:30:31.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2025-03-06T09:47:19.000Z (8 months ago)
- Last Synced: 2025-03-06T10:34:35.304Z (8 months ago)
- Topics: flutter, flutter-package, flutter-plugin, flutter-ui, flutter-web, javascript, notifications, notifications-api, notifications-plugin, service-worker, web
- Language: Dart
- Homepage: https://js-notifications-web.web.app/
- Size: 653 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# js_notifications
An extended NotificationsAPI for Dart Web notifications.
## UI Examples
Examples of notifications on different platforms.
### Simple Notification
Example of a simple notification:
```dart
JsNotificationsPlatform.instance.showNotification("Test Notification", tag: "test");
```
### macOS
### Windows
### Linux
### Notification with action
Example of a notification with actions:
```dart
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
## 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:
```yaml
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
```dart
import 'package:js_notifications/js_notifications.dart';
```
### Grab instance
```dart
final _jsNotificationsPlugin = JsNotificationsPlatform.instance;
```
### Requesting permission
```dart
_jsNotificationsPlugin.requestPermission().then((permission) {
print(permission);
});
```
### Creating a notification
```dart
_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](https://pub.dev/packages/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.
```dart
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
```dart
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
```dart
_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
```dart
_jsNotificationsPlugin.getAllNotifications().then((notifications) {
notifications.forEach((notification) {
print(notification);
});
});
```
### Get a specific notification
```dart
_jsNotificationsPlugin.getNotification('my-awesome-notification-tag-here').then((notification) {
print(notification);
});
```
## Features and bugs
Any and all feedback, PRs are welcome.