Add iOS Live Activities documentation by rwarner · Pull Request #1303 · home-assistant/companion.home-assistant

rwarner · 2026-03-19T20:55:59Z

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 screenshots
docs/notifications/commands.md — adds end_live_activity to the iOS command table; notes clear_notification with a tag also ends a matching Live Activity
docs/notifications/basic.md — adds Live Activities subsection under iOS/macOS Specific with a sample automation; updates the Android Live Updates section to show that live_update: true targets both platforms with a single field (no separate iOS key needed)
sidebars.js — registers live-activities under Notifications
static/assets/ios/ — 12 screenshots extracted and cropped from a simulator recording

Type of change

Document existing features within Home Assistant Companion App
Document new or changing features for which there is an existing pull request elsewhere
Spelling or grammatical corrections, or rewording for improved clarity
Changes to the backend of this documentation
Remove stale or deprecated documentation

Checklist

I have read and followed the documentation guidelines.
I have verified that my changes render correctly in the documentation.

Additional information

This PR fixes or closes issue: Fixes
- https://github.com/orgs/home-assistant/discussions/84
- "Live activities" for mobile apps OpenHomeFoundation/roadmap#52
Link to relevant pull request: Adds iOS Live Activities support iOS#4444

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>

rwarner · 2026-03-19T21:33:00Z

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>

bgoncal · 2026-03-30T13:44:33Z

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

Copilot

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_activity and clarifies clear_notification + tag behavior.
Updates the main notifications basics doc to explain that live_update: true targets both Android Live Updates and iOS Live Activities, and registers the new page in sidebars.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.

docs/notifications/commands.md

docs/notifications/live-activities.md

bgoncal · 2026-03-31T08:45:14Z

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>

rwarner · 2026-03-31T18:19:26Z

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.

cc: @bgoncal @TimoPtr

bgoncal · 2026-04-01T07:59:03Z

Drafting just so we dont merge it by mistake before the other PRs

TimoPtr · 2026-04-01T08:20:35Z

docs/notifications/basic.md

 ### 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.


I'm not a big fan to this new sentence having live_update as a the subject seems a bit weird.

Do you have a suggestion to reword it?

docs/notifications/basic.md

docs/notifications/commands.md

docs/notifications/live-activities.md

TimoPtr · 2026-04-01T08:32:44Z

docs/notifications/live-activities.md

+
+### Option 2 — `end_live_activity` command ![iOS](/assets/iOS.svg)
+
+Use this when you want to end the Live Activity without affecting other notifications. Requires iOS 17.2+.


Suggested change

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.

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.

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

docs/notifications/live-activities.md

static/assets/ios/live-activity-lockscreen.png

inukiwi · 2026-04-01T08:57:17Z

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.
The overlap is that they both display on the lockscreen, statusbar/Dynamic Island, and always-on display, but the progress bar and chronometer features are not part of "Live Updates" in Android: they can be used in regular notifications and can also be omitted from a live update notification.

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 live_update and critical_text parameter) and most of the documentation can be then be used by all Android users. The original documentation for the progress and chronometer notifications in Android can then also point to this new page to prevent duplicate information.

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>

rwarner · 2026-04-01T19:55:01Z

@inukiwi

The overlap is that they both display on the lockscreen, statusbar/Dynamic Island, and always-on display, but the progress bar and chronometer features are not part of "Live Updates" in Android: they can be used in regular notifications and can also be omitted from a live update notification.

Correct, perhaps we need to define a couple additional YAMLs marked as iOS only then? Or maybe I'm misunderstanding the limitations on the Android side.

From searching, it seems like the following is the situation:

progress, progress_max, chronometer, when, when_relative, notification_icon all work on any Android version in regular notifications — we're incorrectly implying they're Android 16+ only by bundling everything under the Live Updates umbrella.

What's actually Android 16+ only: Just live_update: true and critical_text in the status bar chip context.

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 live_update tag, but they are inherently different but slightly similiar.

PR Updates

Beta flag for iOS → basic.md BETA badge
iOS-only indicator on end_live_activity → commands.md iOS badge
Remove platform icons from header → live-activities.md
Real value for default dismissal policy → live-activities.md with Apple doc link
iPad → :::warning → live-activities.md
Group restrictions into a note → live-activities.md :::note
Apple doc link for 8-hour limit → live-activities.md
Samsung note already a :::note → no change needed

Replied to all comments that need feedback

This was referenced Mar 19, 2026

Adds iOS Live Activities support home-assistant/iOS#4444

Draft

"Live activities" for mobile apps OpenHomeFoundation/roadmap#52

Open

rwarner mentioned this pull request Mar 20, 2026

Add iOS Live Activity webhook handlers to mobile_app home-assistant/core#166072

Draft

7 tasks

rwarner and others added 2 commits March 26, 2026 10:27

Update Live Activities minimum iOS version to 17.2

004ee90

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

bgoncal requested a review from Copilot March 30, 2026 13:44

Copilot started reviewing on behalf of bgoncal March 30, 2026 13:45 View session

Copilot AI reviewed Mar 30, 2026

View reviewed changes

docs/notifications/commands.md Outdated Show resolved Hide resolved

docs/notifications/live-activities.md Outdated Show resolved Hide resolved

docs/notifications/live-activities.md Outdated Show resolved Hide resolved

bgoncal marked this pull request as draft March 31, 2026 08:44

rwarner and others added 2 commits March 31, 2026 14:02

rwarner marked this pull request as ready for review April 1, 2026 01:53

bgoncal requested review from TimoPtr and jpelgrom April 1, 2026 07:41

bgoncal marked this pull request as draft April 1, 2026 07:58

TimoPtr reviewed Apr 1, 2026

View reviewed changes

rwarner requested review from TimoPtr, bgoncal and edenhaus April 1, 2026 19:55


		### Option 2 — `end_live_activity` command ![iOS](/assets/iOS.svg)

		Use this when you want to end the Live Activity without affecting other notifications. Requires iOS 17.2+.

Uh oh!

Conversation

rwarner commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed change

Type of change

Checklist

Additional information

Uh oh!

rwarner commented Mar 19, 2026

Uh oh!

bgoncal commented Mar 30, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bgoncal commented Mar 31, 2026

Uh oh!

rwarner commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bgoncal commented Apr 1, 2026

Uh oh!

TimoPtr Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

rwarner Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

TimoPtr Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

edenhaus Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

rwarner Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

inukiwi commented Apr 1, 2026

Uh oh!

rwarner commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

rwarner commented Mar 19, 2026 •

edited

Loading

rwarner commented Mar 31, 2026 •

edited

Loading

rwarner commented Apr 1, 2026 •

edited

Loading