Merge pull request #156 from breez/savage-notification-feedback

Improve notification docs

src/SUMMARY.md

@@ -26,22 +26,24 @@
 - [Reporting payment failures](guide/failure_report.md)
 - [Moving to production](guide/production.md)
 
+---
+
 # Notifications
 
-- [Getting Started](notifications/getting_started.md)
-- [Setup an NDS](notifications/setup_nds.md)
-- [Register a webhook](notifications/register_webhook.md)
-- [Project Integration](notifications/setup_plugin.md)
+- [Implementing mobile notifications](notifications/getting_started.md)
+- [Setting up an NDS](notifications/setup_nds.md)
+- [Registering a webhook](notifications/register_webhook.md)
+- [Integrating the plugin](notifications/setup_plugin.md)
     - [Android](notifications/android_setup.md)
-      - [Foreground Service](notifications/android_service.md)
-      - [Notification Plugin](notifications/android_plugin.md)
+      - [Setting up the Foreground Service](notifications/android_service.md)
+      - [Adding the Notification Plugin](notifications/android_plugin.md)
     - [iOS](notifications/ios_setup.md)
-      - [Notification Service Extension](notifications/ios_service.md)
-      - [Notification Plugin](notifications/ios_plugin.md)
+      - [Setting up the Notification Service Extension](notifications/ios_service.md)
+      - [Adding the Notification Plugin](notifications/ios_plugin.md)
 - [Logging](notifications/logging.md)
-- [Service Configuration](notifications/service_configuration.md)
-- [Changing Default Strings](notifications/changing_strings.md)
-- [Custom Notification Handling](notifications/custom_notifications.md)
+- [Configuring the plugin](notifications/service_configuration.md)
+- [Changing default strings](notifications/changing_strings.md)
+- [Handling custom notifications](notifications/custom_notifications.md)
 
 <!-- Hidden Links -->
 [](guide/payment_notification.md)

src/guide/payment_notification.md

@@ -1,14 +1,67 @@
-# Introduction
+# Implementing mobile notifications
 
