Add live activity token retention, notify usage and clean up cycle to mobile_app by bgoncal · Pull Request #172928 · home-assistant/core

bgoncal · 2026-06-03T15:53:15Z

Breaking change

Proposed change

This PR takes over #166072

This PR makes it possible to store live activity tokens and retain in mobile_app so Home Assistant is able to initiate live activities in iOS devices.

This PR also has a clean up cycle for those tokens and an endpoint to expire them in case they are not needed (ended by the user)

Type of change

Dependency upgrade
Bugfix (non-breaking change which fixes an issue)
New integration (thank you!)
New feature (which adds functionality to an existing integration)
Deprecation (breaking change to happen in the future)
Breaking change (fix/feature causing existing functionality to break)
Code quality improvements to existing code or addition of tests

Additional information

This PR fixes or closes issue: fixes #
This PR is related to issue:
Link to documentation pull request: Add iOS Live Activities documentation companion.home-assistant#1303
Link to developer documentation pull request:
Link to frontend pull request:
Link to iOS pull request: Fine tuning Live Activity implementation iOS#4696
Link to Firebase (FCM) pull request: Add iOS Live Activity push support mobile-apps-fcm-push#309

Checklist

I understand the code I am submitting and can explain how it works.
The code change is tested and works locally.
Local tests pass. Your PR cannot be merged unless tests pass
There is no commented out code in this PR.
I have followed the development checklist
I have followed the perfect PR recommendations
The code has been formatted using Ruff (ruff format homeassistant tests)
Tests have been added to verify that the new code works.
Any generated code has been carefully reviewed for correctness and compliance with project standards.

If user exposed functionality or configuration variables are added/changed:

Documentation added/updated for www.home-assistant.io

If the code communicates with devices, web services, or third-party tools:

The manifest file has all fields filled out correctly.
Updated and included derived files by running: python3 -m script.hassfest.
New or updated dependencies have been added to requirements_all.txt.
Updated by running python3 -m script.gen_requirements_all.
For the updated dependencies a diff between library versions and ideally a link to the changelog/release notes is added to the PR description.

To help with the load of incoming pull requests:

I have reviewed two other open pull requests in this repository.

Add support for iOS Live Activities in the mobile_app integration: - Add `supports_live_activities`, `supports_live_activities_frequent_updates`, `live_activity_push_to_start_token`, and `live_activity_push_to_start_apns_environment` fields to SCHEMA_APP_DATA for explicit validation during device registration - Add `update_live_activity_token` webhook handler: stores per-activity APNs push tokens reported by the iOS companion app when a Live Activity is created locally via ActivityKit - Add `live_activity_dismissed` webhook handler: cleans up stored tokens when a Live Activity ends on the device - Both handlers fire bus events so automations can react to activity lifecycle - Add `supports_live_activities()` utility helper - Add 4 tests covering token storage, default environment, dismissal cleanup, and nonexistent tag dismissal for: home-assistant/mobile-apps-fcm-push#278 for: home-assistant/iOS#4444 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Define EVENT_LIVE_ACTIVITY_TOKEN_UPDATED and EVENT_LIVE_ACTIVITY_DISMISSED constants in const.py instead of inline f-strings - Add ATTR_APNS_ENVIRONMENT constant for schema and data access - Add EventOrigin.remote to async_fire calls, matching webhook_fire_event pattern - Use DATA_LIVE_ACTIVITY_TOKENS constant in tests instead of string literals - Import event constants in tests for consistency Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Make push-to-start token and environment vol.Inclusive so they must be provided together — a token without an environment is ambiguous since sandbox tokens are rejected by the production APNs endpoint - Clean up DATA_LIVE_ACTIVITY_TOKENS for the webhook_id in async_unload_entry to prevent stale tokens accumulating in memory when devices are removed or re-added Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

