diff --git a/README.md b/README.md index cebf55be..c8f79c88 100644 --- a/README.md +++ b/README.md @@ -178,3 +178,4 @@ Third party libraries and resources: * [Regex for auto-linking](https://github.com/bryanwoods/autolink-js) (MIT) is used to highlight links (the library is not used) * [Statically linking go-sqlite3](https://www.arp242.net/static-go.html) * [Linked tabs in mkdocs](https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/#linked-tabs) +* [webpush-go](https://github.com/SherClockHolmes/webpush-go) (MIT) is used to send web push notifications diff --git a/docs/config.md b/docs/config.md index 3aeab614..7e1ef6c6 100644 --- a/docs/config.md +++ b/docs/config.md @@ -789,6 +789,55 @@ Note that the self-hosted server literally sends the message `New message` for e may be `Some other message`. This is so that if iOS cannot talk to the self-hosted server (in time, or at all), it'll show `New message` as a popup. +## Web Push notifications +[Web Push](https://developer.mozilla.org/en-US/docs/Web/API/Push_API) ([RFC8030](https://datatracker.ietf.org/doc/html/rfc8030)) +is supported, but needs a little configuration to enable it. Since there is no central server (other than the browser's push endpoint), +you have to configure your own [VAPID](https://datatracker.ietf.org/doc/html/draft-thomson-webpush-vapid) keys. These identify the publisher, +and are used to encrypt the messages before sending them to the push endpoint. + +Limitations: + +- Like foreground browser notifications, background push notifications require the web app to be served over HTTPS. A _valid_ + certificate is required, as service workers will not run on origins with untrusted certificates. + +- Web Push is only supported for the same server. You cannot use subscribe to web push on a topic on another server. This + is due to a limitation of the Push API, which doesn't allow multiple push servers for the same origin. + +To configure VAPID keys, first generate them: + +```sh +$ ntfy web-push generate-keys +Keys generated. + +VAPID Public Key: +AA1234BBCCddvveekaabcdfqwertyuiopasdfghjklzxcvbnm1234567890 + +VAPID Private Key: +AA2BB1234567890abcdefzxcvbnm1234567890 +``` + +Then copy the generated values into your `server.yml` or use the corresponding environment variables or command line arguments: + +```yaml +web-push-enabled: true +web-push-public-key: AA1234BBCCddvveekaabcdfqwertyuiopasdfghjklzxcvbnm1234567890 +web-push-private-key: AA2BB1234567890abcdefzxcvbnm1234567890 +web-push-subscriptions-file: /var/cache/ntfy/subscriptions.db +web-push-email-address: sysadmin@example.com + +# don't forget to set the required base-url for web push notifications +base-url: https://ntfy.example.com +``` + +The `web-push-subscriptions-file` is used to store the push subscriptions. Subscriptions do not ever expire automatically, unless the push +gateway returns an error (e.g. 410 Gone when a user has unsubscribed). + +The web app refreshes subscriptions on start and regularly on an interval, but this file should be persisted across restarts. If the subscription +file is deleted or lost, any web apps that aren't open will not receive new web push notifications until you open then. + +Changing your public/private keypair is NOT recommended. Browsers only allow one server identity (public key) per origin, and +if you change them the clients will not be able to subscribe via web push until the user manually clears the notification permission. + ## Tiers ntfy supports associating users to pre-defined tiers. Tiers can be used to grant users higher limits, such as daily message limits, attachment size, or make it possible for users to reserve topics. If [payments are enabled](#payments), diff --git a/docs/subscribe/desktop.md b/docs/subscribe/desktop.md index 65284543..b13d11a4 100644 --- a/docs/subscribe/desktop.md +++ b/docs/subscribe/desktop.md @@ -1,9 +1,17 @@ -# Using the web app as an installed PWA +# Using the web app as an installed web app + +While ntfy doesn't have a native desktop app, it is built as a [progressive web app](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps) +and thus can be installed on both desktop and mobile. + +This gives it its own launcher (e.g. shortcut on Windows, app on macOS, launcher shortcut on Linux) own window, +push notifications, and an app badge with the unread notification count. + +To receive background notifications, either the browser or the installed web app must be open. + +Web app installation is supported on Chrome and Edge on desktop, as well as Chrome on Android and Safari on iOS. +Look at the [compatibility table](https://caniuse.com/web-app-manifest) for more info. -While ntfy doesn't have a built desktop app, it is built as a progressive web app and can be installed. -This is supported on Chrome and Edge on desktop, as well as Chrome on Android and Safari on iOS. -[caniuse reference](https://caniuse.com/web-app-manifest)
diff --git a/docs/subscribe/web.md b/docs/subscribe/web.md index a563f8b0..e073bec9 100644 --- a/docs/subscribe/web.md +++ b/docs/subscribe/web.md @@ -7,35 +7,37 @@ enable them for the first time, you will be prompted to allow notifications on y - **Sound only** - If you don't enable browser notifications, a sound will play when a new notification comes in, and the tab title - will show the number of new notifications. + If you don't enable browser notifications, a sound will play when a new notification comes in, and the tab title + will show the number of new notifications. - **Browser Notifications** - This requires an active ntfy tab to be open to receive notifications. These are typically instantaneous, and will - appear as a system notification. If you don't see these, check that your browser is allowed to show notifications - (for example in System Settings on macOS). + This requires an active ntfy tab to be open to receive notifications. These are typically instantaneous, and will + appear as a system notification. If you don't see these, check that your browser is allowed to show notifications + (for example in System Settings on macOS). - If you don't want to enable background notifications, pinning the ntfy tab on your browser is a good solution to leave - it running. + If you don't want to enable background notifications, pinning the ntfy tab on your browser is a good solution to leave + it running. - **Background Notifications** - This uses the [Web Push API](https://caniuse.com/push-api). You don't need an active ntfy tab open, but in some - cases you may need to keep your browser open. + This uses the [Web Push API](https://caniuse.com/push-api). You don't need an active ntfy tab open, but in some + cases you may need to keep your browser open. + Background notifications are only supported on the same server hosting the web app. You cannot use another server, + but can instead subscribe on the other server itself. - | Browser | Platform | Browser Running | Browser Not Running | Notes | - | ------- | -------- | --------------- | ------------------- | ------------------------------------------------------- | - | Chrome | Desktop | ✅ | ❌ | | - | Firefox | Desktop | ✅ | ❌ | | - | Edge | Desktop | ✅ | ❌ | | - | Opera | Desktop | ✅ | ❌ | | - | Safari | Desktop | ✅ | ✅ | requires Safari 16.1, macOS 13 Ventura | - | Chrome | Android | ✅ | ✅ | | - | Safari | iOS | ⚠️ | ⚠️ | requires iOS 16.4, only when app is added to homescreen | - - (Browsers below 1% usage not shown, look at the Push API link for more info) + | Browser | Platform | Browser Running | Browser Not Running | Restrictions | + | ------- | -------- | --------------- | ------------------- | ------------------------------------------------------- | + | Chrome | Desktop | ✅ | ❌ | | + | Firefox | Desktop | ✅ | ❌ | | + | Edge | Desktop | ✅ | ❌ | | + | Opera | Desktop | ✅ | ❌ | | + | Safari | Desktop | ✅ | ✅ | requires Safari 16.1, macOS 13 Ventura | + | Chrome | Android | ✅ | ✅ | | + | Safari | iOS | ⚠️ | ⚠️ | requires iOS 16.4, only when app is added to homescreen | + + (Browsers below 1% usage not shown, look at the [Push API](https://caniuse.com/push-api) for more info) To learn how to send messages, check out the [publishing page](../publish.md).