Adds iOS Live Activities support

[rwarner]

Summary

For architecture decisions, data model details, iOS version strategy, push token flow, and rate limiting — see 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_activity: 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 — a single YAML automation block targets both platforms.

data:
  title: "Washing Machine"
  message: "Cycle in progress"
  data:
    tag: washer_cycle
    live_update: true           # Android 16+
    live_activity: true         # iOS 16.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 16.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
• AppDelegate.swift — reattaches surviving activities at launch; observes push-to-start token stream (iOS 17.2+)
• Info.plist — NSSupportsLiveActivities + NSSupportsLiveActivitiesFrequentUpdates

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 16.2, not 16.1. The ActivityContent API (required for staleDate and anything practically useful) is 16.2+. The 16.1-only API is deprecated and produces blank activity cards. iOS 16.1 was a 3-week window in late 2022 — gating at 16.2 removes ~35 lines of dead deprecated code and eliminates the blank card scenario.

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 ✓ Add iOS Live Activity webhook handlers to mobile_app core#166072
• mobile_app_live_activity_token webhook handler ✓ Add iOS Live Activity webhook handlers to mobile_app core#166072
• mobile_app_live_activity_dismissed webhook handler ✓ Add iOS Live Activity webhook handlers to mobile_app core#166072
• Relay server: Live Activity delivery via FCM apns.liveActivityToken ✓ Add iOS Live Activity push support mobile-apps-fcm-push#278
• notify.py routing: includes Live Activity APNs token alongside FCM token ✓ Add iOS Live Activity webhook handlers to mobile_app core#166072

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: "Live activities" for mobile apps roadmap#52

[Copilot]

Pull request overview

Adds ActivityKit-based Live Activities support to the Home Assistant iOS app, enabling notifications to start/update/end a Lock Screen/Dynamic Island Live Activity via homeassistant.command or homeassistant.live_activity payload fields, plus UI/settings and device registration support.

Changes:

• Adds a Live Activity attributes model and an actor-based registry to manage activity lifecycle, push tokens, and dismissal reporting.
• Extends notification command routing/handlers to start/update/end Live Activities (including clear_notification + tag dismissal).
• Adds widget extension ActivityConfiguration UI, settings UI, localization strings, and new unit tests for routing/handlers.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
Tests/Shared/LiveActivity/NotificationsCommandManagerLiveActivityTests.swift	Adds routing tests for live_activity, end_live_activity, and flag-based routing.
Tests/Shared/LiveActivity/MockLiveActivityRegistry.swift	Provides a registry test double for handler/manager tests.
Tests/Shared/LiveActivity/HandlerLiveActivityTests.swift	Adds validation/parsing/guard/dismissal-policy tests for the new handlers.
Sources/Shared/Settings/SettingsStore.swift	Persists a “privacy disclosure seen” flag for Live Activities.
Sources/Shared/Resources/Swiftgen/Strings.swift	Adds generated localization accessors for Live Activities settings strings.
Sources/Shared/Notifications/NotificationCommands/NotificationsCommandManager.swift	Registers Live Activity commands and adds live_activity: true routing + clear_notification Live Activity end behavior.
Sources/Shared/Notifications/NotificationCommands/HandlerLiveActivity.swift	Implements start/update and end handlers, including payload parsing and validation.
Sources/Shared/LiveActivity/LiveActivityRegistry.swift	Adds an actor to manage activities, observe token/lifecycle streams, and report webhooks.
Sources/Shared/LiveActivity/HALiveActivityAttributes.swift	Defines ActivityAttributes / ContentState wire model for Live Activities.
Sources/Shared/Environment/Environment.swift	Adds apnsEnvironment helper and a lazily created liveActivityRegistry environment dependency.
Sources/Shared/API/HAAPI.swift	Extends registration payload with Live Activities capability and token fields.
Sources/Extensions/Widgets/Widgets.swift	Registers the Live Activity widget configuration in widget bundles with iOS 16.2 gating.
Sources/Extensions/Widgets/LiveActivity/HALockScreenView.swift	Implements the Lock Screen/StandBy UI for the activity.
Sources/Extensions/Widgets/LiveActivity/HALiveActivityConfiguration.swift	Adds ActivityConfiguration wrapper for the Live Activity widget.
Sources/Extensions/Widgets/LiveActivity/HADynamicIslandView.swift	Implements Dynamic Island compact/minimal/expanded views.
Sources/App/Settings/Settings/SettingsItem.swift	Adds Live Activities to Settings navigation and gates it behind iOS 16.2.
Sources/App/Settings/LiveActivity/LiveActivitySettingsView.swift	Adds a settings screen for status, active activities list, privacy text, and debug scenarios.
Sources/App/Resources/en.lproj/Localizable.strings	Adds English strings for Live Activities settings UI.
Sources/App/Resources/Info.plist	Enables Live Activities + Frequent Updates support via Info.plist keys.
Sources/App/AppDelegate.swift	Reattaches surviving activities at launch and starts observing push-to-start tokens (iOS 17.2+).
HomeAssistant.xcodeproj/project.pbxproj	Adds new source files/groups and adjusts build settings (including a Widgets debug signing team).

