user-notify 0.4.2

Show desktop notifications to end users on linux, macOS and windows.
Documentation

user-notify

Simple library to implement user facing notifications in end-user applications on macOS, Linux and Windows.

The name user-notify is inspired by how the system API is called in the Apple ecosystem (“User Notifications”).

What can it do?

You can send notifications to your users using this crate. Goal of this crate is to provide an API that just works and offers enough of the platform specific API to be useful for creating full apps like instant messengers.

  • Uses system APIs directly, you can contribute to this crate to add options for using the rest of the system API.
    • In the future this crate could even support contact avatars and macOS focus.
  • Buttons in notifications (macOS, todo: windows, Linux).
  • Inline Reply to notifications (macOS, todo: windows).
  • Images in notifications.
  • Notifications are identified by metadata that you can add to them (windows, macOS).
  • Notification can persist across sessions and can be used to start your app (windows, macOS).
  • Async API with Tokio.
  • Not many dependencies.

Currently there is no built-in support for timeouts on notifications (see #4).

If you this crate is not for you, then you may like https://github.com/hoodie/notify-rust, which is an established crate, but has less feature support on macOS.

System Requirements:

  • macOS 10.14 or above
    • Note for developers: on macOS this only works inside an app package with a “Bundle ID”, also you need an Apple developer account to sign it.
  • Windows 10 or above
  • Linux with a desktop/notification-daemon which supports the org.freedesktop.Notifications dbus protocol. (most modern desktop environments do)

Usage

TODO : for now look in these places:

History of this crate

This library was initially created as replacement for tauri's notification APIs, because they did not implement all notification features that we needed for our project of porting the Delta Chat instant messenger from electron to tauri (Basic features like reacting to clicks on notifications were missing in the rust api).

Features by operating system

Legend:

  • ✅ — is supported
  • #issue-number — tracking issue for implementing it
  • ❌ — not planned, since platform has no support for it (yet)
  • NO — not necessary on platform, so implemented as “no operation”
  • 🏃 — does not work across sessions, just in current session
What API macOS Linux Windows
Primary description Notification.title ✅ ✅ ✅
Main content Notification.body ✅ ✅ ✅
secondary description Notification.subtitle ✅ ❌ ✅
Image Attachment Notification.set_image ✅ ✅ ✅
Override app icon Notification.set_icon ❌ ✅ ✅
Group notifications by thread Notification.set_thread_id ✅ ❌ #3
Set category/template with actions Notification.set_category_id ✅ ✅ ✅
Set notification data Notification.set_user_info ✅ ✅🏃 ✅
Persistent notifications across sessions(keeping their data even when you restart the app / handle notifications from previous sessions) - ✅ ❌ ✅
Get permission state NotificationManager .get_notification_permission_state ✅ ❌ NO
Ask for permission NotificationManager .first_time_ask_for_notification_permission ✅ ❌ ❌
Remove all notifications NotificationManager .remove_all_delivered_notifications ✅ ✅🏃 ✅
Remove notifications by id NotificationManager .remove_delivered_notifications ✅ ✅🏃 ✅
Get still active notifications NotificationManager .get_active_notifications ✅ ✅🏃 ✅🏃
Action: Button NotificationCategoryAction::Action ✅ #1 #2
Action: reply input field NotificationCategoryAction::TextInputAction ✅ ❌ #2

Platform specific API:

What API macOS Linux Windows
Set App icon to be round Notification.set_icon_round_crop ❌ ❌ ✅
Set xdg notification Category Notification.set_xdg_category ❌ ✅ ❌
Override app name Notification.set_xdg_app_name ❌ ✅ ❌

Testing the example

Linux

RUST_LOG=debug cargo run --example test

macOS

On macOS you need a signed app package, otherwise notifications don't work. So may only work fully in released/packaged versions when you use tauri, you can use the "mock" implementation in debug mode which just logs to the console.

You can build and package the example (examples/test.rs) for macOS with this helper script:

security find-identity -v -p codesigning
# replace the zeros with the signing key you want to use
APPLE_SIGNING_IDENTITY=00000000000000000000000000000000000000 ./test_example_macos.sh

Windows

TODO: instructions for windows (I don't remember if it also needed custom steps)

Useful Links

These links can be useful for reference when contributing to this plugin.

Contributing

Contributions are welcome. Just be nice to everyone, if you are unsure what being nice and fair means, then refer to https://delta.chat/en/community-standards.

Credits

Contributors

Funding