When a notification contains live_activity: true and a tag, the notify service now routes it through the dedicated APNs relay endpoint instead of FCM. This completes the direct APNs delivery path: 1. Per-activity token — if the iOS app has registered a push token for the given tag (via update_live_activity_token webhook), use that token and its stored push_url to deliver directly to the running activity. 2. Push-to-start fallback — if no per-activity token exists but the device has a push-to-start token in app_data (iOS 17.2+), use that to start a new activity remotely without the app being open. 3. Normal FCM — if live_activity is not set, or no tag is provided, the notification flows through the existing FCM path unchanged. The apns_environment (sandbox/production) is included in registration_info so the relay server can route to the correct APNs endpoint. Adds 4 tests: stored token routing, push-to-start fallback, no-tag fallthrough, and normal notification ignoring stored tokens. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

FCM v1 API natively supports Live Activities via apns.liveActivityToken. This simplifies the core integration: - notify.py: instead of routing to a separate relay URL, sends both the FCM token (push_token) and Live Activity APNs token (live_activity_token) to the SAME relay endpoint. The relay server places it in the FCM message's apns.liveActivityToken field, and FCM handles APNs delivery. - webhook.py: update_live_activity_token schema simplified — removed push_url and apns_environment (FCM handles routing automatically) - const.py: removed ATTR_APNS_ENVIRONMENT (no longer needed) - Tests updated to match simplified token storage and routing Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- notify.py: guard against non-string tag values in notification payload to avoid runtime errors when used as dict key - webhook.py: use ATTR_DEVICE_ID and CONF_WEBHOOK_ID constants in event data instead of string literals for consistency Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- webhook.py: reject empty push tokens with vol.Length(min=1) in update_live_activity_token schema - notify.py: use `is not True` for live_activity flag to prevent truthy non-bool values like string "false" from triggering Live Activity routing - const.py: reject empty push-to-start tokens with vol.Length(min=1) in SCHEMA_APP_DATA Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…ssed tag, add unload test - Replace CONF_WEBHOOK_ID with ATTR_WEBHOOK_ID as the key in EVENT_LIVE_ACTIVITY_TOKEN_UPDATED and EVENT_LIVE_ACTIVITY_DISMISSED payloads to keep runtime event data semantically separate from config constants - Require non-empty ATTR_LIVE_ACTIVITY_TAG in the live_activity_dismissed webhook schema (vol.Length(min=1)) to match the update handler and prevent stale token store entries from empty tags - Add test_unload_removes_live_activity_tokens to verify live activity tokens are purged from hass.data when a config entry is unloaded Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

…ivities Unifies the iOS and Android notification data field: live_update: true now triggers Live Activity routing on iOS, matching the field Android already uses. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…y _get_live_activity_token signature - Drop EVENT_LIVE_ACTIVITY_TOKEN_UPDATED and EVENT_LIVE_ACTIVITY_DISMISSED — nothing consumes these events in any of the three repos (no automation triggers, no iOS listener, no relay usage), so they add noise without value - Remove supports_live_activities() from util.py — defined but never called - Pass app_data directly into _get_live_activity_token instead of the full registration dict (edenhaus review feedback) - Group Live Activity push constants with other PUSH attrs in const.py - Update tests to remove event-capture assertions Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

The generic 'tag' field name collides with the notification tag used elsewhere in mobile_app. Using 'live_activity_tag' makes the webhook contract unambiguous. notify.py continues to read 'tag' from the notification payload (user YAML) unchanged. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Core registered 'update_live_activity_token' and 'live_activity_dismissed' but the iOS app sends 'mobile_app_live_activity_token' and 'mobile_app_live_activity_dismissed', matching the mobile_app_ prefix convention used elsewhere in the integration. Rename core handlers to match. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