[Copilot]

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 4 comments.

[bgoncal]

tip for lint you can use bundle exec fastlane autocorrect

[bgoncal]

Can you make a screen recording showing the whole flow? Showing HA UI sending the push and iPhone handling it

[rwarner]

Can you make a screen recording showing the whole flow? Showing HA UI sending the push and iPhone handling it

So I don't have a paid Apple dev account so apparently the only way I could get it to compile to an actual device (to try to get push notifs) was to rip a bunch of entitlements out to compile for my physical device. For the emulator, I wasn't sure how to do a full-end-to-end test with the four repo changes altogether and run that locally. Theoretically it seemed like a possibility to do a local push to the emulated device but didn't get to that point.

Mainly why I created the debug options in the screenshot section showcasing all of the possibilities with the YAML at the moment. (This is in App Companion Settings -> Live Activity -> DEBUG options)

I don't mind putting some more stuff together, lemme know any specifics you would like to see and I can try. There's also more screenshots in the documentation repo here: home-assistant/companion.home-assistant#1303

[bgoncal]

Nowadays you can already test push notification on simulator as well from what I can remember, check this https://www.tiagohenriques.dev/blog/testing-push-notifications-ios-simulators

[rwarner]

Thanks, I'll look at this and see if I can produce some more examples for you / video on top of the previous gif

[rwarner]

Nowadays you can already test push notification on simulator as well from what I can remember, check this https://www.tiagohenriques.dev/blog/testing-push-notifications-ios-simulators

Thanks for the link! I looked into xcrun simctl push — from my testing, it delivers through UNUserNotificationCenter rather than ActivityKit's push token channel, so Live Activity payloads (event, content-state, etc.) arrive as regular notifications instead of updating the running activity. The simulator also returns nil for ActivityKit push tokens, so real APNs delivery to a Live Activity isn't possible either. Happy to be corrected if there's a way I'm missing!

For the local WebSocket path, the simulator is currently connecting through Nabu Casa (cloud relay), so notifications route through FCM rather than the local WebSocket channel. I'd need to be on the same local network as the HA instance for WebSocket-based delivery to work — I'll try to set that up.
Update: Would need a new Hass instance running my new core feature branch

In the meantime, I've added two screen recordings demonstrating start/update/end with various payload configurations on the simulator. The debug section in Settings also exercises all the UI states. As well as correcting the linting issues

Settings.Area.mp4

Debug.sample.mp4

[rwarner]

Progress with xcrun simctl actually, I was able to get a "push" to work using the following file and a small recent code change I just pushed

live_activity_test.apns

