Notification support

[tonyho]

Is your feature request related to a problem? Please describe.

We want to show a notification toast to hint information to users, but it seems no such function in Wails and its roadmap.

Describe the solution you'd like

Notification should be added.

Describe alternatives you've considered

Toast function which is similiar to Android Toas.

Additional context

No response

[lyimmi]

I don't know if there is a plan for notifications, but beeep is a good package for native notifications IMO:
https://github.com/gen2brain/beeep .

[leaanthony]

Added to Roadmap 👍

[lyimmi]

As @leaanthony suggested, I'm trying to put together an API proposal and I'm looking at the notification capabilities of Windows, macOs and linux. Windows has the most extensive functionality, linux and macOS has a "simpler" API.

My question would be, what is the goal, a common API with functions that work everywhere, or one where each OS can have its own settings, or some form of hybrid from the two with an override style solution.

Case one:
A common API for all supported OS with "limited" functionality.

• title
• message
• icon
• image (only windows)
• action buttons

We may lose some functionality on windows, but when you create a notification it would behave the same way on every OS.

Case two:
An API with separate options for each OS.

One would have to configure every notification for each OS they want to support, probably the only common options for a notification would be the title and a message (and maybe action buttons).

Case three:
An API with a "limited" common functionality but with separate options for each OS.

The main API would work as described in the first case with the basic functionality, but has OS specific options like timing, sound, position, or for windows status/download bars, etc.

[leaanthony]

Awesome @lyimmi ! As far as API goes, it's ok to have a single struct of options for all platforms where options are ignored if not supported 👍

[lyimmi]

Here is my first draft of the Notification API. I think if we want to have more than a title, message and an icon, we need to have OS specific options. As far as I can tell Electron only supports these three options as default.

Even the timeout is different on each os, on linux it's set in milliseconds, on windows it's a dateTime, on macOs its not available. Handling the actions / buttons is totally different as well.

Maybe the click on the notification could be handled commonly too.

It is more of a conversation starter than a complete API.

// LinuxActionInvokedHandler handles signals returned by activating actions
type LinuxActionInvokedHandler func(signal *LinuxNotificationActionInvokedSignal, options ...interface{})

// LinuxNotificationAction represents a Notification action for a notification
type LinuxNotificationAction struct {

	// Key is the actions's identifier
	Key string

	// Label is shown on the notification
	Label string
}

// LinuxNotificationActionInvokedSignal holds data from any signal received regarding Actions invoked
type LinuxNotificationActionInvokedSignal struct {

	// ID of the Notification the action was invoked for
	NotificationID uint32

	// Key from the activated action
	ActionKey string
}

type LinuxNotificationOptions struct {

	// ReplacesID is used to replace an existing notification.
	ReplacesID uint32

	// Actions to be shown.
	Actions []LinuxNotificationAction

	// OnAction handles the activated action's signal.
	OnAction LinuxActionInvokedHandler

	// Timeout of the notification
	Timeout time.Duration
}

// NotificationProgressBar shows a progress bar. (Windows only)
type NotificationProgressBar struct {

	// Gets or sets an optional title string. Supports data binding.
	Title string

	// Gets or sets the value of the progress bar. Supports data binding.
	// Defaults to 0. Can either be a double between 0.0 and 1.0, AdaptiveProgressBarValue.
	// Indeterminate, or new BindableProgressBarValue("myProgressValue").
	Value float32

	// Gets or sets an optional string to be displayed instead of the default percentage string.
	// If this isn't provided, something like "70%" will be displayed.
	ValueStringOverride string

	// Gets or sets a status string (required), which is displayed underneath the progress bar on the left.
	// This string should reflect the status of the operation, like "Downloading..." or "Installing..."
	Status string
}

// NotificationHeroImage A featured "hero" image that is displayed on the toast and within Action Center. (Windows only)
type NotificationHeroImage struct {

	// The URL to the image. ms-appx, ms-appdata, and http are supported.
	// Http images must be 200 KB or less in size.
	Source string

	// Alternate text describing the image, used for accessibility purposes.
	AlternateText string

	// Set to "true" to allow Windows to append a query string to the image URL
	// supplied in the toast notification. Use this attribute if your server hosts
	// images and can handle query strings, either by retrieving an image
	// variant based on the query strings or by ignoring the query string and
	// returning the image as specified without the query string.
	//
	// This query string specifies scale, contrast setting, and language; for instance,
	// a value of "www.website.com/images/hello.png" given in the notification becomes
	// "www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us"
	AddImageQuery bool
}

type WindowsNotificationOptions struct {

	// HeroImage shows a full size image.
	HeroImage *NotificationHeroImage

	// ProgressBar shows a progress bar style notification.
	ProgressBar *NotificationProgressBar
        
        // ExpirationTime sets the expiration time for the notification.
        ExpirationTime time.Time
}

// NotificationOptions sets up a notification to be sent.
type NotificationOptions struct {

	// Applications identifier.
	AppID string

	// AppIcon used to show an icon on the notification. Absolute path to the icon.
	AppIcon string

	// Title is a summary for the notification.
	Title string

	// Message is the notification's message.
	Message string

	// LinuxOptions holds the linux specific options for a notification.
	LinuxOptions *LinuxNotificationOptions

	// WindowsOptions holds the windows specific options for a notification.
	WindowsOptions *WindowsNotificationOptions

	// Timeout is the duration for how long a notification is shown.
	Timeout time.Duration
}

Usage would look something like this:

no := NotificationOptions{
		AppID:      "Wails test",
		AppIcon:    "/wails/build/appicon.png",
		Title:      "wails test",
		Message:    name,
		LinuxOptions: &LinuxNotificationOptions{
			ReplacesID: 0,
			Actions: []LinuxNotificationAction{
				{Key: "btn-1", Label: "Button 1"},
				{Key: "btn-2", Label: "Button 2"},
			},
			OnAction: func(signal *LinuxNotificationActionInvokedSignal, options ...interface{}) {
				fmt.Printf("key: %v, label: %v", signal.NotificationID, signal.ActionKey)
			},
			Timeout: time.Second * 10,
		},
		WindowsOptions: &WindowsNotificationOptions{
			HeroImage: &NotificationHeroImage{
				Source:        "/path/to/image.jpg",
				AlternateText: "alternate text",
				AddImageQuery: false,
			},
			ProgressBar: &NotificationProgressBar{
				Title:               "title",
				Value:               0.5,
				ValueStringOverride: "10 out of a 100",
				Status:              "progress...",
			},
                        ExpirationTime: time.Now().Add(24 * time.Hour),
		},
	}


	runtime.SendNotification(ctx, no)

[willdot]

For a work side project, I needed something to send notifications on macOS. All of the existing libraries I found were either deprecated or no longer maintained (and so features didn't work on recent versions of macOS), or the beeep one suggested earlier in this issue would cause script manager to launch when used, which isn't nice UX.

However I found a library / binary (written in Objective-C) that is maintained and fairly feature complete but needed a Go library to work with it. So I created one that I'm using.

https://github.com/willdot/gomacosnotify

It does require the Alterer binary to be embedded and then installed into a temp location on the users machine, however I'm sure there's a way to stop that so that it's opt in (ie you want notifications and so the binary then gets used), possibly via build tags?

Happy to work together to get something working for notifications working (on macOS) using the library I've created and open to API changes etc.