From 795d88807f07f2d7f7b7010472f16ba2ec9405ec Mon Sep 17 00:00:00 2001
From: Mark Kraemer <mark.kraemer@rolemodelsoftware.com>
Date: Sat, 17 Feb 2024 09:56:43 -0500
Subject: [PATCH] Update the iOS documentation on how to manage the badge
 (#409)

* Update the iOS documentation on how to manage the badge

* Update docs/delivery_methods/ios.md

* Simplify example

---------

Co-authored-by: Chris Oliver <excid3@gmail.com>
---
 docs/delivery_methods/ios.md | 45 ++++++++++++++++++++++++++++++++++--
 1 file changed, 43 insertions(+), 2 deletions(-)

diff --git a/docs/delivery_methods/ios.md b/docs/delivery_methods/ios.md
index 9c25d5f..182de38 100644
--- a/docs/delivery_methods/ios.md
+++ b/docs/delivery_methods/ios.md
@@ -19,7 +19,7 @@ https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_
 ## Usage
 
 ```ruby
-class CommentNotification
+class CommentNotifier < ApplicationNotifier
   deliver_by :ios do |config|
     config.device_tokens = -> { recipient.notification_tokens.where(platform: :iOS).pluck(:token) }
     config.format = ->(apn) {
@@ -83,13 +83,54 @@ end
 Apple Push Notifications may fail delivery if the user has removed the app from their device. Noticed allows you
 
 ```ruby
-class CommentNotification
+class CommentNotifier < ApplicationNotifier
   deliver_by :ios do |config|
     config.invalid_token = ->(token) { NotificationToken.where(token: token).destroy_all }
   end
 end
 ```
 
+## Updating the iOS app badge
+
+If you're managing the iOS app badge, you can pass it along in the format
+
+```ruby
+class CommentNotifier < ApplicationNotifier
+  deliver_by :ios do |config|
+    config.format = ->(apn) {
+      apn.alert = "Hello world"
+      apn.custom_payload = {url: root_url(host: "example.org")}
+      apn.badge = recipient.notifications.unread.count
+    }
+  end
+end
+```
+
+Another common action is to update the badge after a user reads a notification. 
+
+This is a great use of the Noticed::Ephemeral class. Since it's all in-memory, it will perform the job and not touch the database.
+
+```ruby
+class NativeBadgeNotifier < Noticed::Ephemeral
+  deliver_by :ios do |config|
+    config.format = ->(apn) {
+      # Setting the alert text to nil will deliver the notification in
+      # the background. This is used to update the app badge on the iOS home screen
+      apn.alert = nil
+      apn.custom_payload = {}
+      apn.badge = recipient.notifications.unread.count
+    }
+  end
+end
+```
+
+Then you can simply deliver this notifier to update the badge when you mark the notification as read
+
+```ruby
+notification.mark_as_read!
+NativeBadgeNotifier.with(record: notification).deliver(notification.recipient)
+```
+
 ## Delivering to Sandboxes and real devices
 
 If you wish to send notifications to both sandboxed and real devices from the same application, you can configure two iOS delivery methods