live_update is the cross-platform YAML key shared with Android; on iOS it maps to ActivityKit Live Activities, on Android to a different mechanism. The live_activity naming in webhook handlers and token storage is intentionally iOS-specific. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Remove unused ATTR_SUPPORTS_LIVE_ACTIVITIES and ATTR_SUPPORTS_LIVE_ACTIVITIES_FREQUENT_UPDATES constants and schema entries - Add ATTR_LIVE_UPDATE, ATTR_LIVE_ACTIVITY_TOKEN, and ATTR_PUSH_TAG constants; replace hardcoded strings - Simplify tag check: remove redundant isinstance(tag, str) guard - Use walrus operator for live activity token assignment in notify.py - Store live activity push token as a plain string instead of a dict - Remove comment before webhook registration already described in docstring - Simplify push-to-start token return to app_data.get(...) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Drop vol.Length(min=1) from the tag and push token fields — consistent with webhook_scan_tag which uses plain cv.string. APNs tokens are explicitly variable length per Apple docs; hardcoding a minimum is both inconsistent and fragile. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…lution Two Live Activity test docstrings lost their indentation when resolving rebase conflicts, causing a syntax error. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Consistent with all other webhook types in this integration which use short names (scan_tag, update_location, etc.) without a mobile_app_ prefix. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Remove unused AsyncGenerator import from notify.py - Sort ATTR_PUSH_TAG import alphabetically (after ATTR_PUSH_RATE_LIMITS_SUCCESSFUL) - Wrap long line in webhook_update_live_activity_token Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Store per-activity tokens as {"push_token": <token>} dict in DATA_LIVE_ACTIVITY_TOKENS so the structure matches test expectations and leaves room for additional fields without a schema change - Update _get_live_activity_token to read the push_token key from the dict - Update test_notify.py setups to use dict format - Fix stale "mobile_app_live_activity_token" type name in test_init.py (should be "live_activity_token" after the prefix-drop rename) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

…anup Tokens are now stored via a dedicated Store (mobile_app.live_activity_tokens) so they survive HA restarts. Each token is saved with a stored_at timestamp; tokens older than 8 hours are filtered on load and cleaned up lazily on lookup. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Removes the separate live_activity_tokens store. Tokens are now saved in the main mobile_app store (STORAGE_VERSION bumped to 2). Existing v1 data is migrated inline by defaulting the new key to {}. Stores timestamps as floats so no custom datetime parsing is needed. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

Tokens should survive unload (restart/reload) so they are available when the entry loads again. Remove them only in async_remove_entry, when the device is permanently deleted. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

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

edenhaus · 2026-06-04T13:57:39Z

@@ -0,0 +1,87 @@
+"""Live Activity webhook handlers."""


Please move the websocket commands to the websocket class

Webhook you mean? Why can't we separate based on feature? Otherwise we will have a "monster class" one day

edenhaus · 2026-06-04T13:59:15Z

        """Send a message to a target."""
+        # Applies Apple ActivityKit Live Activity routing when the payload asks
+        # for it; otherwise it returns the original generic mobile push data.
+        remote_push = prepare_live_activity_remote_push(self.hass, entry.data, data)


We are calling this function always not not just for apple devices. It make no sense to put this function in a live activity file if we are even calling it always.
Live activity stuff should just be called when needed

Do you see a way to differentiate while keeping code separation in mind? Open for ideas

home-assistant · 2026-06-04T14:05:18Z

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.

Co-authored-by: Robert Resch <robert@resch.dev>

bgoncal · 2026-06-04T22:15:28Z

Re-tested for local push and firebase, in the current state both work ✅

rwarner and others added 30 commits April 29, 2026 13:12

Require non-empty tag in update_live_activity_token webhook schema

d9df34f

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

Remove unused ATTR_WEBHOOK_ID import from webhook.py

23ff061

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

Fix test_init.py to use renamed webhook type and tag field

61a609b

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

Fix docstring indentation in test_notify.py after merge conflict reso…

9d9ef58

…lution Two Live Activity test docstrings lost their indentation when resolving rebase conflicts, causing a syntax error. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Rename live activity webhooks to drop mobile_app_ prefix

a1a6db3

Consistent with all other webhook types in this integration which use short names (scan_tag, update_location, etc.) without a mobile_app_ prefix. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

mobile_app: simplify live activity comments and docstrings

978d802

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

mobile_app: restore websocket channel comment in SCHEMA_APP_DATA

1437794

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

Merge upstream/dev into feat/ios-live-activity

883f1f8

mobile_app: fix pylint hass-use-runtime-data in savable_state

16fde1c

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

mobile_app: fix import order in test_notify

83ee21a

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

bgoncal requested a review from edenhaus June 3, 2026 15:55

bgoncal mentioned this pull request Jun 3, 2026

Add iOS Live Activity webhook handlers to mobile_app #166072

Closed

7 tasks

bgoncal added 2 commits June 3, 2026 17:57

Document live activity push routing

d51de14

Merge branch 'dev' into live-activity-last-mile

7b6e08a

Copilot AI review requested due to automatic review settings June 3, 2026 15:57

Copilot AI reviewed Jun 3, 2026

View reviewed changes

Comment thread tests/components/mobile_app/test_init.py

Comment thread tests/components/mobile_app/test_init.py

Comment thread homeassistant/components/mobile_app/live_activity/__init__.py Outdated

Comment thread homeassistant/components/mobile_app/__init__.py

Clarify ActivityKit routing comments

1776af6

bgoncal commented Jun 3, 2026

View reviewed changes

Comment thread homeassistant/components/mobile_app/notify.py Outdated

Improve naming and add comments

e21b629

Copilot AI review requested due to automatic review settings June 4, 2026 09:32

bgoncal added 3 commits June 4, 2026 11:36

Rename live activity tag constant

de47f7b

Move live activity token storage comment

ff5de45

Separate live activity push-to-start token key

9e96478

bgoncal mentioned this pull request Jun 4, 2026

Live Activities in iOS home-assistant/epics#61

Open

bgoncal added 7 commits June 4, 2026 12:04

Move live activity helpers into module

d057e14

Clarify live activity cleanup naming

9f2f7b5

Remove redundant live activity comment

830cc39

Move Live Activity related code to separate files and folder

b749ac8

Keep remote notification sending generic

ab773c5

Address live activity review comments

b9221f8

Merge branch 'dev' into live-activity-last-mile

ecff7fa

bgoncal marked this pull request as ready for review June 4, 2026 11:46

bgoncal requested a review from a team as a code owner June 4, 2026 11:46

edenhaus requested changes Jun 4, 2026

View reviewed changes

home-assistant Bot marked this pull request as draft June 4, 2026 14:05

bgoncal and others added 3 commits June 4, 2026 16:11

Update __init__.py

8f34c9e

Co-authored-by: Robert Resch <robert@resch.dev>

Update const.py

3f8977d

Co-authored-by: Robert Resch <robert@resch.dev>

Fix ATTR

ec936a0

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add live activity token retention, notify usage and clean up cycle to mobile_app#172928

Add live activity token retention, notify usage and clean up cycle to mobile_app#172928
bgoncal wants to merge 71 commits into
home-assistant:devfrom
bgoncal:live-activity-last-mile

bgoncal commented Jun 3, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

edenhaus Jun 4, 2026

Uh oh!

bgoncal Jun 4, 2026

Uh oh!

Uh oh!

edenhaus Jun 4, 2026

Uh oh!

bgoncal Jun 4, 2026

Uh oh!

Uh oh!

home-assistant Bot commented Jun 4, 2026

Uh oh!

bgoncal commented Jun 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

bgoncal commented Jun 3, 2026

Breaking change

Proposed change

Type of change

Additional information

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

edenhaus Jun 4, 2026

Choose a reason for hiding this comment

Uh oh!

bgoncal Jun 4, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

edenhaus Jun 4, 2026

Choose a reason for hiding this comment

Uh oh!

bgoncal Jun 4, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

home-assistant Bot commented Jun 4, 2026

Uh oh!

bgoncal commented Jun 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants