From 12b83828bdd4ba92bf70f3e0831e0fae644eb148 Mon Sep 17 00:00:00 2001 From: Philipp Heckel Date: Sat, 28 May 2022 20:20:46 -0400 Subject: [PATCH] Docs --- cmd/serve.go | 2 ++ docs/config.md | 29 +++++++++++++++++++++++++++++ docs/releases.md | 3 ++- docs/subscribe/phone.md | 12 ++++++++++++ 4 files changed, 45 insertions(+), 1 deletion(-) diff --git a/cmd/serve.go b/cmd/serve.go index 52008c2e..630889d0 100644 --- a/cmd/serve.go +++ b/cmd/serve.go @@ -151,6 +151,8 @@ func execServe(c *cli.Context) error { return errors.New("if set, web-root must be 'home' or 'app'") } else if upstreamBaseURL != "" && !strings.HasPrefix(upstreamBaseURL, "http://") && !strings.HasPrefix(upstreamBaseURL, "https://") { return errors.New("if set, upstream-base-url must start with http:// or https://") + } else if upstreamBaseURL != "" && baseURL == "" { + return errors.New("if upstream-base-url is set, base-url must also be set") } webRootIsApp := webRoot == "app" diff --git a/docs/config.md b/docs/config.md index c767a5f2..44afb536 100644 --- a/docs/config.md +++ b/docs/config.md @@ -618,6 +618,35 @@ Example: firebase-key-file: "/etc/ntfy/ntfy-sh-firebase-adminsdk-ahnce-9f4d6f14b5.json" ``` +## iOS instant notifications +Unlike Android, iOS heavily restricts background processing, which sadly makes it impossible to implement instant +push notifications without a central server. + +To still support instant notifications on iOS through your self-hosted ntfy server, you have to forward so called `poll_request` +messages to the main ntfy.sh server (or any upstream server that's APNS/Firebase connected, if you build your own iOS app), +which will then forward it to Firebase/APNS. + +To configure it, simply set `upstream-base-url` like so: + +``` yaml +upstream-base-url: "https://ntfy.sh" +``` + +If set, all incoming messages will publish a poll request to the configured upstream server, containing +the message ID of the original message, instructing the iOS app to poll this server for the actual message contents. + +If `upstream-base-url` is not set, notifications will still eventually get to your device, but delivery can take hours, +depending on the state of th phone. If you are using your phone, it shouldn't take more than 20-30 minutes though. + +In case you're curious, here's an example of the entire flow: + +- In the iOS app, you subscribe to `https://ntfy.example.com/mytopic` +- The app subscribes to the Firebase topic `6de73be8dfb7d69e...` (the SHA256 of the topic URL) +- When you publish a message to `https://ntfy.example.com/mytopic`, your ntfy server will publish a + poll request to `https://ntfy.sh/6de73be8dfb7d69e...` (passing the message ID in the `X-Poll-ID` header) +- The ntfy.sh server publishes the message to Firebase, which forwards it to APNS, which forwards it to your iOS device +- Your iOS device receives the poll request, and fetches the actual message from your server, and then displays it + ## Rate limiting !!! info Be aware that if you are running ntfy behind a proxy, you must set the `behind-proxy` flag. diff --git a/docs/releases.md b/docs/releases.md index 479e7c50..67278ad1 100644 --- a/docs/releases.md +++ b/docs/releases.md @@ -26,7 +26,8 @@ and the [ntfy Android app](https://github.com/binwiederhier/ntfy-android/release **Features:** * Regularly send Firebase keepalive messages to ~poll topic to support self-hosted servers (no ticket) -* Add subscribe filter to query exact messages by ID (no ticket) +* Add subscribe filter to query exact messages by ID (no ticket) +* Support for `poll_request` messages to support [iOS push notifications](https://ntfy.sh/docs/config/#ios-instant-notifications) for self-hosted servers (no ticket) **Bugs:** diff --git a/docs/subscribe/phone.md b/docs/subscribe/phone.md index 6d0ee68e..7707afa2 100644 --- a/docs/subscribe/phone.md +++ b/docs/subscribe/phone.md @@ -33,6 +33,8 @@ If those screenshots are still not enough, here's a video: ## Message priority +_Supported on:_ :material-android: :material-apple: + When you [publish messages](../publish.md#message-priority) to a topic, you can **define a priority**. This priority defines how urgently Android will notify you about the notification, and whether they make a sound and/or vibrate. @@ -61,6 +63,8 @@ setting, and other settings such as popover or notification dot: ## Instant delivery +_Supported on:_ :material-android: + Instant delivery allows you to receive messages on your phone instantly, **even when your phone is in doze mode**, i.e. when the screen turns off, and you leave it on the desk for a while. This is achieved with a foreground service, which you'll see as a permanent notification that looks like this: @@ -91,6 +95,8 @@ The ntfy Android app uses Firebase only for the main host `ntfy.sh`, and only in It won't use Firebase for any self-hosted servers, and not at all in the the F-Droid flavor. ## Share to topic +_Supported on:_ :material-android: + You can share files to a topic using Android's "Share" feature. This works in almost any app that supports sharing files or text, and it's useful for sending yourself links, files or other things. The feature remembers a few of the last topics you shared content to and lists them at the bottom. @@ -103,6 +109,8 @@ The feature is pretty self-explanatory, and one picture says more than a thousan ## ntfy:// links +_Supported on:_ :material-android: + The ntfy Android app supports deep linking directly to topics. This is useful when integrating with [automation apps](#automation-apps) such as [MacroDroid](https://play.google.com/store/apps/details?id=com.arlosoft.macrodroid) or [Tasker](https://play.google.com/store/apps/details?id=net.dinglisch.android.taskerm), or to simply directly link to a topic from a mobile website. @@ -121,6 +129,8 @@ or to simply directly link to a topic from a mobile website. ## Integrations ### UnifiedPush +_Supported on:_ :material-android: + [UnifiedPush](https://unifiedpush.org) is a standard for receiving push notifications without using the Google-owned [Firebase Cloud Messaging (FCM)](https://firebase.google.com/docs/cloud-messaging) service. It puts push notifications in the control of the user. ntfy can act as a **UnifiedPush distributor**, forwarding messages to apps that support it. @@ -136,6 +146,8 @@ to handle messages. Here's an example with [FluffyChat](https://fluffychat.im/): ### Automation apps +_Supported on:_ :material-android: + The ntfy Android app integrates nicely with automation apps such as [MacroDroid](https://play.google.com/store/apps/details?id=com.arlosoft.macrodroid) or [Tasker](https://play.google.com/store/apps/details?id=net.dinglisch.android.taskerm). Using Android intents, you can **react to incoming messages**, as well as **send messages**.