Skip to content

Messaging: deliver the notification tap that launches a closed Kivy app - #12

Merged
kengoon merged 2 commits into
mainfrom
feat/notification-launch-tap
Nov 12, 2026
Merged

kengoon merged 2 commits into
mainfrom
feat/notification-launch-tap

Conversation

@kengoon

@kengoon kengoon commented Nov 12, 2026

Copy link
Copy Markdown
Contributor

The problem

When a user taps a notification while a Kivy app is closed, the app opens, but on_open never runs, so the app can't know which notification was tapped.

iOS delivers that tap during launch. A Kivy app's Python starts only after launch, when SDL starts the interpreter, so there is no handler yet. The system log shows iOS answering response-not-possible and dropping the tap. I checked that nothing keeps it for later:

  • SDL's SDLUIKitSceneDelegate doesn't keep the connection options;
  • UIKit's scene and UIApplication have nothing pending.

So no Python code can recover it.

The fix: an optional native hook, and no API change

  • The new package: pyios-firebase-notifications-hook (tag 0.1.0) is a tiny Swift package, one Objective-C file.
    • Its +load runs before Python. It wraps application:didFinishLaunchingWithOptions: on SDL's delegate class, with a fallback on UIApplicationDidFinishLaunchingNotification.
    • It sets a notification-center delegate before launch ends, and keeps each UNNotificationResponse.
    • It never replaces a delegate the app set itself. The idea is credited to kivyforge's ios-lifecycle-hook example (MIT).
  • notifications.set_handlers(on_open=...): if the hook is in the app, it takes the kept taps and passes them to on_open on the main thread's next turn (once the event loop runs).
    • They arrive as full Notifications, built with the same from_native as any other tap.
    • They're reported to Firebase Messaging's "opened" statistics, once Firebase is configured.
    • Without an on_open, they stay in the hook.
  • notifications.launch_hook_status(): returns None without the hook, otherwise its status (for example "ok: SDLUIKitSceneDelegate").
  • Without the hook, nothing changes. Taps while the app is open or in the background never needed it. Toga apps should not need it either, since Python starts before launch there (not tested yet).

e2e

  • New phase 6 in run_ios_e2e.sh:
    1. Get notification permission, tapping Allow with idb if the dialog appears.
    2. Close the app and simctl push a notification.
    3. Tap the home-screen banner with idb until the app launches.
    4. Check what on_open recorded: title, body, data, FCM message ID and action.
  • The e2e app installs its recorder at every launch, before App.run() (notification_open.py). It idles when launched without E2E_PHASE, which is the case for a tap launch.
  • Found along the way: a simulator booted while SIMCTL_CHILD_* variables are set keeps them for every app launch (launchd_bootstrap.plist), even a tap launch. The script now boots the simulator itself with a clean environment, and restarts a device that has them.
  • Result: 83 passed, 1 skipped (TOTP). test_notification_tap_launches_closed_app passes with the published package. on_open received the notification 0.36 s after Python started.

Docs

  • Notifications: a new section, "When the app is closed", with a table of which taps reach on_open, the setup, and the status helper.
  • App configuration: the hook is in the Messaging section and on the combined configuration page. All 15 kivyforge blocks load with kivyforge's own config loader.
  • README: a short note and a Troubleshooting row (only additions).

Checks

908 unit tests pass, including new tests for delivery, waiting for on_open, no-hook behaviour and the status helper. ruff, mypy (strict), pyright and mkdocs build --strict are clean.

🤖 Generated with Claude Code

iOS delivers that tap during launch, before a Kivy app's Python starts, and
drops it ("response-not-possible"): on_open never ran. The new optional
Swift package pyios-firebase-notifications-hook
(github.com/PySimpleObjC/pyios-firebase-notifications-hook, 0.1.0) sets a
notification-center delegate before launch ends and keeps the tap.

