Add iOS Live Activities documentation#1303
Conversation
New page covering Live Activities (iOS 16.2+): payload fields, start/ update/end lifecycle, dismissal policy options, cross-platform YAML patterns with Android Live Updates, iPad limitations, iOS 18 rate limiting, privacy disclosure, and annotated screenshots from all major scenarios. - docs/notifications/live-activities.md — new page - docs/notifications/commands.md — adds end_live_activity to iOS command table; notes clear_notification also ends Live Activities - docs/notifications/basic.md — adds Live Activities subsection under iOS/macOS Specific (with sample automation); adds cross-platform tip callout and combined YAML example in Android Live Updates section - sidebars.js — registers live-activities under Notifications - static/assets/ios/ — 12 screenshots cropped from simulator video Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
Open to discussing the main "Live Activities" page and perhaps combining with Android and maybe using "Live Widgets" instead or something? Then referencing android like I did in the iOS section for more details in the "Live Activities page" |
Replace live_activity: true with live_update: true throughout. Both iOS and Android now use the same field — a single YAML automation targets both platforms with no platform-specific keys required. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
Can we combine the docs between iOS and Android? Since it uses the same tags but ignores the one that is not needed on each platform, can we make 1 doc with information boxes when needed to differentiate between platforms? @TimoPtr can help you if you need an android reviewer as well |
There was a problem hiding this comment.
Pull request overview
Adds end-user documentation for iOS Live Activities in the Home Assistant companion app docs, and wires the new page into the Notifications section navigation.
Changes:
- Adds a new Live Activities documentation page with lifecycle (start/update/end) examples and payload field reference.
- Updates notification command docs to include
end_live_activityand clarifiesclear_notification+tagbehavior. - Updates the main notifications basics doc to explain that
live_update: truetargets both Android Live Updates and iOS Live Activities, and registers the new page insidebars.js.
Reviewed changes
Copilot reviewed 4 out of 22 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
docs/notifications/live-activities.md |
New Live Activities doc page with examples, payload fields, and limitations. |
docs/notifications/commands.md |
Adds end_live_activity and clarifies clear_notification behavior with tag. |
docs/notifications/basic.md |
Cross-platform note tying live_update: true to iOS Live Activities + adds an iOS subsection. |
sidebars.js |
Adds Live Activities page to the Notifications sidebar. |
static/assets/ios/live-activity-security-solo.png |
Adds a new screenshot asset referenced by the Live Activities page. |
|
Converting to draft until the above is done |
…stamp placeholder - commands.md: fix end_live_activity requirement from iOS 16.2+ to 17.2+ - live-activities.md: clarify that title/message are top-level data fields while Live Activity options go in the nested data.data block - live-activities.md: replace hard-coded Unix timestamp in dismissal_policy example with a placeholder so the snippet stays evergreen Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
… page Both iOS and Android use live_update: true — merge the iOS live-activities.md and Android Live Updates section (basic.md) into one unified reference page. - live-activities.md: rewritten to cover both platforms with platform badges, a shared payload fields table with per-field platform indicators, and platform-specific behavior sections (iOS Dynamic Island/rate limits/privacy, Android status bar chip/Samsung note/always-on display) - basic.md: collapse the verbose Android Live Updates section and iOS Live Activities section into short summaries linking to the combined page Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
Okay, I combined the more detailed information between Android's Live Updates and iOS's Live Activities into one page that dives into the specifics. Whereas the introduction page for notification has links that points people to that combined page. Let me know if I should update anything beyond that. Or whomever usually looks through the documentation to give it a once over. |
|
Drafting just so we dont merge it by mistake before the other PRs |
|
|
||
| ### Option 2 — `end_live_activity` command  | ||
|
|
||
| Use this when you want to end the Live Activity without affecting other notifications. Requires iOS 17.2+. |
There was a problem hiding this comment.
| Use this when you want to end the Live Activity without affecting other notifications. Requires iOS 17.2+. | |
| Use this when you want to end the Live Activity without affecting other notifications using this specific tag. Requires iOS 17.2+. |
Do we really need that? It seems adding one more option that might be easy to bypass by using another tag.
There was a problem hiding this comment.
I agree with @TimoPtr. Can you please provide a real use case where you can't use the above command and need this one.
I don't see dismissal_policy as reason as you can wait in the automation and send the clear notification later.
There was a problem hiding this comment.
I am not familiar with how often people actually use this. It was more so included because we have the option.
From what I understand, the user could theoretically specify a longer timeout than the OS default of 4 hours. So if they wanted the live activity to complete but hang out more like 6 - 8 hours they could possibly do so with this.
Other than that, you could dismiss the live activity without clearing away other notifications that have the same tag without effecting them.
I'm fine with removing if you guys deem it unnecessary documentation fatigue and unnecessary code add
There was a problem hiding this comment.
@bgoncal what do you think? I would not encourage using the TAG for another notification personally.
There was a problem hiding this comment.
Let's not over complicate, the tag should be considered the ID in this case and be used for a single live activity or a single ordinary push notification.
The 'clear' command should end the activity/notification and dismiss it.
There was a problem hiding this comment.
Restructured the ending section — clear_notification is now the primary approach, with end_live_activity only appearing under a "Dismissal policy" subsection for when you need lock screen control after ending. Lemme know how the new commit seems now once I push rwarner@a432ae7
There was a problem hiding this comment.
Maybe I missed something or did the discussion here understand it differently.
But I understood that we are going to remove end_live_activity completely as clear_notification can be used. In my opinion is confuses user more if we provide two commands to remove it.
Also Bruno commented above:
The 'clear' command should end the activity/notification and dismiss it.
So my consensus is that we remove end_live_activity but the PR is documenting it.
As written above we should start simple, we can always at it later if users really want to have it. We can't easily remove something, therefore I would remove it and see in the future if users really are needing it. Especially as we don't have a strong use case currently
|
We have to consider here that although both platform's features have "Live" in their name and they have some overlap, they are not entirely the same. This shouldn't be an issue on the Introduction page but on the new page users might get the idea that these features are limited to Android 16+ when most of it is available on all versions. Perhaps we could rename the new page to something neutral like "Progress notifications". The Android 16+ requirement could then be limited to just the first paragraph (and the I'm also working on a PR for customization of the progress bar, if this is also added to the iOS notifications the documentation could be shared on the new page. |
- basic.md: add BETA badge to iOS Live Activity mention - commands.md: add iOS badge to end_live_activity row - live-activities.md: remove platform icons from page header (both platforms) - live-activities.md: update default dismissal policy with exact Apple doc value (4 hours) - live-activities.md: convert iPad limitation to :::warning admonition - live-activities.md: group rate limiting, expiry, privacy into :::note with Apple doc links for 8-hour and 4-hour limits Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Correct, perhaps we need to define a couple additional YAMLs marked as From searching, it seems like the following is the situation:
I'm open to tweaking things, I had tried to open the conversation when I first posted it since it seems we want to use the same PR Updates
Replied to all comments that need feedback |
## Summary > For architecture decisions, data model details, iOS version strategy, push token flow, and rate limiting — see [technical-brief.pdf](https://github.com/user-attachments/files/26280274/technical-brief.pdf) Adds iOS Live Activities support, letting Home Assistant automations push real-time state to the Lock Screen — washing machine countdowns, EV charging progress, delivery tracking, alarm states, or anything time-sensitive that benefits from glanceable visibility without unlocking the phone. When an automation sends a notification with `live_update: true` in the data payload, the companion app starts a Live Activity instead of (or in addition to) a standard notification banner. Subsequent pushes with the same `tag` update it in-place silently. `clear_notification` + `tag` ends it. Field names (`tag`, `title`, `message`, `progress`, `progress_max`, `chronometer`, `when`, `when_relative`, `notification_icon`, `notification_icon_color`) are intentionally shared with Android's Live Notifications API. Both platforms use the same `live_update: true` trigger — a single YAML block targets iOS 17.2+ and Android 16+ with no platform-specific keys. ```yaml data: title: "Washing Machine" message: "Cycle in progress" data: tag: washer_cycle live_update: true # Android 16+ and iOS 17.2+ progress: 2700 progress_max: 3600 chronometer: true when: 2700 when_relative: true notification_icon: mdi:washing-machine notification_icon_color: "#2196F3" ``` **New files:** - `Sources/Shared/LiveActivity/HALiveActivityAttributes.swift` — the `ActivityAttributes` type. Field names match the Android payload spec. **Struct name and `CodingKeys` are wire-format frozen** — APNs push-to-start payloads reference the Swift type name directly. - `Sources/Shared/LiveActivity/LiveActivityRegistry.swift` — Swift `actor` managing `Activity<HALiveActivityAttributes>` lifecycle. Uses a reservation pattern to prevent duplicate activities when two pushes with the same `tag` arrive simultaneously. - `Sources/Shared/Notifications/NotificationCommands/HandlerLiveActivity.swift` — start/update and end `NotificationCommandHandler` implementations, guarded against the `PushProvider` extension process where ActivityKit is unavailable. - `Sources/Extensions/Widgets/LiveActivity/` — `ActivityConfiguration` wrapper, Lock Screen / StandBy view, and compact / minimal / expanded Dynamic Island views. - `Sources/App/Settings/LiveActivity/LiveActivitySettingsView.swift` — activity status, active list, privacy disclosure, and 11 debug scenarios for pre-server-side testing. **Modified files:** - `Widgets.swift` — registers `HALiveActivityConfiguration` in all three `WidgetBundle` variants behind `#available(iOSApplicationExtension 17.2, *)` - `NotificationsCommandManager.swift` — registers new handlers; `HandlerClearNotification` now also ends a matching Live Activity when `tag` is present - `HAAPI.swift` — adds `supports_live_activities`, `supports_live_activities_frequent_updates`, `live_activity_push_to_start_token`, `live_activity_push_to_start_apns_environment` to registration payload under a single `#available(iOS 17.2, *)` check - `AppDelegate.swift` — reattaches surviving activities at launch and starts observing push-to-start tokens under a single `#available(iOS 17.2, *)` check - `Info.plist` — `NSSupportsLiveActivities` + `NSSupportsLiveActivitiesFrequentUpdates` - `SettingsItem.swift` / `SettingsView.swift` — Live Activities settings row is gated behind `Current.isTestFlight` and shows a `BetaLabel` badge **Tests:** - *Unit Tests* - 45 new tests (36 handler tests, 9 command manager routing tests). All 490 existing tests continue to pass. - *Device Tests* - I tried to test with my physical device, however I do not have a paid account. Turns out I could not deploy without disabling a lot of entitlements for compilation. Even so, once I did get it deployed and running Live Activities wouldn't show unless some of those settings that I disable were re-enable and leaving me in a particular spot. - I mainly tested with the simulator which is what is shown below ## Screenshots  ## Link to pull request in Documentation repository Documentation: home-assistant/companion.home-assistant#1303 ## Link to pull request in push relay repository Relay server: home-assistant/mobile-apps-fcm-push#278 ## Link to pull request in HA core Core: home-assistant/core#166072 ## Any other notes **iOS version gating at 17.2.** The entire feature is gated at `#available(iOS 17.2, *)` — this is the minimum for push-to-start (the primary server-side start mechanism). A single availability check now covers all Live Activity APIs: `supports_live_activities`, `frequentPushesEnabled`, push-to-start token, and all ActivityKit usage. This eliminates the nested 16.2/17.2 check pattern. **Push-to-start (iOS 17.2+) is client-complete.** The token is observed, stored in Keychain, and included in registration payloads. All companion server-side PRs are now open — relay server at home-assistant/mobile-apps-fcm-push#278 and HA core webhook handlers at home-assistant/core#166072. The relay server uses FCM's native `apns.liveActivityToken` support (Firebase Admin SDK v13.5.0+) — no custom APNs client or credentials needed. > **Server-side work** — all PRs now open: > - ~~`supports_live_activities` field handling in device registration~~ ✓ home-assistant/core#166072 > - ~~`mobile_app_live_activity_token` webhook handler~~ ✓ home-assistant/core#166072 > - ~~`mobile_app_live_activity_dismissed` webhook handler~~ ✓ home-assistant/core#166072 > - ~~Relay server: Live Activity delivery via FCM `apns.liveActivityToken`~~ ✓ home-assistant/mobile-apps-fcm-push#278 > - ~~`notify.py` routing: includes Live Activity APNs token alongside FCM token~~ ✓ home-assistant/core#166072 **Live Activities entry in Settings is gated behind TestFlight.** The settings row only appears when `Current.isTestFlight` is true, preventing it from surfacing in a release build before the feature is fully tested. A `BetaLabel` badge is shown alongside the row title. **iPad:** `areActivitiesEnabled` is always `false` on iPad — Apple system restriction. The Settings screen shows "Not available on iPad." The registry silently no-ops. HA receives `supports_live_activities: false` in the device registration for iPad. **`HALiveActivityAttributes` is frozen post-ship.** The struct name appears as `attributes-type` in APNs push-to-start payloads. Renaming it silently breaks all remote starts. The `ContentState` `CodingKeys` are equally frozen — only additions are safe. Both have comments in the source calling this out. **The debug section in Settings is intentional.** Gated behind `#if DEBUG` so it only appears in debug builds — it never ships to TestFlight or the App Store. It exercises the full ActivityKit lifecycle without requiring the server-side chain. **`UNUserNotificationCenter` in tests.** The `clear_notification` + `tag` → Live Activity dismissal path is covered by code review rather than a unit test. `HandlerClearNotification` calls `UNUserNotificationCenter.current().removeDeliveredNotifications` synchronously, which requires a real app bundle and throws `NSInternalInconsistencyException` in the XCTest host. A comment in the test file explains this. **Rate limiting on iOS 18.** Apple throttles Live Activity updates to ~15 seconds between renders. Automations should trigger on state change events, not polling timers. **Related:** - Community discussion: https://github.com/orgs/home-assistant/discussions/84 - Android companion reference: https://github.com/home-assistant/android - Roadmap: OpenHomeFoundation/roadmap#52 --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com> Co-authored-by: Bruno Pantaleão Gonçalves <5808343+bgoncal@users.noreply.github.com>
|  Multiple Live Activities stack on the Lock Screen under the app group header. | ||
|
|
||
|  | ||
|
|
There was a problem hiding this comment.
Is it possible to hide a collapse section of the yamls use for screenshot? It would also help making screenshot for Android
There was a problem hiding this comment.
Are you asking for a collapsible <details> section under the screenshots showing the YAML used to generate them? Happy to add that, just want to make sure I'm implementing what you have in mind before making changes.
TimoPtr
left a comment
TimoPtr
left a comment
There was a problem hiding this comment.
Could you double check the assets I think some of them are not used anymore.
Only 5 of the 18 added assets are referenced in the documentation. Remove the 13 unreferenced images to keep the repository lean. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Restructure ending section: clear_notification is primary, end_live_activity only appears under a Dismissal policy subsection for lock screen control - Add Unix timestamp unit clarification and Jinja2 template example for after: policy - Convert Samsung devices plain text to :::note admonition Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add four Android screenshots provided by TimoPtr and place them
next to the equivalent iOS screenshots in the Starting, Updating,
and example sections. Also fix {% raw %} tag that broke MDX parsing.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
Just pushed some updates:
Still open / waiting on input:
cc: @inukiwi - Not sure if you have any concerns going forward still |
iPad supports Live Activities from iPadOS 17 — update requirements, remove the incorrect "iPad not supported" warning, and clarify that the Dynamic Island is iPhone Pro–only (iPad shows on Lock Screen only). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Dynamic Island is available on iPhone 14 Pro/Pro Max and all iPhone 15 and later models — not Pro-only. Clarify that older iPhones (notch/Home button) and iPad show the activity on the Lock Screen only. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
## Summary iPad has supported Live Activities since iPadOS 17 — the previous `userInterfaceIdiom == .pad` guard in `LiveActivitySettingsView` was incorrect. `areActivitiesEnabled` (the `ActivityAuthorizationInfo` API) already returns the correct value on iPad, so no platform-specific gate is needed. Changes: - Remove the `userInterfaceIdiom == .pad` branch from `LiveActivitySettingsView` that showed a static "Not available on iPad" label. iPad users now see the same enabled/open-settings states as iPhone. - Drop the `live_activity.status.not_supported` localisation key from all 34 locale files and the generated `Strings.swift` accessor. - Update a stale comment in `HAAPI.swift` that incorrectly stated iPads report `false` for `areActivitiesEnabled`. ActivityKit handles Dynamic Island availability transparently — the island pill appears on iPhone 14 Pro/Pro Max and all iPhone 15 and later models; on iPad and older iPhones it simply doesn't render, and the activity shows on the Lock Screen only. ## References - Apple docs confirming iPad support: [Displaying live data with Live Activities](https://developer.apple.com/documentation/activitykit/displaying-live-data-with-live-activities) - Companion docs PR: home-assistant/companion.home-assistant#1303 ## Test plan - [ ] On iPhone: Live Activities settings screen shows enabled/open-settings as before - [ ] On iPad (iPadOS 17+): settings screen no longer shows "Not available on iPad"; shows enabled/open-settings - [ ] On iPad (iPadOS 17+): Live Activities can be started and updated from Home Assistant - [ ] On iPad (iPadOS 16 or earlier): `areActivitiesEnabled` returns `false`; open-settings button shown - [ ] Verify `live_activity.status.not_supported` key is absent from all `.lproj` files 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
edenhaus
left a comment
edenhaus
left a comment
There was a problem hiding this comment.
Please remove anything (documentation, code parts) for end_live_activity
bgoncal
left a comment
bgoncal
left a comment
There was a problem hiding this comment.
Iterating over @edenhaus comment #1303 (comment)
What needs to be done now:
-
Remove dismissal policy
After some discussion we endup on the conclusion that the user can just update their live activity over and over again, no need to update to 100% and then decide x amount of seconds until dismissal, when it needs to get dismissed the user can automate callingclear_notificationcommand -
Remove "end_live_activity" command
Since "clear_notification" already exists and works for both platforms, it's easier to keep it simple now and have only 1 command.
Let me (or @edenhaus) know in case you have questions
Per edenhaus and bgoncal review — clear_notification already handles ending live activities on both platforms. Removing end_live_activity keeps the API simple and consistent. The dismissal_policy field goes with it. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
Updated the docs based on @bgoncal and @edenhaus discussions
Please let me know if there are any other discussions needing to be attended to. I left this one as unresolved: #1303 (comment) There are a few @TimoPtr conversations that need responses if neccessary |
|
Please link the PR, where you are removing also the code in iOS here so everything is linked |
Ah yes, I forgot I needed to remove from iOS as well: home-assistant/iOS#4616 - done |
|
fwiw: Didn’t mark as ready for review to not have it merged accidentally but it is technically ready for more reviews after my last update: |
Proposed change
Documents iOS Live Activities (iOS 17.2+), which lets Home Assistant automations push real-time state to the Lock Screen. Covers the full payload spec, start/update/end lifecycle, dismissal policy options, cross-platform YAML patterns shared with Android Live Updates, iPad limitations, iOS 18 rate limiting, and privacy disclosure behavior.
Changes:
docs/notifications/live-activities.md— new page with payload field reference, lifecycle examples, and screenshotsdocs/notifications/commands.md— addsend_live_activityto the iOS command table; notesclear_notificationwith atagalso ends a matching Live Activitydocs/notifications/basic.md— adds Live Activities subsection under iOS/macOS Specific with a sample automation; updates the Android Live Updates section to show thatlive_update: truetargets both platforms with a single field (no separate iOS key needed)sidebars.js— registers live-activities under Notificationsstatic/assets/ios/— 12 screenshots extracted and cropped from a simulator recordingType of change
Checklist
Additional information
Part of epic: home-assistant/epics#61
Fixes: home-assistant/iOS#4624