Add iOS Live Activities documentation

docs/notifications/basic.md

@@ -619,66 +619,11 @@ automation:
 
 ### Live Updates
 
-On Android 16.0+ you can create "Live updates" notifications. These notifications are pinned to the top of the notification shade and appear on the lockscreen and always-on display. They will also display as a chip in the status bar with an optional short text. This might vary by manufacturer.
+On Android 16+, `live_update: true` displays a persistent notification pinned to the top of the notification shade, the Lock Screen, and the always-on display, with a status bar chip.
 
-For the notification to display as a "Live updates" notification, `title` must be provided.
+The same field also starts a **Live Activity** <span class="beta">BETA</span> on iOS 17.2+ — a single automation targets both platforms.
 
-- `live_update` - set to `true` to display as a "Live updates" notification
-- `critical_text` - set an optional short text to display in the status bar chip
-  - `live_update` must be set to `true` as well
-  - If there is not enough space in the status bar to show the text, only the icon will be displayed
-  - If the `chronometer` parameter is used it will replace the `critical_text` value
-
-:::note
-On Samsung devices you may have to enable "Live notifications for all apps" in developer options to make notifications show a chip in the status bar.
-:::
-
-#### Basic configuration
-
-```yaml
-automation:
-  - alias: Notify a live update
-    trigger:
-      ...
-    action:
-      - action: notify.mobile_app_<your_device_id_here>
-        data:
-          title: "Live update"
-          message: "This will show on the always-on display"
-          data:
-            live_update: true
-            critical_text: "42%"
-```
-
-These screenshots show how the notifications will display in the statusbar (with or without critical text)
-![Status bar chip](/assets/android/live_updates_without_critical_text.png)
-![Status bar chip when using critical text](/assets/android/live_updates_with_critical_text.png)
-
-#### Configuration combined with progress, chronometer, tag and icon
-
-```yaml
-automation:
-  - alias: Notify a live update
-    trigger:
-      ...
-    action:
-      - action: notify.mobile_app_<your_device_id_here>
-        data:
-          title: Example notification showing progress
-          message: Current progress is 42%
-          data:
-            live_update: true
-            chronometer: true
-            when: 315
-            when_relative: true
-            progress: 42
-            progress_max: 100
-            tag: live_progress_notification
-            notification_icon: mdi:progress-helper
-```
-
-This screenshot shows how the above configuration will appear on the always-on display
-![Example notification showing progress and the chronometer on always-on display](/assets/android/live_updates_always_on_display.png)
+See [Live Activities and Live Updates](live-activities.md) for the full payload reference, examples, and platform-specific behavior.
 
 ### Alert Once
 
@@ -735,6 +680,12 @@ By default Home Assistant notifications do not show up in the Android Auto inter
 
 ## iOS/macOS Specific
 
