# Ha IOS Push Live Activities

> Live Activities and push notifications across the local-push and remote-push delivery flows. Use when implementing or fixing notifications, Live Activities, payload parsing/promotion, alerting behavior, or the SharedPush parser (including the vendored relay copy).

- Skill: `home-assistant/ha-ios-push-live-activities` (Agent Skill)
- Install (CLI): `npx skillmds@latest add home-assistant/ha-ios-push-live-activities`
- Raw SKILL.md: https://api.skillmd.com/api/skills/home-assistant/ha-ios-push-live-activities/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: home-assistant (https://skillmd.com/u/home-assistant)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/home-assistant/ha-ios-push-live-activities

---


# Live Activities & Push Notifications

**When implementing or fixing anything related to Live Activities (or push notifications generally), always check BOTH delivery flows — local push and remote push.** They are handled by different code paths, so a field, behavior, or fix applied to one is easily missed in the other (e.g. a payload key parsed for APNs but dropped over local push, or alerting/sound handled differently per flow).

- **Remote push (APNs / cloud)**: Home Assistant → the push relay (`Sources/PushServer`) → APNs → the app / `Sources/Extensions/NotificationService`. The payload already carries a `homeassistant` dictionary.
- **Local push (WebSocket / `NEAppPushProvider`)**: delivered over the on-network channel and handled by `Sources/Extensions/PushProvider` + `Sources/Shared/Notifications/LocalPush` (`LocalPushManager`, `LocalPushEvent`). The payload arrives as a flat `{message, data}` shape and is reshaped by `LegacyNotificationParserImpl` (`Sources/SharedPush/Sources/NotificationParserLegacy.swift`), which must explicitly **promote** `data` fields into `homeassistant` — any field not in that promotion list is silently dropped on this flow only.

Both flows converge on `NotificationCommandManager` → `HandlerStartOrUpdateLiveActivity` → `LiveActivityRegistry` (`Sources/Shared/LiveActivity`), with the UI rendered by `Sources/Extensions/Widgets/LiveActivity`.

Practical checklist when changing this area:
- If you add or read a notification/Live-Activity payload field, confirm it survives **both** the local-push parser promotion list and the remote-push payload.
- Verify alerting behavior (sound, haptics, banner suppression, the `silent` flag) on **both** flows — local push presents notifications through `LocalPushManager`, not the system directly.
- `Sources/SharedPush` is vendored as a separate copy under `Sources/PushServer/SharedPush` (the relay). Keep the two parser copies in sync when a parsing change is relevant to **both** the app and the relay; some logic intentionally lives in only one copy (e.g. the Live Activity `live_update` promotion is app-only, since the relay/cloud path already carries a `homeassistant` dict). When you change one copy, decide explicitly whether the other needs the same change.
- Add/extend tests for both flows (e.g. `Tests/Shared/LocalPushManager.test.swift` for the local path, `Sources/PushServer/Tests/SharedPushTests` for the relay/parser).