parra/ntfy
parra/ntfy
1
0
Fork 0
mirror of https://github.com/binwiederhier/ntfy.git synced 2024-12-22 17:52:30 +01:00
Code Releases Activity

Improve web push docs

Browse source
This commit is contained in:
nimbleghost 2023-05-29 22:09:40 +02:00
parent a9fef387fa
commit f94bb1aa30
4 changed files with 84 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
README.md
View file

@ -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

49
docs/config.md
View file

@ -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),

16
docs/subscribe/desktop.md
View file

@ -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>

42
docs/subscribe/web.md
View file

@ -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).