+### Live Activities
+
+On iOS 17.2+, `live_update: true` starts a **Live Activity** on the Lock Screen and Dynamic Island — the same field Android uses for [Live Updates](#live-updates), so a single automation targets both platforms.
+
+See [Live Activities and Live Updates](live-activities.md) for the full payload reference, examples, and platform-specific behavior.
+
 ### Sounds
 By default the default notification sound (Tri-tone on iOS) will be played upon receiving a notification. See the [Sounds documentation](sounds.md) for details of the available sounds and how to add custom sounds. The default notification sounds (Tri-tone) can be disabled by setting `sound` to `none` in the data payload:
 

docs/notifications/commands.md

@@ -11,7 +11,7 @@ The Companion apps offer a lot of different notification options. In place of po
 | ------- | ----------- |
 | `request_location_update` | Request a location update from the device, [see below](#request-location-updates) for implications about this command. |
 | `clear_badge` | Silently removes the badge from the App icon without displaying a notification. |
-| `clear_notification` | Removes a notification, [more details](basic.md#clearing). |
+| `clear_notification` | Removes a notification or a live activity, [more details](basic.md#clearing). |
 | `update_complications` | Updates the complications on a paired Apple Watch. [More details](/apple-watch/complications.md). |
 | `update_widgets`* | Updates 'Gauge' and 'Details' widgets introduced on App v2024.7 (iOS will decide if the update is allowed or not, so don't worry if it doesn't work all the time). |
 

docs/notifications/live-activities.md

@@ -0,0 +1,191 @@
+---
+title: "Live Activities and Live Updates"
+id: "live-activities"
+---
+
+**Live Activities** (iOS) and **Live Updates** (Android) keep real-time Home Assistant state visible on the Lock Screen, Dynamic Island, status bar, and always-on display — without the user needing to unlock their device.
+
+:::info Requirements
+- ![iOS](/assets/iOS.svg) **iOS:** iOS 17.2 or later on iPhone and iPad. Not available on macOS.
+- ![Android](/assets/android.svg) **Android:** Android 16 or later. Status bar chip appearance may vary by manufacturer.
+:::
+
+![Washing Machine, EV Charging, Now Playing, and Package Delivery Live Activities on the iOS Lock Screen](/assets/ios/live-activity-lockscreen-cards.png)
+
+---
+
+## Starting
+
+Add `live_update: true` and a `tag` to any notification payload. The companion app intercepts the push and displays a Live Activity (iOS) or Live Update (Android) instead of a standard notification banner.
+
+```yaml
+automation:
+  - alias: "Washing machine started"
+    trigger:
+      ...
+    action:
+      - action: notify.mobile_app_<your_device_id_here>
+        data:
+          title: "Washing Machine"
+          message: "Rinsing · 1 of 2"
+          data:
+            tag: washer_cycle
+            live_update: true
+            progress: 900
+            progress_max: 3600
+            chronometer: true
+            when: 2700
+            when_relative: true
+            notification_icon: mdi:washing-machine
+            notification_icon_color: "#2196F3"
+```
+
+The `tag` uniquely identifies the activity. Subsequent pushes with the same `tag` update the existing activity in-place rather than creating a new one.
+
+![iOS](/assets/iOS.svg) The activity appears on the Lock Screen and Dynamic Island.
+
+![Android](/assets/android.svg) The notification is pinned to the top of the notification shade, the Lock Screen, and the always-on display. It also shows as a chip in the status bar. `title` must be provided.
+
+![Android Live Update showing "Washing Machine / Rinsing · 1 of 2" on the Lock Screen](/assets/android/live_updates_washing_lockscreen.png)
+
+:::note Samsung devices
+On Samsung, you may need to enable **Live notifications for all apps** in developer options for the status bar chip to appear.
+:::
+
+---
+
+## Updating
+
+Send the same payload again with the same `tag`. The display updates silently — no banner, no sound.
+
+```yaml
+action:
+  - action: notify.mobile_app_<your_device_id_here>
+    data:
+      title: "Washing Machine"
+      message: "Cycle complete"
+      data:
+        tag: washer_cycle
+        live_update: true
+        progress: 3600
+        progress_max: 3600
+        notification_icon: mdi:washing-machine
+        notification_icon_color: "#4CAF50"
+```
+
+![Washing Machine Live Activity showing "Cycle complete" with a full green progress bar](/assets/ios/live-activity-complete-solo.png)
+
+![Android Live Update showing "Washing Machine / Cycle complete" on the Lock Screen](/assets/android/live_updates_complete_lockscreen.png)
+
+---
+
+## Ending
+
+Send `clear_notification` with the same `tag` to end the Live Activity / Live Update and dismiss any delivered notification with that identifier — on both iOS and Android.
+
+```yaml
+action:
+  - action: notify.mobile_app_<your_device_id_here>
+    data:
+      message: "clear_notification"
+      data:
+        tag: washer_cycle
+```
+
+---
+
+## Payload fields
+
+`title` and `message` are standard notification fields set at the top level (`data.title`, `data.message`). All other Live Activity / Live Update fields go inside the nested `data:` block (`data.data`).
+
+| Field | Platform | Type | Description |
+|---|---|---|---|
+| `tag` | Both | string | **Required.** Unique identifier for the activity. Alphanumeric, hyphens, and underscores only; max 64 characters. |
+| `live_update` | Both | boolean | Set to `true` to start or update a Live Activity / Live Update. |
+| `title` | Both | string | Top-level field (`data.title`). Static header text; set at creation, cannot be changed by updates. |
+| `message` | Both | string | Top-level field (`data.message`). Main body text shown in the notification and on the Lock Screen / always-on display. |
+| `critical_text` | Both | string | Short supplementary text. ![Android](/assets/android.svg) Shown in the status bar chip (replaced by `chronometer` if set). |
+| `progress` | Both | integer | Current progress value (such as seconds elapsed). |
+| `progress_max` | Both | integer | Maximum progress value. Shows a progress bar when both `progress` and `progress_max` are set. |
+| `chronometer` | Both | boolean | Show a live countdown or count-up timer. Requires `when`. ![Android](/assets/android.svg) Replaces `critical_text` in the status bar chip. |
+| `when` | Both | number | Timer reference point. Unix timestamp (absolute) or seconds (relative when `when_relative: true`). |
+| `when_relative` | Both | boolean | If `true`, treat `when` as seconds from now rather than a Unix timestamp. |
+| `notification_icon` | Both | string | [Material Design Icon](https://pictogrammers.com/library/mdi/) slug, such as `mdi:washing-machine`. |
+| `notification_icon_color` | ![iOS](/assets/iOS.svg) | string | Hex color for the icon, such as `#2196F3`. |
+| `alert_once` | ![Android](/assets/android.svg) | boolean | If `true`, the notification only alerts (sound/vibration) once. |
+| `sticky` | ![Android](/assets/android.svg) | boolean | If `true`, the notification is not dismissed when the user taps it. |
+
+---
+
+## Example scenarios
+
+### Plain notification with a message
+
+```yaml
+data:
+  title: "Home Assistant"
+  message: "Everything looks good at home."
+  data:
+    tag: status-update
+    live_update: true
+```
+
+![Plain "Home Assistant / Everything looks good at home." Live Activity banner on the iOS Lock Screen](/assets/ios/live-activity-plain-crop.png)
+
+### Security alert with icon and color
+
+```yaml
+data:
+  title: "Security Alert"
+  message: "Person detected · Camera 1"
+  data:
+    tag: security-alert
+    live_update: true
+    notification_icon: mdi:motion-sensor
+    notification_icon_color: "#F44336"
+```
+
+![Security Alert Live Activity card with a red motion sensor icon](/assets/ios/live-activity-security-solo.png)
+
+![Android Live Update showing "Security Alert / Person detected · Camera 1" on the Lock Screen](/assets/android/live_updates_security_lockscreen.png)
+
+### Multiple concurrent activities
+
+![iOS](/assets/iOS.svg) Multiple Live Activities stack on the Lock Screen under the app group header.
+
+![Four Live Activities grouped on the iOS Lock Screen: Home Assistant, Script Running, Security Alarm, All Fields](/assets/ios/live-activity-multi-crop.png)
+
+![Android](/assets/android.svg) On Android, multiple Live Updates appear as separate pinned notifications in the notification shade.
+
+![Android notification shade showing multiple Live Updates including Washing Machine and Home Assistant](/assets/android/live_updates_notification_shade.png)
+
+---
+
+## Platform-specific behavior
+
+### iOS
+
+**Dynamic Island:** On iPhone 14 Pro/Pro Max and all iPhone 15 and later models, the Live Activity also appears as a compact island pill at the top of the screen. On older iPhones without a Dynamic Island (notch or Home button), and on iPad, the activity appears on the Lock Screen only.
+
+**Settings:** Go to **Settings → Live Activities** in the companion app to see whether Live Activities are enabled and to view or end any currently active activities.
+
+:::note iOS limitations
+- **Rate limiting:** Apple throttles Live Activity updates to approximately 15 seconds between rendered updates. Structure automations to fire on state-change events rather than polling timers.
+- **Expiry:** Activities expire after [up to 8 hours](https://developer.apple.com/documentation/activitykit/displaying-live-data-with-live-activities#Understand-constraints) (Apple system limit). If the app is force-quit and relaunched, it automatically reattaches to any Live Activities iOS kept alive.
+- **Privacy:** The first time a Live Activity is started, the companion app displays a one-time disclosure noting that Lock Screen content is visible without unlocking the device.
+:::
+
+### Android
+
+**Always-on display:** The Live Update appears pinned at the top of the notification shade, on the Lock Screen, and on the always-on display.
+
+**Status bar chip:** The notification shows as a chip in the status bar. Use `critical_text` to display a short label in the chip. If `chronometer: true` is set, the timer replaces `critical_text` in the chip. If there is not enough space in the status bar, only the icon is shown.
+
+:::note Samsung devices
+On Samsung, you may need to enable **Live notifications for all apps** in developer options for the status bar chip to appear.
+:::
+
+![Status bar chip without critical text](/assets/android/live_updates_without_critical_text.png)
+![Status bar chip with critical text](/assets/android/live_updates_with_critical_text.png)
+
+![Always-on display showing progress and chronometer](/assets/android/live_updates_always_on_display.png)

sidebars.js

@@ -32,6 +32,7 @@ module.exports = {
       'notifications/notification-details',
       'notifications/notification-cleared',
       'notifications/notification-commands',
+      'notifications/live-activities',
       'notifications/notification-sounds',
       'notifications/notification-local',
       'notifications/notification-received',