- notifications.set_handlers(on_open=...) takes the kept taps and passes
  them to on_open on the main thread's next turn (once the event loop runs),
  as full Notifications; it reports them to Firebase Messaging's open
  statistics once Firebase is configured. Without on_open, they wait.
  Without the hook, nothing changes.
- notifications.launch_hook_status(): None without the hook, else its status
- e2e: phase 6 closes the app, pushes a notification, taps the banner with
  idb, and checks what on_open got; the app records taps at every launch
  (notification_open.py) and idles without E2E_PHASE (a tap launch)
- e2e: the script boots the simulator itself; a device booted with
  SIMCTL_CHILD_* variables kept them for every launch (launchd_bootstrap.plist)
- docs: Notifications > When the app is closed; the hook in the Messaging and
  combined App configuration (every kivyforge block loads in kivyforge);
  README note and troubleshooting row

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@jetbrains-air jetbrains-air Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me, approving — thanks for this! 🎉

Comment thread e2e/run_ios_e2e.sh Outdated
sleep 12
xcrun simctl terminate "$DEVICE_UDID" "$BUNDLE_ID" >/dev/null 2>&1 || true
for _ in $(seq 1 8); do
allow="$(ui_find Allow)"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Problem: phase 6 runs under set -euo pipefail, and several of its idb calls are not guarded: allow="$(ui_find Allow)" (where idb ui describe-all … 2>/dev/null | python3 … json.load fails when idb returns nothing), and the bare idb ui tap calls here and at line 282.

Failure scenario: idb is installed but the companion can't reach the simulator (no companion, or a stale idb connect, which || true lets through). describe-all prints nothing, json.load raises, the pipeline returns 1, and the assignment makes the whole script exit. No launch_tap_result is written and the combined summary never prints, so the results of phases 1–5 are lost too, and the run ends with a bare exit code and no failing test name.

Suggested fix: keep phase 6 failures inside phase 6. Use allow="$(ui_find Allow || true)", add || true to the idb ui tap calls (and to the simctl push), or check once that idb works (idb ui describe-all --udid "$DEVICE_UDID" >/dev/null 2>&1 || launch_tap_result skip "idb cannot reach the simulator") before the tap steps.


Produced by Air Automations. Name: Code Review / Run: https://air.jetbrains.cloud/org/a114b0a9-2e82-18ec-abd3-29d0c8a05e2d/automations/c07b9901-fe4e-417d-ae1d-e00c83e39e4c?run=a8c01e51-120d-4c3b-b6e0-1f23c1af1a1d

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 9504c0a, as you suggested. Phase 6 first checks that idb ui describe-all reaches the simulator; if not, the test is skipped with how to fix idb (idb kill; idb connect <udid>), and the run continues to the summary. ui_find, every idb ui tap and the simctl push now have || true, so a failure there becomes this test's result instead of stopping the script. The full e2e suite still passes (83 passed, 1 skipped; the launch-tap test passes).

From the review: under set -e, an idb that cannot reach the simulator made
ui_find (json.load on empty output), a bare idb ui tap or simctl push stop
the whole script, losing the results of phases 1-5. Phase 6 now checks that
idb reaches the simulator (else it is skipped, with how to fix idb), and
every idb and push step is allowed to fail.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@jetbrains-air jetbrains-air Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Everything checks out, so I'm happy to approve — thanks for the quick follow-up! 🎉

@kengoon
kengoon merged commit 76ffb83 into main Nov 12, 2026
4 checks passed
@kengoon
kengoon deleted the feat/notification-launch-tap branch November 12, 2026 12:18
@kengoon kengoon mentioned this pull request Nov 12, 2026
kengoon added a commit that referenced this pull request Nov 12, 2026
Since 0.2.0:
- Firestore: in / not-in / array-contains-any value lists, and the query
  mistakes the SDK would abort the app on, raise ValueError / TypeError (#7, #8)
- Messaging: the notification tap that launches a closed Kivy app reaches
  on_open, with the optional pyios-firebase-notifications-hook package;
  notifications.launch_hook_status() (#12)
- Docs: the app configuration of every product (#11)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant