From be4c80e2015ae3f22d9c84a7f1389346004261d4 Mon Sep 17 00:00:00 2001
From: nimbleghost <132819643+nimbleghost@users.noreply.github.com>
Date: Sat, 24 Jun 2023 20:35:38 +0200
Subject: [PATCH] Improve web push docs

---
 .../{desktop.md => installed-web-app.md}      | 20 ++++++++++++++++---
 docs/subscribe/web.md                         |  9 +++++++--
 2 files changed, 24 insertions(+), 5 deletions(-)
 rename docs/subscribe/{desktop.md => installed-web-app.md} (52%)

diff --git a/docs/subscribe/desktop.md b/docs/subscribe/installed-web-app.md
similarity index 52%
rename from docs/subscribe/desktop.md
rename to docs/subscribe/installed-web-app.md
index 8d97571c..d7c54241 100644
--- a/docs/subscribe/desktop.md
+++ b/docs/subscribe/installed-web-app.md
@@ -1,10 +1,24 @@
 # 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) (PWA)
-and thus can be installed on both desktop and mobile devices. 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.
+and thus can be installed on both desktop and mobile devices.
+
+This gives it its own launcher (e.g. shortcut on Windows, app on macOS, launcher shortcut on Linux, home screen icon on iOS, and
+launcher icon on Android), a standalone window, push notifications, and an app badge with the unread notification count.
 
 To install and register the web app in your operating system, click the "install app" icon in your browser (usually next to the
-address bar). To receive background notifications, **either the browser or the installed web app must be open**.
+address bar). On iOS Safari, tap on the Share menu > "Add to Home Screen".
+
+## Background Notifications
+
+Background notifications via web push are enabled by default and cannot be turned off when the app is installed, as notifications would
+not be delivered reliably otherwise. You can mute topics you don't want to receive notifications for.
+
+On desktop, you generally need either your browser or the web app open to receive notifications, though the ntfy tab doesn't need to be
+open. On mobile, you don't need to have the web app open to receive notifications. Look at the [web docs](./web.md#background-notifications)
+for a detailed breakdown.
+
+## Compatibility
 
 <!-- TODO: (Q4 2023) Safari 17 / macOS 14 Sonoma supports installable PWAs too -->
 
diff --git a/docs/subscribe/web.md b/docs/subscribe/web.md
index 1508e99f..0faa8cb4 100644
--- a/docs/subscribe/web.md
+++ b/docs/subscribe/web.md
@@ -23,10 +23,15 @@ If topic reservations are enabled, you can claim ownership over topics and defin
     <a href="../../static/img/web-reserve-topic-dialog.png"><img src="../../static/img/web-reserve-topic-dialog.png"/></a>
 </div>
 
-## Background notifications
+## Background Notifications
+
 While subscribing, you have the option to enable background notifications on supported browsers (see "Settings" tab).
 
-**If background notifications are off (default):** This requires an active ntfy tab to be open to receive notifications. 
+Note: If you add the web app to your homescreen (as a progressive web app, more info in the [installed web app](./installed-web-app.md)
+docs), you cannot turn these off, as notifications would not be delivered reliably otherwise. You can mute topics you don't want to receive
+notifications for.
+
+**If background notifications are off:** 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.