{
  "Simulator Target Bundle": "com.rwarner.ha.HomeAssistant.dev",
  "aps": {
    "alert": {
      "title": "Washing Machine",
      "body": "Cycle in progress"
    },
    "mutable-content": 1,
    "content-available": 1
  },
  "homeassistant": {
    "live_activity": true,
    "tag": "washer_cycle",
    "title": "Washing Machine",
    "message": "Cycle in progress",
    "progress": 2700,
    "progress_max": 3600,
    "chronometer": true,
    "when": 2700,
    "when_relative": true,
    "notification_icon": "mdi:washing-machine",
    "notification_icon_color": "#2196F3"
  }
}

xcrun simctl push booted com.rwarner.ha.HomeAssistant.dev /tmp/live_activity_test.apns

Which works while the application is in the foreground of the iPhone:

For some reason the dynamic island in the emulator is fussy but pops up very quickly

trimmed.mp4

Tests: push payload → NotificationCommandManager → HandlerStartOrUpdateLiveActivity → LiveActivityRegistry → ActivityKit → Lock Screen

However to test an actual background push Live Activity handler from what I can figure out I would need:

• Local WebSocket — HA instance compiled with my core changes on same network
• Real APNs — paid developer account
• FCM — production Firebase project matching the bundle ID
• ?Apple's Push Notification console in their paid dev area?

[bgoncal]

Local WebSocket — HA instance compiled with my core changes on same network

You have that already right? Because you opened a PR for core as well, so you can use that instance you used to test core to connect to the iOS App

[home-assistant]

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍

Learn more about our pull request process.

[codecov]

Codecov Report

❌ Patch coverage is 41.26074% with 205 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@db92bab). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
...ces/Shared/LiveActivity/LiveActivityRegistry.swift	0.00%	172 Missing ⚠️
Sources/Shared/API/HAAPI.swift	26.08%	17 Missing ⚠️
...Shared/LiveActivity/HALiveActivityAttributes.swift	60.00%	6 Missing ⚠️
Sources/Shared/Environment/Environment.swift	64.28%	5 Missing ⚠️
...ficationCommands/NotificationsCommandManager.swift	77.27%	5 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4444   +/-   ##
=======================================
  Coverage        ?   42.71%           
=======================================
  Files           ?      269           
  Lines           ?    15918           
  Branches        ?        0           
=======================================
  Hits            ?     6799           
  Misses          ?     9119           
  Partials        ?        0           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[bgoncal]

In your example we have 2 different tags, one for android and one for iOS:

    live_update: true           # Android 16+
    live_activity: true         # iOS 16.2+

Should we use the same as android has so the user does not need 2 different approaches based on platform? Are there more differences that we could merge into a single approach?

[rwarner]

Local WebSocket — HA instance compiled with my core changes on same network

You have that already right? Because you opened a PR for core as well, so you can use that instance you used to test core to connect to the iOS App

Correct yeah, I haven't stood up core before locally from the repo will take a stab and see if I can ping HASS Core directly from the localhost from the iPhone sim. Was just using my personal instance to try at first.

---

In your example we have 2 different tags, one for android and one for iOS:

    live_update: true           # Android 16+
    live_activity: true         # iOS 16.2+

Should we use the same as android has so the user does not need 2 different approaches based on platform? Are there more differences that we could merge into a single approach?

Great point actually. I can change this to just use the pre-existing live_update YAML that Android already uses and nobody has to make YAML additions / changes. (This would also require updating the other repos but honestly might be worth it)

Unless you think it would be handy to have the following example:

they might want a Live Activity on iOS but a regular sticky notification on Android (or vice versa).

But overall, the field names inside data (tag, progress, chronometer, etc.) are already unified across both platforms — it's only the opt-in trigger that's separate.

---

Responded to all comments and questions, updated suggested code changes and integrated requested tests.

[rwarner]

Great news, I was able to get core up and running locally and run the web socket test. Found two bugs I pushed up involving using the simulator. Got the live activity coming in via YAML:

Websocket.Demo.mov