-The Breez SDK Notification Plugin provides vendors the ability to receive events via mobile notifications even while the application is in the background or closed. This plugin processes several different notification types like receiving payments, LNURL-pay flows and swap confirmations. You can even extend the functionality to handle your own notification types within your application.
+The Breez SDK Notification Plugin provides developers a simple solution to improve the payment experience on a mobile device. No longer does the application need to be in foreground when receiving payments. When the Notification Plugin is added to process push notifications, the application can be in the background or even closed.
+
+## How it works
+
+The process involves using a Notification Delivery Service (NDS) acting as an intermediary host by the application developer. The NDS must provide a public facing webhook URL where a POST request can be sent to when a notification needs to be delivered to the application. The NDS then forwards the data sent in the webhook POST request via push notification to the application. When the application then receives the push notification, the Breez SDK Notification Plugin can be used to process the event.
 
 ![receive via notifications_2](https://github.com/breez/breez-sdk-docs/assets/31890660/75e7cac6-4480-453d-823b-f52bd6757ce9)
 
-## How it works
+## Use cases
+
+The Notification Plugin handles several use cases by default to automatically process push notifications sent via the NDS from when an SDK service calls the registered webhook. If your use case isn't covered by the Notification Plugin, you can extend the plugin to [handle custom notifications](/notifications/custom_notifications.md).
+
+#### Receiving a payment
+
+Payments are routed through an LSP to the user's node. When an LSP intercepts a payment, the LSP calls the registered webhook with the details of the payment. The Notification Plugin when receiving this notification from the NDS will connect to the Breez SDK and wait for the payment to be processed by the Breez SDK. The `payment_received` notification type has the following format:
+```json
+{
+    "template": "payment_received",
+    "data": {  
+        "payment_hash": "" // The payment hash that is in progress
+    }
+}
+```
+
+#### Confirming a swap
+
+When receiving a payment via a onchain address, the swap address needs to be monitored until the funds are confirmed onchain before the swap is executed. A chain service is used to monitor the address for confirmed funds. Once funds are confirmed, the chain service calls the registered webhook with the address. The Notification Plugin when receiving this notification from the NDS will connect to the Breez SDK and redeem the swap. The `address_txs_confirmed` notification type has the following format:
+```json
+{
+    "template": "address_txs_confirmed",
+    "data": {  
+        "address": "" // The address of the swap with confirmed funds
+    }
+}
+```
+
+#### Handling LNURL pay requests
+
+Having the ability to process push notifications when the application is in the background or closed also opens up the ability to handle payment requests from a static LNURL address. To do this the application also needs to register a webook with an [LNURL-pay service](lnurlpay.md), then when the LNURL service receives a request on the static LNURL address, it will forward it via the NDS to the application. The Notification Plugin handles the two-step flow for fulfilling these requests.
 
-This process involves using a Notification Delivery Service (NDS) acting as an intermediary host by the application developer. The NDS must provide a public facing webhook URL where a POST request can be sent to when a notification needs to be delivered to the application. The NDS then forwards the data sent in the webhook POST request via push notification to the application. When the application then receives the push notification then Breez SDK Notification Plugin can be used to process the event.
+Firstly the LNURL service receives a request for LNURL-pay information to get the min/max amount that can be received. The LNURL service calls the registered webhook and when receiving this notification, the Notification Plugin will connect to the Breez SDK and send a response back to the LNURL service based on the node info. The `lnurlpay_info` notification type has the following format:
+```json
+{
+    "template": "lnurlpay_info",
+    "data": {  
+        "callback_url": "", // The URL of the LNURL service
+        "reply_url": "" // The URL to reply to this request
+    }
+}
+```
+Secondly the LNURL service receives a request for an invoice based on the selected amount to pay. The LNURL service calls the registered webhook and when receiving this notification, the Notification Plugin will connect to the Breez SDK and call receive payment for the requested amount. The resulting invoice is then returned to the LNURL service. The `lnurlpay_invoice` notification type has the following format:
+```json
+{
+    "template": "lnurlpay_invoice",
+    "data": {  
+        "amount": 0, // The amount in millisatoshis within the min/max sendable range
+        "reply_url": "" // The URL to reply to this request
+    }
+}
+```
 
-## Next Steps
-- **[Setup an NDS](/notifications/setup_nds.md)** to receive webhook requests
-- **[Register a webhook](/notifications/register_webhook.md)** in your main application
-- **[Project integration](/notifications/setup_plugin.md)** using a notification service extension or foreground service
+## Next steps
+- **[Setting up an NDS](/notifications/setup_nds.md)** to receive webhook requests
+- **[Registering a webhook](/notifications/register_webhook.md)** in your main application
+- **[Integrating the plugin](/notifications/setup_plugin.md)** using a notification service extension or foreground service

src/notifications/android_plugin.md

@@ -1,4 +1,4 @@
-# Add the Android Notification Plugin
+# Adding the Notification Plugin
 
 Add the `breez-sdk` dependency to your application's `build.gradle` file in the `app` directory.
 

src/notifications/android_service.md

@@ -1,4 +1,4 @@
-# Android Foreground Service
+# Setting up the Foreground Service
 
 In the `AndroidManifest.xml` file of the application's `app/src/main` directory, add the user permissions necessary to handle notifications `POST_NOTIFICATIONS` as a foreground service `FOREGROUND_SERVICE`. Then to your main application add two services, one to handle messaging events and one to handle the foreground service.
 

src/notifications/android_setup.md

@@ -1,7 +1,7 @@
-# Setup the Android Notification Plugin
+# Android
 
 In order to add the Notification Plugin to your Android application, first you need to setup the Foreground Service, then add the Notification Plugin dependency and integrate it:
 
-## Next Steps
-- **[Setup the Foreground Service](android_service.md)**
-- **[Add the Notification Plugin](android_plugin.md)**
+## Next steps
+- **[Setting up the Foreground Service](android_service.md)**
+- **[Adding the Notification Plugin](android_plugin.md)**

src/notifications/changing_strings.md

@@ -1,4 +1,4 @@
-# Changing Default Strings
+# Changing default strings
 
 The Notification Plugin uses a set of identifiers and default strings to display messages when processing push notifications. These default strings can be customised by the application. For example, if you wanted to change the `lnurl_pay_metadata_plain_text`, which sets the LNURL-pay text/plain metadata.
 

src/notifications/custom_notifications.md

@@ -1,4 +1,4 @@
-# Custom Notification Handling
+# Handling custom notifications
 
 You can customise the Notification Plugin even further by handling your own notification types sent to the application via push notification. Follow the code example below for adding these to iOS and Android.
 
@@ -125,11 +125,7 @@ class CustomTask : TaskProtocol {
         self.bestAttemptContent = bestAttemptContent
         self.logger = logger
     }
-    
-    // Use the `onEvent` function to handle events from the Breez SDK 
-    // that can be used in your task
-    public func onEvent(e: BreezEvent) {}
-    
+        
     // The `start` function is called once the SDK instance is connected
     func start(breezSDK: BlockingBreezServices) throws {
         // Decode the `CustomRequest` from the payload
@@ -152,6 +148,10 @@ class CustomTask : TaskProtocol {
         }
     }
 
+    // Use the `onEvent` function to handle events from the Breez SDK 
+    // that can be used in your task
+    public func onEvent(e: BreezEvent) {}
+
     // The 'onShutdown' function can be called when the notification service extension is about to be 
     // shutdown by the OS, here you can cleanup and display the failed push notification message
     func onShutdown() {
@@ -191,10 +191,6 @@ class CustomJob(
         private const val TAG = "CustomJob"
     }
 
-    // Use the `onEvent` function to handle events from the Breez SDK 
-    // that can be used in your task
-    override fun onEvent(e: BreezEvent) {}
-
     // The `start` function is called once the SDK instance is connected
     override fun start(breezSDK: BlockingBreezServices) {
         // Remember if you are using a custom notification channel, you have to register it first
@@ -221,6 +217,14 @@ class CustomJob(
         // Tell the foreground service the job is finished
         fgService.onFinished(this)
     }
+
+    // Use the `onEvent` function to handle events from the Breez SDK 
+    // that can be used in your task
+    override fun onEvent(e: BreezEvent) {}
+
+    // The `onShutdown` function is called when the service timeout is reached
+    // and the job should cleanup before shutting down
+    override fun onShutdown() {}
 }
 ```
 

src/notifications/getting_started.md

@@ -1,20 +1,20 @@
-# Introduction
+# Implementing mobile notifications
 
-The Breez SDK Notification Plugin provides vendors the ability to receive events via mobile notifications even while the application is in the background or closed. This plugin processes several different notification types like receiving payments, LNURL-pay flows and swap confirmations. You can even extend the functionality to handle your own notification types within your application.
-
-![receive via notifications_2](https://github.com/breez/breez-sdk-docs/assets/31890660/75e7cac6-4480-453d-823b-f52bd6757ce9)
+The Breez SDK Notification Plugin provides developers a simple solution to improve the payment experience on a mobile device. No longer does the application need to be in foreground when receiving payments. When the Notification Plugin is added to process push notifications, the application can be in the background or even closed.
 
 ## How it works
 
-This process involves using a Notification Delivery Service (NDS) acting as an intermediary host by the application developer. The NDS must provide a public facing webhook URL where a POST request can be sent to when a notification needs to be delivered to the application. The NDS then forwards the data sent in the webhook POST request via push notification to the application. When the application then receives the push notification then Breez SDK Notification Plugin can be used to process the event.
+The process involves using a Notification Delivery Service (NDS) acting as an intermediary host by the application developer. The NDS must provide a public facing webhook URL where a POST request can be sent to when a notification needs to be delivered to the application. The NDS then forwards the data sent in the webhook POST request via push notification to the application. When the application then receives the push notification, the Breez SDK Notification Plugin can be used to process the event.
 
-## Handled Types
+![receive via notifications_2](https://github.com/breez/breez-sdk-docs/assets/31890660/75e7cac6-4480-453d-823b-f52bd6757ce9)
 
-The following notification types are handled by default by the Notification Plugin.
+## Use cases
 
-#### Payment Received
+The Notification Plugin handles several use cases by default to automatically process push notifications sent via the NDS from when an SDK service calls the registered webhook. If your use case isn't covered by the Notification Plugin, you can extend the plugin to [handle custom notifications](custom_notifications.md).
 
-When an LSP intercepts a payment on the way to the user's node, the LSP will call the webhook with the POST data:
+#### Receiving a payment
+
+Payments are routed through an LSP to the user's node. When an LSP intercepts a payment, the LSP calls the registered webhook with the details of the payment. The Notification Plugin when receiving this notification from the NDS will connect to the Breez SDK and wait for the payment to be processed by the Breez SDK. The `payment_received` notification type has the following format:
 ```json
 {
     "template": "payment_received",
@@ -24,9 +24,9 @@ When an LSP intercepts a payment on the way to the user's node, the LSP will cal
 }
 ```
 
-#### Swap Confirmed
+#### Confirming a swap
 
-When the chain service confirms that there are funds available at the swap address when receiving a onchain payment, the chain service will call the webhook with the POST data:
+When receiving a payment via a onchain address, the swap address needs to be monitored until the funds are confirmed onchain before the swap is executed. A chain service is used to monitor the address for confirmed funds. Once funds are confirmed, the chain service calls the registered webhook with the address. The Notification Plugin when receiving this notification from the NDS will connect to the Breez SDK and redeem the swap. The `address_txs_confirmed` notification type has the following format:
 ```json
 {
     "template": "address_txs_confirmed",
@@ -36,9 +36,11 @@ When the chain service confirms that there are funds available at the swap addre
 }
 ```
 
-#### LNURL-pay
+#### Handling LNURL pay requests
+
+Having the ability to process push notifications when the application is in the background or closed also opens up the ability to handle payment requests from a static LNURL address. To do this the application also needs to register a webook with an [LNURL-pay service](/guide/lnurlpay.md), then when the LNURL service receives a request on the static LNURL address, it will forward it via the NDS to the application. The Notification Plugin handles the two-step flow for fulfilling these requests.
 
-When an LNURL service receives a request for LNURL-pay info or an invoice, the LNURL service will first call the webhook with the POST data:
+Firstly the LNURL service receives a request for LNURL-pay information to get the min/max amount that can be received. The LNURL service calls the registered webhook and when receiving this notification, the Notification Plugin will connect to the Breez SDK and send a response back to the LNURL service based on the node info. The `lnurlpay_info` notification type has the following format:
 ```json
 {
     "template": "lnurlpay_info",
@@ -48,7 +50,7 @@ When an LNURL service receives a request for LNURL-pay info or an invoice, the L
     }
 }
 ```
-Then to get an invoice with the POST data:
+Secondly the LNURL service receives a request for an invoice based on the selected amount to pay. The LNURL service calls the registered webhook and when receiving this notification, the Notification Plugin will connect to the Breez SDK and call receive payment for the requested amount. The resulting invoice is then returned to the LNURL service. The `lnurlpay_invoice` notification type has the following format:
 ```json
 {
     "template": "lnurlpay_invoice",
@@ -59,7 +61,7 @@ Then to get an invoice with the POST data:
 }
 ```
 
-## Next Steps
-- **[Setup an NDS](setup_nds.md)** to receive webhook requests
-- **[Register a webhook](register_webhook.md)** in your main application
-- **[Project integration](setup_plugin.md)** using a notification service extension or foreground service
+## Next steps
+- **[Setting up an NDS](setup_nds.md)** to receive webhook requests
+- **[Registering a webhook](register_webhook.md)** in your main application
+- **[Integrating the plugin](setup_plugin.md)** using a notification service extension or foreground service

src/notifications/ios_plugin.md

@@ -1,4 +1,4 @@
-# Add the iOS Notification Plugin
+# Adding the Notification Plugin
 
 Add the `BreezSDK` cocoapod to your iOS Podfile, with the target `NotificationService`. You can add any other dependencies your require here also, for example `KeychainAccess` to read the saved mnemonic from the keychain.
 

src/notifications/ios_service.md

@@ -1,4 +1,5 @@
-# iOS Notfication Service Extension
+# Setting up the Notification Service Extension
+
 ## Add a Notfication Service Extension target
 
 In Xcode add a new Target to your application:

src/notifications/ios_setup.md

@@ -1,7 +1,7 @@
-# Setup the iOS Notification Plugin
+# iOS
 
 In order to add the Notification Plugin to your iOS application, first you need to setup the Notification Service Extension, then add the Notification Plugin dependency and integrate it:
 
-## Next Steps
-- **[Setup the Notification Service Extension](ios_service.md)**
-- **[Add the Notification Plugin](ios_plugin.md)**
+## Next steps
+- **[Setting up the Notification Service Extension](ios_service.md)**
+- **[Adding the Notification Plugin](ios_plugin.md)**

src/notifications/register_webhook.md

@@ -1,6 +1,6 @@
-# Register a webhook
+# Registering a webhook
 
-Once your vendor [NDS is set up](setup_nds.md) and can accept POST requests from the SDK services, you can within your mail application register the webhook URL with the Breez SDK by calling the register webhook API as follows:
+Once your [NDS is set up](setup_nds.md) and can accept POST requests from the SDK services, you can within your mail application register the webhook URL with the Breez SDK by calling the register webhook API as follows:
 
 <custom-tabs category="lang">
 <div slot="title">Rust</div>

src/notifications/service_configuration.md

@@ -1,4 +1,4 @@
-# Service Configuration
+# Configuring the plugin
 
 You can override the default Notification Plugin config to set values used to process certain notification events. For example, the `channelFeeLimitMsat` value can be set to limit the maximum fee paid in the case where a channel will be opened during receiving a payment with LNURL-pay.