mirror of
https://github.com/binwiederhier/ntfy.git
synced 2024-12-27 02:42:10 +03:00
Improve web push docs
This commit is contained in:
nimbleghost
parent
a9fef387fa
commit
f94bb1aa30
@ -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
|
||||
|
||||
@ -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),
|
||||
|
||||
@ -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)
|
||||
|
||||
<div id="pwa-screenshots" class="screenshots">
|
||||
<a href="../../static/img/pwa.png"><img src="../../static/img/pwa.png"/></a>
|
||||
|
||||
@ -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).
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user