151 lines
6 KiB
Markdown
151 lines
6 KiB
Markdown
# Notifications
|
|
|
|
Each operating system has its own mechanism to display notifications to users. Electron's notification
|
|
APIs are cross-platform, but are different for each process type.
|
|
|
|
If you want to use a renderer process API in the main process or vice-versa, consider using
|
|
[inter-process communication](./ipc.md).
|
|
|
|
## Usage
|
|
|
|
Below are two examples showing how to display notifications for each process type.
|
|
|
|
### Show notifications in the main process
|
|
|
|
Main process notifications are displayed using Electron's [Notification module](../api/notification.md).
|
|
Notification objects created using this module do not appear unless their `show()` instance
|
|
method is called.
|
|
|
|
```js title='Main Process'
|
|
const { Notification } = require("electron");
|
|
|
|
const NOTIFICATION_TITLE = "Basic Notification";
|
|
const NOTIFICATION_BODY = "Notification from the Main process";
|
|
|
|
new Notification({
|
|
title: NOTIFICATION_TITLE,
|
|
body: NOTIFICATION_BODY,
|
|
}).show();
|
|
```
|
|
|
|
Here's a full example that you can open with Electron Fiddle:
|
|
|
|
```javascript fiddle='docs/fiddles/features/notifications/main'
|
|
const { Notification } = require("electron");
|
|
|
|
const NOTIFICATION_TITLE = "Basic Notification";
|
|
const NOTIFICATION_BODY = "Notification from the Main process";
|
|
|
|
new Notification({
|
|
title: NOTIFICATION_TITLE,
|
|
body: NOTIFICATION_BODY,
|
|
}).show();
|
|
```
|
|
|
|
### Show notifications in the renderer process
|
|
|
|
Notifications can be displayed directly from the renderer process with the
|
|
[web Notifications API](https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API/Using_the_Notifications_API).
|
|
|
|
```js title='Renderer Process'
|
|
const NOTIFICATION_TITLE = "Title";
|
|
const NOTIFICATION_BODY =
|
|
"Notification from the Renderer process. Click to log to console.";
|
|
const CLICK_MESSAGE = "Notification clicked";
|
|
|
|
new Notification(NOTIFICATION_TITLE, { body: NOTIFICATION_BODY }).onclick =
|
|
() => console.log(CLICK_MESSAGE);
|
|
```
|
|
|
|
Here's a full example that you can open with Electron Fiddle:
|
|
|
|
```javascript fiddle='docs/fiddles/features/notifications/renderer'
|
|
const NOTIFICATION_TITLE = "Title";
|
|
const NOTIFICATION_BODY =
|
|
"Notification from the Renderer process. Click to log to console.";
|
|
const CLICK_MESSAGE = "Notification clicked";
|
|
|
|
new Notification(NOTIFICATION_TITLE, { body: NOTIFICATION_BODY }).onclick =
|
|
() => console.log(CLICK_MESSAGE);
|
|
```
|
|
|
|
## Platform considerations
|
|
|
|
While code and user experience across operating systems are similar, there
|
|
are subtle differences.
|
|
|
|
### Windows
|
|
|
|
For notifications on Windows, your Electron app needs to have a Start Menu shortcut with an
|
|
[AppUserModelID][app-user-model-id] and a corresponding [ToastActivatorCLSID][toast-activator-clsid].
|
|
|
|
Electron attempts to automate the work around the AppUserModelID and ToastActivatorCLSID. When
|
|
Electron is used together with Squirrel.Windows (e.g. if you're using electron-winstaller),
|
|
[shortcuts will automatically be set correctly][squirrel-events].
|
|
|
|
In production, Electron will also detect that Squirrel was used and will automatically call
|
|
`app.setAppUserModelId()` with the correct value. During development, you may have
|
|
to call [`app.setAppUserModelId()`][set-app-user-model-id] yourself.
|
|
|
|
:::info Notifications in development
|
|
|
|
To quickly bootstrap notifications during development, adding
|
|
`node_modules\electron\dist\electron.exe` to your Start Menu also does the
|
|
trick. Navigate to the file in Explorer, right-click and 'Pin to Start Menu'.
|
|
Then, call `app.setAppUserModelId(process.execPath)` in the main process to see notifications.
|
|
|
|
:::
|
|
|
|
#### Use advanced notifications
|
|
|
|
Windows also allow for advanced notifications with custom templates, images, and other flexible
|
|
elements.
|
|
|
|
To send those notifications from the main process, you can use the userland module
|
|
[`electron-windows-notifications`](https://github.com/felixrieseberg/electron-windows-notifications),
|
|
which uses native Node addons to send `ToastNotification` and `TileNotification` objects.
|
|
|
|
While notifications including buttons work with `electron-windows-notifications`,
|
|
handling replies requires the use of
|
|
[`electron-windows-interactive-notifications`](https://github.com/felixrieseberg/electron-windows-interactive-notifications),
|
|
which helps with registering the required COM components and calling your
|
|
Electron app with the entered user data.
|
|
|
|
#### Query notification state
|
|
|
|
To detect whether or not you're allowed to send a notification, use the
|
|
userland module [`windows-notification-state`][windows-notification-state].
|
|
|
|
This module allows you to determine ahead of time whether or not Windows will silently throw the
|
|
notification away.
|
|
|
|
### macOS
|
|
|
|
Notifications are straightforward on macOS, but you should be aware of
|
|
[Apple's Human Interface guidelines regarding notifications][apple-notification-guidelines].
|
|
|
|
Note that notifications are limited to 256 bytes in size and will be truncated
|
|
if you exceed that limit.
|
|
|
|
#### Query notification state
|
|
|
|
To detect whether or not you're allowed to send a notification, use the userland module
|
|
[`macos-notification-state`][macos-notification-state].
|
|
|
|
This module allows you to detect ahead of time whether or not the notification will be displayed.
|
|
|
|
### Linux
|
|
|
|
Notifications are sent using `libnotify`, which can show notifications on any
|
|
desktop environment that follows [Desktop Notifications
|
|
Specification][notification-spec], including Cinnamon, Enlightenment, Unity,
|
|
GNOME, and KDE.
|
|
|
|
[notification-spec]: https://developer-old.gnome.org/notification-spec/
|
|
[app-user-model-id]: https://learn.microsoft.com/en-us/windows/win32/shell/appids
|
|
[set-app-user-model-id]: ../api/app.md#appsetappusermodelidid-windows
|
|
[squirrel-events]: https://github.com/electron/windows-installer/blob/main/README.md#handling-squirrel-events
|
|
[toast-activator-clsid]: https://learn.microsoft.com/en-us/windows/win32/properties/props-system-appusermodel-toastactivatorclsid
|
|
[apple-notification-guidelines]: https://developer.apple.com/design/human-interface-guidelines/notifications
|
|
[windows-notification-state]: https://github.com/felixrieseberg/windows-notification-state
|
|
[macos-notification-state]: https://github.com/felixrieseberg/macos-notification-state
|