notif ios: Handle opening of conversation on tap; take 2 #1379

rajveermalviya · 2025-02-26T16:36:09Z

2nd attempt, first attempt was #1261. This one uses pigeon to move most of the notification payload handling to dart side (and doesn't use/rely on zulip://notification URL).

chrisbobbe · 2025-03-12T22:13:22Z

Ah this has gathered a conflict in lib/widgets/app.dart; could you resolve it please? (I see you did a few days ago, but looks like it's happened again; thanks. 🙂)

rajveermalviya · 2025-03-13T22:14:53Z

(Rebased to main, Thanks!)

chrisbobbe

Thanks! There's a lot here, and I haven't gotten around to it all today. But here are some comments from an initial review.

chrisbobbe · 2025-03-18T21:09:38Z

lib/widgets/app.dart

-            GlobalLocalizations.zulipLocalizations = ZulipLocalizations.of(context);
-            return child!;
-          },
+    return DeferrredBuilderWidget(


nit: check spelling (here and in commit message)

(also spelling of _ZulipAppState.initState in the commit message)

chrisbobbe · 2025-03-18T21:22:34Z

lib/widgets/store.dart

-/// Provides access to the app's data.
-///
-/// There should be one of this widget, near the root of the tree.
-///
-/// See also:
-///  * [GlobalStoreWidget.of], to get access to the data.
-///  * [PerAccountStoreWidget], for the user's data associated with a
-///    particular Zulip account.
-class GlobalStoreWidget extends StatefulWidget {
+// This is separate from [GlobalStoreWidget] only because we need
+// a [StatefulWidget] to get hold of the store, and an [InheritedWidget] to
+// provide it to descendants, and one widget can't be both of those.
+class GlobalStoreWidget extends InheritedNotifier<GlobalStore> {


Did you mean to move this implementation comment here and delete the dartdoc? The implementation comment doesn't make sense in this context—saying GlobalStoreWidget is "separate from" GlobalStoreWidget.

chrisbobbe · 2025-03-18T21:38:04Z

test/widgets/content_test.dart

-        child: PerAccountStoreWidget(accountId: eg.selfAccount.id,
-          child: RealmContentNetworkImage(src))));
+      await tester.pumpWidget(DeferrredBuilderWidget(
+        future: ZulipBinding.instance.getGlobalStoreUniquely(),


We normally do this as testBinding.getGlobalStoreUniquely, right?

Also, for these tests that aren't specifically about GlobalStoreWidget, it would be simpler to use TestZulipApp instead, I think.

chrisbobbe · 2025-03-18T22:15:32Z

test/widgets/store_test.dart

+                store: store,
+                child: PerAccountStoreWidget(
+                  accountId: accountId,
+                  child: MyWidgetWithMixin(key: widgetWithMixinKey)));


Maybe we can use TestZulipApp for this test?

Used TestZulipApp in tests where possible, but kept this unchanged because I was getting the same extraneous dep changes mentioned in the above TODO.

chrisbobbe · 2025-03-18T22:51:11Z

lib/notifications/open.dart

+        case TargetPlatform.android:
+        case TargetPlatform.fuchsia:
+        case TargetPlatform.linux:
+        case TargetPlatform.macOS:
+        case TargetPlatform.windows:
+          // Do nothing; we don't offer notifications on these platforms.
+          break;


The comment is wrong about Android; we do offer notifications on Android.

A lot of the code added in this commit is implemented just for iOS, but named/documented as though it's cross-platform, because it doesn't say it's just for iOS.

I don't know if we plan to align the implementation with the names/docs or vice versa. The answer might be in the later commits (I haven't read them yet), but it would be helpful to comment on this in the commit message, I think.

chrisbobbe · 2025-03-18T23:57:21Z

lib/widgets/app.dart

+  List<Route<dynamic>> _handleGenerateInitialRoutesIos(_) {
+    // The `_ZulipAppState.context` lacks the required ancestors. Instead
+    // we use the Navigator which should be available when this callback is
+    // called and it's context should have the required ancestors.


chrisbobbe · 2025-03-19T00:09:59Z

test/notifications/open_test.dart

+      await tester.pump();
+      takeStartingRoutes();
+      matchesNavigation(check(pushedRoutes).single, account, message);
+      debugDefaultTargetPlatformOverride = null;


Hmm, awkward to have this teardown line so far away from its corresponding setup line.

How about instead passing variant: const TargetPlatformVariant({TargetPlatform.iOS})) to testWidgets?

chrisbobbe · 2025-03-19T00:25:50Z

lib/notifications/open.dart

+    final route = _routeForNotification(context, payload);
+    if (route == null) return; // TODO(log)
+
+    // TODO(nav): Better interact with existing nav stack on notif open


Maybe we should have an iOS counterpart to

android: When opening a notification, "back" should not leave the account's context #1210

for this? Or make that a both-platforms issue? That issue says:

(The iOS counterpart is covered by #1147, for navigating at all when a notification is tapped.)

but it seems reasonable to postpone this part of it; we'd just want to keep track of it.

After this PR is merged the potential fix for that issue would work on both platforms, because this PR consolidates the notification routing implementation on both iOS and Android.

chrisbobbe · 2025-03-19T00:26:07Z

pigeon/notifications.dart

+@EventChannelApi()
+abstract class NotificationHostEvents {
+  /// An event stream that emits a notification payload when
+  /// app encounters a notification tap, while the app is runnning.


nit: "the app encounters a notification tap, while the app is running."

chrisbobbe · 2025-03-19T00:28:01Z

test/notifications/open_test.dart

+      await testBinding.globalStore.add(eg.selfAccount, eg.initialSnapshot());
+      await prepare(tester);
+      await checkOpenNotification(tester, eg.selfAccount, eg.streamMessage());
+      debugDefaultTargetPlatformOverride = null;


(same comment about maybe using variant: const TargetPlatformVariant({TargetPlatform.iOS}))

rajveermalviya · 2025-03-20T11:16:58Z

Thanks for the review @chrisbobbe! Pushed a new revision, PTAL.

chrisbobbe

Thanks! Here's a more thorough review of the first four commits:

d1f648c app: Use DeferredBuilderWidget while loading GlobalStore
a5a0fff pigeon [nfc]: Rename pigeon file to notification -> android_notifications
ab3ff84 notif ios: Navigate when app launched from notification
4b2ade0 notif ios: Navigate when app running but in background

That leaves the last two commits:

28ea77f notif android: Migrate to cross-platform Pigeon API for navigation
616defe docs: Document testing push notifications on iOS Simulator

Actually for your next revision, could you send a new PR with everything except the "Migrate to cross-platform" commit? That one's pretty large, so makes sense to review separately.

chrisbobbe · 2025-03-24T23:59:47Z

ios/Runner/Notifications.g.swift

@@ -0,0 +1,167 @@
+// Autogenerated from Pigeon (v24.2.1), do not edit directly.


This needs an update for the Pigeon 25 upgrade e2aac35.

chrisbobbe · 2025-03-25T00:16:59Z

lib/widgets/app.dart

+  /// The widget to build when [future] completes, with it's result
+  /// passed as `result`.


chrisbobbe · 2025-03-25T20:28:55Z

android/app/src/main/kotlin/com/zulip/flutter/AndroidNotifications.g.kt

@@ -381,7 +381,7 @@ data class StoredNotificationSound (
    )
  }
 }
-private open class NotificationsPigeonCodec : StandardMessageCodec() {
+private open class AndroidNotificationsPigeonCodec : StandardMessageCodec() {


Commit-message nit:

pigeon [nfc]: Rename pigeon file to `notification` -> `android_notifications`

I think the "to" should be deleted? Or moved to replace the "->"?

pigeon [nfc]: Rename pigeon file `notifications.dart` to `android_notifications.dart`

commit-message nit: limit summary line length to 76 (this is 85).

chrisbobbe · 2025-03-25T23:31:26Z

pigeon/notifications.dart

+  /// On iOS, this checks and returns value for the `remoteNotification` key
+  /// in the `launchOptions` map. The value could be either the raw APNs data
+  /// dictionary, if the launch of the app was triggered by a notification tap,
+  /// otherwise it will be null.
+  ///
+  /// See: https://developer.apple.com/documentation/uikit/uiapplication/launchoptionskey/remotenotification


Can be a bit more concise I think:

/// Returns `launchOptions.remoteNotification`, /// which is the raw APNs data dictionary /// if the app launch was opened by a notification tap, /// else null. See Apple doc: /// https://developer.apple.com/documentation/uikit/uiapplication/launchoptionskey/remotenotification

And this is only used on iOS at this commit, right; the "On iOS" can be added in the later commit where it also starts being used on Android.

chrisbobbe · 2025-03-26T21:33:48Z

test/model/binding.dart

+  FakeNotificationPigeonApi? _notificationPigeonApi;
+
+  @override
+  FakeNotificationPigeonApi get notificationPigeonApi {
+    return (_notificationPigeonApi ??= FakeNotificationPigeonApi());
+  }


nit: getter before private field: https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md#order-other-class-members-in-a-way-that-makes-sense

Also, can use fewer lines:

@override FakeNotificationPigeonApi get notificationPigeonApi => (_notificationPigeonApi ??= FakeNotificationPigeonApi());

chrisbobbe · 2025-03-27T00:09:55Z

ios/Runner/AppDelegate.swift

+  func onNotificationTapEvent(data: NotificationPayloadForOpen) {
+    if let eventSink = eventSink {
+      eventSink.success(data)
+    }
+  }


Instead of the one class NotificationPayloadForOpen, could we have two separate classes NotificationDataFromLaunch and NotificationTapEvent? Perhaps with a Payload typedef helper:

typedef Payload = Map<Object?, Object?>; class NotificationDataFromLaunch { const NotificationDataFromLaunch({required this.payload}); /// The raw payload that is attached to the notification, /// holding the information required to carry out the navigation. final Payload payload; } class NotificationTapEvent { const NotificationTapEvent({required this.payload}); /// The raw payload that is attached to the notification, /// holding the information required to carry out the navigation. final Payload payload; }

I think the current naming makes the event-channel code harder to read than it needs to be. When reading the Pigeon example code, I see "event" used pretty consistently in the names of things. Here, we have both "data" (onNotificationTapEvent's param) and "payload", and "payload" is used ambiguously for a payload (NotificationPayloadForOpen.payload) and something that contains a payload (NotificationPayloadForOpen itself).

That would mean, for this method:

func onNotificationTapEvent(event: NotificationTapEvent) { if let eventSink = eventSink { eventSink.success(event) } }

chrisbobbe · 2025-03-27T00:18:26Z

pigeon/notifications.dart

+@EventChannelApi()
+abstract class NotificationHostEvents {


Would NotificationEventChannelApi be a better name for this, to make it clearer what kind of thing it is?

chrisbobbe · 2025-03-27T00:28:53Z

lib/model/binding.dart

+// in global scope of the generated file. This is a helper class to
+// namespace the notification related Pigeon API under a single class.
+class NotificationPigeonApi {
+  final _notifInteractionHost = notif_pigeon.NotificationHostApi();


Is _notifInteractionHost the best name for this? How about _hostApi? We might add more to NotificationHostApi that's not about interacting with notifications (such as a method to query the current notification permissions). Also, NotificationHostApi isn't the only code that's about interacting with notifications; notif_pigeon.notificationTapEvents is too.

chrisbobbe · 2025-03-27T00:36:42Z

lib/notifications/open.dart

+  /// Navigates to the [MessageListPage] of the specific conversation
+  /// for the provided payload that was attached while creating the
+  /// notification.
+  Future<void> _navigateForNotification(NotificationPayloadForOpen payload) async {


Another reason the NotificationPayloadForOpen rename would be helpful: currently, it's pretty unclear that this private method is only about notifications that come while the app is open. It'll be helpful for debugging if it's easier to see what code is about the launch notification vs. not.

chrisbobbe · 2025-03-27T00:41:57Z

test/notifications/open_test.dart

+
+    testWidgets('(iOS) stream message', (tester) async {
+      addTearDown(testBinding.reset);
+      await testBinding.globalStore.add(eg.selfAccount, eg.initialSnapshot());


This add-self-account line looks boring; can we put it in prepare?

rajveermalviya · 2025-04-22T11:28:35Z

(Rebased to fix conflicts.)

gnprice

OK, I finally came back and tested out these instructions after the debugging described in that chat thread (from #1379 (comment) ).

This version works great, with one correction below.

Then I also have one high-level comment on the structure (doesn't call for much new text, mostly just moving things around plus a bit of new section-intro text), and a couple of small comments.

My remaining review to-do list for this PR is the other three points in #1379 (review) .

gnprice · 2025-05-07T00:26:15Z

docs/howto/push-notifications-ios-simulator.md

+         user_profile, message, mentioned_user_group_id, mentioned_user_group_name, can_access_sender
+     )
+     logger.info("Sending push notifications to mobile clients for user %s", user_profile_id)
+    logger.info("APNS payload %s", orjson.dumps(apns_payload))


Suggested change

+ logger.info("APNS payload %s", orjson.dumps(apns_payload))

+ logger.info("APNS payload %s", orjson.dumps(apns_payload).decode())

That way it gets printed in the log as verbatim JSON. Otherwise the byte-string gets encoded the way it would be in Python source code, like b'…' — which means that if you try to copy-paste it to use directly, it can get mangled depending on the contents. For example if you send a message whose content is ", you get:
APNS payload: b'{"alert":{"title":"Desdemona","subtitle":"","body":"\\""},"sound":"default","badge":0,"custom":{"zulip":{"server":"192.168.0.113:9991","realm_id":2,"realm_uri":"http://192.168.0.113:9991","realm_url":"http://192.168.0.113:9991","realm_name":"Zulip Dev","user_id":11,"sender_id":9,"sender_email":"[email protected]","time":1746576414,"recipient_type":"private","message_ids":[104]}}}'

with "\\"" , which fails to parse as JSON.

gnprice · 2025-05-07T00:36:23Z

docs/howto/push-notifications-ios-simulator.md

+
+</details>
+
+To receive a notification on the iOS Simulator, we need to push


Now that I've gotten the full instructions working end to end for me and then scanned back through them, I think the structure of what the reader is intended to do here can be expressed more clearly with a bit of reordering:

First, a ## section consisting of the steps from here to the end.

This is the main thing the document is saying to do — everything else is optional, and/or only needs to be done occasionally before then doing this portion many times.

Then, a ## section with the three pre-canned payloads, i.e. the portion of Step 6 above this point.

Then, a third ## section describing how to produce new canned payloads. That consists of Steps 1–5, with each one adjusted to a ###-level section instead of ##-level so that it's a sub-section of this overall section.

Then the structure is: you do what's in the first section. To get input to use in that, you can use either the second section or the third section.

And then in particular the individual steps of the third section don't get labeled as optional; they're all required if you want to produce payloads. So this structure makes that relationship clearer, whereas the individual "optional" labels look as if they're saying one might pick and choose.

gnprice · 2025-05-07T00:36:38Z

docs/howto/push-notifications-ios-simulator.md

+Apple's Push Notification service to show notifications on iOS
+Simulator.
+
+## 1. (Optional) Setup dev server


Suggested change

## 1. (Optional) Setup dev server

## 1. (Optional) Set up dev server

"setup" is a noun, "set up" the verb

gnprice · 2025-05-07T00:39:32Z

docs/howto/push-notifications-ios-simulator.md

+And then follow the steps [here](https://zulip.com/help/mobile-notifications)
+to enable Mobile Notifications for "Channels".
+
+## 3. (Optional) Login to the dev user on zulip-flutter.


Suggested change

## 3. (Optional) Login to the dev user on zulip-flutter.

## 3. (Optional) Log in as the dev user on zulip-flutter.

Similarly "login" is a noun, "log in" the verb.

And as a smaller point: one logs in "to" a server, a realm, or even an account, but logs in "as" a user. The user isn't a space one is entering, but an identity one is taking on.

gnprice

Here's re-review on the Swift changes. The revisions look good; small comments below.

gnprice · 2025-05-07T00:49:59Z

ios/Runner/AppDelegate.swift

+      let listener = notificationTapEventListener!
+      let userInfo = response.notification.request.content.userInfo
+      listener.onNotificationTapEvent(payload: userInfo)


nit: bit simpler with listener inlined

gnprice · 2025-05-07T00:58:36Z

ios/Runner/AppDelegate.swift

+    // Setup handler for notification tap while the app is running.
+    UNUserNotificationCenter.current().delegate = self


nit: "setup" verb/noun

But actually I think this is a comment that can be omitted. In Xcode if you put your cursor on the delegate property that's getting set here, you get this bit of docs:
https://developer.apple.com/documentation/usernotifications/unusernotificationcenter/delegate

Use the delegate object to respond to user-selected actions and to process incoming notifications when your app is in the foreground.

and I think that makes the point just as well as the comment does.

gnprice · 2025-05-07T01:00:26Z

ios/Runner/AppDelegate.swift

+  }
+}
+
+class NotificationTapEventListener: NotificationTapEventsStreamHandler {


Let's include comments somewhere in here with links to the Flutter examples that you found helpful, from the thread #1379 (comment) , since those examples were nontrivial to find.

Here at the top of this class is probably a fine place.

gnprice

OK, and re-reviewed the small commits from early in the branch. Just a couple of small comments below.

With this and the reviews just above, the remaining items for me to review in this PR are, after #1379 (review), down to just:

review the Dart changes in those two main commits at the end of the branch (having covered the Swift changes above).

gnprice · 2025-05-07T01:12:31Z

lib/widgets/dialog.dart

+/// The context argument is used to look up [ZulipLocalizations],
+/// the [Navigator] and [Theme] for the dialog.


I'm not sure how to use this information, when writing or editing a call site of this function. What sort of context does this mean is acceptable or not acceptable?

I believe the main upshot is: this context should be a descendant of the app's main [Navigator]. (That's enough, because the [ZulipLocalizations] and [Theme] are provided by [MaterialApp] and go above the [Navigator].)

Does that cover it? Or are there situations where further guidance beyond that would be helpful?

Also the same information should probably go on showSuggestedActionDialog too, since that's so similar.

gnprice

OK, and started on those two main commits at the end.

I think in this round I've read the first of them:
37683db notif ios: Navigate when app launched from notification

except its tests.

gnprice · 2025-05-07T23:36:08Z

lib/notifications/open.dart

+  /// A [Future] that completes to signal that the initialization of
+  /// [NotificationOpenManager] has completed or errored.
+  Future<void>? get initializationFuture => _initializedSignal?.future;


What's the meaning when this is null?

gnprice · 2025-05-07T23:38:47Z

lib/widgets/app.dart

-          onGenerateInitialRoutes: _handleGenerateInitialRoutes);
+          // TODO migrate Android's handling to the new Pigeon API.
+          onGenerateInitialRoutes: defaultTargetPlatform == TargetPlatform.iOS
+            ? _handleGenerateInitialRoutesIos
+            : _handleGenerateInitialRoutes);


I think it would be somewhat cleaner to push this conditional down into the _handleGenerateInitialRoutes method. The method could consist of just checking this condition and calling one of two methods like _handleGenerateInitialRoutesAndroid and _handleGenerateInitialRoutesIos; pushing the conditional there would mean that this MaterialApp constructor call, which has lots of other things it's dealing with, doesn't get into that detail.

gnprice · 2025-05-07T23:43:30Z

lib/widgets/app.dart

@@ -202,6 +203,31 @@ class _ZulipAppState extends State<ZulipApp> with WidgetsBindingObserver {
    ];
  }

+  List<Route<dynamic>> _handleGenerateInitialRoutesIos(_) {


Re my comment just previous, it actually looks like the old and new methods would share most of their code — the start and end are the same, and only the middle differs. So I'd try making them one method with the conditional just in the middle.

The two sides of that conditional could still be in two separate methods if that seems cleanest — like:

final route = defaultTargetPlatform == TargetPlatform.iOS ? _initialRouteIos() : _initialRouteAndroid(initialRouteStr); if (route != null) { return [ HomePage.buildRoute(accountId: route.accountId), route, ]; }

gnprice · 2025-05-07T23:51:44Z

lib/notifications/open.dart

+/// Service for handling notification navigation.
+class NotificationOpenManager {


I think this doc comment is right — the term "service" fits for this, similar to NotificationService, and unlike NotificationDisplayManager. This is especially so with that listener for notification-tap events, which has this effectively standing ready to act.

So let's name this with "service" instead of "manager", and accordingly rename the init method to start.

gnprice · 2025-05-07T23:53:02Z

lib/notifications/open.dart

+  /// Returns null if app launch wasn't triggered by a notification, or if
+  /// an error occurs while determining the route for the notification, in
+  /// which case an error dialog is also shown.


Suggested change

/// Returns null if app launch wasn't triggered by a notification, or if

/// an error occurs while determining the route for the notification, in

/// which case an error dialog is also shown.

/// Returns null if app launch wasn't triggered by a notification, or if

/// an error occurs while determining the route for the notification.

/// In the latter case an error dialog is also shown.

Otherwise it's ambiguous whether the error dialog applies to both of these cases.

gnprice · 2025-05-07T23:54:24Z

lib/notifications/open.dart

+    unawaited(navigator.push(route));
+  }
+
+  NotificationNavigationData? _tryParsePayload(


nit: may as well have this as its own method when it's first introduced, instead of in the next commit

gnprice · 2025-05-07T23:56:29Z

lib/notifications/open.dart

+    required this.realmUrl,
+    required this.userId,
+    required this.narrow,
+  }) : assert(narrow is TopicNarrow || narrow is DmNarrow);


Perhaps make the type itself be SendableNarrow?

gnprice · 2025-05-07T23:58:09Z

lib/notifications/open.dart

+      final String realmUrl;
+      switch (zulipData) {
+        case {'realm_url': final String value}:
+          realmUrl = value;


This can be more compact as a switch-expression.

gnprice · 2025-05-08T00:03:27Z

lib/notifications/open.dart

+            allRecipientIds: pmUsers
+              .split(',')
+              .map((e) => int.parse(e, radix: 10))
+              .toList(growable: false)..sort(),


nit: the sort is a significant step, so best to keep it visible and not tuck it in:

Suggested change

.toList(growable: false)..sort(),

.toList(growable: false)

..sort(),

gnprice · 2025-05-08T00:13:16Z

lib/notifications/open.dart

+  /// Provides the route to open by parsing the notification payload.
+  ///
+  /// Returns null and shows an error dialog if the associated account is not
+  /// found in the global store.
+  AccountRoute<void>? _routeForNotification(BuildContext context, NotificationNavigationData data) {


It looks like the logic in this method all duplicates most of what's in NotificationDisplayManager.routeForNotification.

It'd be good to avoid duplicating that. Instead, can have a method with this logic (could live on either class), and have NotificationDisplayManager.routeForNotification call that.

This does take its input in a different form, as NotificationNavigationData instead of NotificationOpenPayload. The simplest way to share the logic, starting from this version, would be to have the method that has this logic just take the three fields as separate arguments — since those two classes have the exact same three fields.

It also feels like these two classes are really two ways of describing the same thing, though. How about making fromIosApnsPayload be a new constructor on the NotificationOpenPayload class? The doc comment on that class would change a bit:

/// The information contained in 'zulip://notification/…' internal /// Android intent data URL, used for notification-open flow. class NotificationOpenPayload {

but I think the real point remains the same: it's the data about a notification that describes what to do on opening it.

rajveermalviya · 2025-05-15T18:14:18Z

Thanks for the review @gnprice! Pushed an update, PTAL.

gnprice · 2025-05-16T23:57:30Z

Thanks for the revision!

High-level comment on the main code changes in this revision: this rename commit looks good:
082f95e notif [nfc]: Rename NotificationOpenPayload -> NotificationNavigationData

and the structure of the refactors (along the lines of #1379 (comment)) within the next commit looks good too:
add4f17 notif ios: Navigate when app launched from notification

But that latter commit is harder to read than I'd like it to be, because those refactors (moving a lot of code around) are combined in the same commit with substantial other changes (introducing new logic for iOS). Let's split that into two:

One commit that moves the NotificationNavigationData class and moves/refactors the routeForNotification method, as a pure NFC change. This will create the new file and new NotificationNavigationService class, even though those won't yet do much else. It'll also make the corresponding changes on ZulipApp to follow those moves.
Then one commit that does the rest of the work of the existing commit, including adding the rest of NotificationNavigationService's functionality like start and routeForNotificationFromLaunch.

This is an example of clear and coherent commits. I think each of those new commits will be easier to read once split up than the same changes are as part of the combined commit.

gnprice

OK, and here's a re-review on the changes related to my last three review groups above: the Swift changes #1379 (review); the small commits from early in the branch #1379 (review); and the Dart changes in the first of the two main commits #1379 (review) . Just a handful of small comments from those, below.

Next I'll look at the docs commit, following up on #1379 (review) , and that will complete my re-review.

After you split up that first main commit as described in
#1379 (comment) , I'll be able to read that more completely, followed by the final commit.

gnprice · 2025-05-18T03:24:16Z

lib/widgets/dialog.dart

@@ -49,10 +49,12 @@ class DialogStatus<T> {
 ///
 /// The [DialogStatus.result] field of the return value can be used
 /// for waiting for the dialog to be closed.
+///
+/// The context argument is used to look up the [Navigator] for the dialog.


This is a bit misleading: the context might indeed be used to look that up, but it's also used to look up other things. The reader can see one of those things a few lines below, which casts doubt on the trustworthiness of the whole function's doc.

My suggestion above at #1379 (comment) was a bit different; here it is concretely:

Suggested change

/// The context argument is used to look up the [Navigator] for the dialog.

/// The context argument should be a descendant of the app's main [Navigator].

By being less specific about concrete details (that the caller of this function doesn't need to care about), this version is actually more complete: it covers all the ways the context ends up getting used, because all the ancestors it needs are either the main Navigator or one of its ancestors.

gnprice · 2025-05-18T03:27:44Z

lib/widgets/app.dart

+        ? _initialRouteIos(context)
+        : _initialRouteAndroid(context, initialRoute);
+    if (route != null) {
+      return [HomePage.buildRoute(accountId: route.accountId), route];


nit: I think keeping this list vertically expanded (like it is in main) is helpful for keeping both of the routes visually salient. Similar to how the children of Row and Column widgets almost always get listed on separate lines.

gnprice · 2025-05-18T03:32:35Z

lib/notifications/navigate.dart

+  }
+}
+
+class NotificationNavigationData {


Let's give this class a bit of dartdoc to say what it's intended to mean, like the old NotificationOpenPayload had. Like this (cf #1379 (comment)):

Suggested change

class NotificationNavigationData {

/// The data from a notification that describes what to do

/// when the user opens the notification.

class NotificationNavigationData {

gnprice · 2025-05-18T03:34:24Z

lib/notifications/navigate.dart

+/// Service for handling notification navigation.
+class NotificationNavigationService {


What's your thinking behind naming this class and this file with "navigate", rather than "open" as in the previous revision?

(Either name seems plausible to me; but I'm curious to hear what shifted your thinking to cause you to rename it.)

I just thought that this class should match the naming with NotificationNavigationData, so changed both to "navigate".

Cool, thanks. Let's name them NotificationOpenService and open.dart, like in that previous revision.

That makes the scope a bit more general: they're not only about navigating in a way related to a notification, but more generally about whatever we might do on opening a notification.

Those concepts might coincide for now, but I expect they won't always: for example, we might want to take you directly to the relevant message in history, rather than to the first unread or the newest message. (Maybe it was an @-mention in the middle of a long-running conversation that you weren't previously reading.) That's a further detail of opening the notification that isn't about navigation, because it doesn't change what page you're on compared to just going to the default start point in the conversation.

And then I think we'd want that logic to live together with the logic that's here in this version. In particular this logic is really more about how to interpret the data we get from the notification than it is about how to navigate.

Another angle on that is that the dartdoc in this version is kind of tautological — cf https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#avoid-useless-documentation or https://dart.dev/effective-dart/documentation#avoid-redundancy-with-the-surrounding-context . I tried thinking of a better summary line to write, and didn't come up with anything great — in particular, how does the navigation relate to the notification?

The answer to that is basically that the navigation is for opening the notification. So we can make that the core concept of what the class is. And then the doc can say:

/// Responds to the user opening a notification.

(Re NotificationNavigationData, we'll probably want that to end up covering the more general "open" concept too: in particular we'll need the message ID from the notification, and that will naturally become another field on that class. That more general concept is reflected in the name of the existing NotificationOpenPayload, and in the dartdoc this version has which I supplied at #1379 (comment) above.)

gnprice · 2025-05-18T04:26:15Z

OK, and the docs changes generally all look good. I think my remaining comments on the doc are all best expressed by just making the edits — so I've pushed an additional commit to the branch:

commit 5df6033
Author: Greg Price [email protected]
Date: Sat May 17 21:20:02 2025 -0700

docs: Clarify and expand a few spots in the iOS simulator notif doc

Also make use of a handy shorthand within `jq`.

Let's leave that unsquashed, but reorder it to just after the commit that introduces the doc.

Then the remaining steps are as described in my review just above: #1379 (review)

…art` This makes it clear that these bindings are for Android only.

And fix a typo.

Also make use of a handy shorthand within `jq`.

…Data And rename it's methods to be clear that they are Android only.

And move the notification navigation data parsing utilities to the new class.

Introduces a new Pigeon API file, and adds the corresponding bindings in Swift. Unlike the `pigeon/android_notifications.dart` API this doesn't use the ZulipPlugin hack, as that is only needed when we want the Pigeon functions to be available inside a background isolate (see doc in `zulip_plugin/pubspec.yaml`). Since the notification tap will trigger an app launch first (if not running already) anyway, we can be sure that these new functions won't be running on a Dart background isolate, thus not needing the ZulipPlugin hack.

rajveermalviya · 2025-05-20T14:38:04Z

Thanks for the review @gnprice! Pushed a new revision, PTAL.

gnprice

Thanks for splitting up that commit! That was very helpful for my reading those changes. Here's a full review of the resulting two commits:
80a89e3 notif [nfc]: Introduce NotificationNavigationServer
b8cfff7 notif ios: Navigate when app launched from notification

except the tests.

I'll take a look at those tests next. Then the remaining to-do list for review will be the final commit:
1c03950 notif ios: Navigate when app running but in background

gnprice · 2025-05-21T01:22:20Z

lib/notifications/navigate.dart

+  /// The context argument is used to look up the [Navigator], which is used
+  /// to show an error dialog if there is a failure.
+  AccountRoute<void>? routeForNotificationFromLaunch({required BuildContext context}) {


similar to #1379 (comment)

gnprice · 2025-05-21T01:36:48Z

lib/widgets/app.dart

+    } else {
+      // The account didn't match any existing accounts,
+      // fall through to show the default route below.


This comment doesn't seem accurate. This condition will indeed occur if the data for the initial route specified an account which didn't match any existing accounts… but it will also occur if the data for the initial route didn't specify any account at all.

In particular I believe this condition will occur every time the app is launched other than by opening a notification.

gnprice · 2025-05-21T01:37:27Z

lib/widgets/app.dart

          onGenerateRoute: (_) => null,
-
          onGenerateInitialRoutes: _handleGenerateInitialRoutes);


nit: stray diff hunk

gnprice · 2025-05-21T01:45:49Z

lib/notifications/navigate.dart

+    try {
+      return NotificationNavigationData.parseAndroidNotificationUrl(url);
+    } on FormatException catch (e, st) {
+      assert(debugLog('$e\n$st'));
+      final zulipLocalizations = ZulipLocalizations.of(context);
+      showErrorDialog(context: context,
+        title: zulipLocalizations.errorNotificationOpenTitle);


notif [nfc]: Introduce NotificationNavigationServer And move the notification navigation data parsing utilities to the new class.

This change doesn't look like it's NFC (see definition). If the URL doesn't parse, the old code would throw (because it called parseAndroidNotificationUrl directly); this version will instead pop up an error dialog.

The dialog seems like a fine change. That change should go in a different commit, though (either before or after). The great value of the NFC concept is that knowing a given commit is supposed to be NFC can help make it a lot simpler to read: all the logic in the red - parts of the diff will match up, not necessarily textually but semantically, with logic in the green + parts of the same diff. The reader can therefore mentally cross off all the bits that match up, aiming to get to zero.

gnprice · 2025-05-21T01:49:10Z

lib/widgets/app.dart

-    final route = _initialRouteAndroid(context, initialRoute);
+    final route = defaultTargetPlatform == TargetPlatform.iOS
+        ? _initialRouteIos(context)
+        : _initialRouteAndroid(context, initialRoute);


I like this diff hunk — it expresses pretty crisply the fact that before this change, we didn't respond to an initial route on iOS (only on Android), and after this change, we do.

gnprice · 2025-05-21T02:03:57Z

lib/notifications/navigate.dart

+  /// A [Future] that completes to signal that the initialization of
+  /// [NotificationNavigationService] has completed or errored.
+  ///
+  /// Returns null if [start] wasn't called yet.
+  Future<void>? get initializationFuture => _initializedSignal?.future;


In Future terminology, "complete" includes both success and failure. See e.g. [Future.whenComplete].

Suggested change

/// A [Future] that completes to signal that the initialization of

/// [NotificationNavigationService] has completed or errored.

///

/// Returns null if [start] wasn't called yet.

Future<void>? get initializationFuture => _initializedSignal?.future;

/// A [Future] that completes to signal that the initialization of

/// [NotificationNavigationService] has completed

/// (with either success or failure).

///

/// Null if [start] hasn't been called.

Future<void>? get initializationFuture => _initializedSignal?.future;

(also includes nit: omit "returns" for describing getter; a getter impersonates a field, so it just "is" its value; and "wasn't" doesn't sound right to me tense-wise)

For the name, how about just initialized? It's common for things of type Future to have names that describe the future's result, letting the type speak for the fact that it's a future.

gnprice · 2025-05-21T03:09:00Z

lib/notifications/navigate.dart

+/// Service for handling notification navigation.
+class NotificationNavigationService {


(Re NotificationNavigationData, we'll probably want that to end up covering the more general "open" concept too: in particular we'll need the message ID from the notification, and that will naturally become another field on that class. That more general concept is reflected in the name of the existing NotificationOpenPayload, and in the dartdoc this version has which I supplied at #1379 (comment) above.)

gnprice · 2025-05-21T03:11:00Z

lib/notifications/navigate.dart

+    unawaited(navigator.push(route));
+  }
+
+  NotificationNavigationData? _tryParseIosApnsPayload(


Can this be static? Seems similar to tryParseAndroidNotificationUrl just below it.

gnprice · 2025-05-21T03:13:01Z

lib/notifications/navigate.dart

+    assert(context.mounted);
+    if (!context.mounted) return; // TODO(linter): this is impossible as there's no actual async gap, but the use_build_context_synchronously lint doesn't see that
+
+    final notifNavData = _tryParseIosApnsPayload(context, event.payload);


Looks like this _navigateForNotification method should get an assert that the platform is iOS, to clarify why this line makes sense.

gnprice · 2025-05-21T03:14:28Z

lib/notifications/navigate.dart

+  /// Navigates to the [MessageListPage] of the specific conversation
+  /// for the provided payload that was attached while creating the
+  /// notification.
+  Future<void> _navigateForNotification(NotificationTapEvent event) async {


Can this method be static? Doesn't look like it's using any instance data.

gnprice

OK, and here's a review on the tests in that next-to-last commit:
b8cfff7 notif ios: Navigate when app launched from notification

I think some of the changes requested here will help make those tests easier to read and understand, so for this round I haven't yet read every line.

gnprice · 2025-05-21T03:20:13Z

test/model/store_test.dart

-      addTearDown(NotificationService.debugReset);
      testBinding.packageInfoResult = eg.packageInfo(packageName: 'com.zulip.flutter');
+      addTearDown(NotificationService.debugReset);
+      addTearDown(NotificationNavigationService.debugReset);
      await NotificationService.instance.start();


Hmm yeah, good thought reordering these while you're here editing them.

gnprice · 2025-05-21T03:22:35Z

test/notifications/display_test.dart

    addTearDown(NotificationService.debugReset);
+    addTearDown(NotificationNavigationService.debugReset);


It'd be good if we can avoid going and adding another detail like this that tests have to know about.

How about having NotificationService.debugReset call the new service's debugReset? Seems appropriate for the main service to take responsibility for resetting the new one, given that the main service is also the one place responsible for starting up the new service.

gnprice · 2025-05-21T03:25:15Z

test/notifications/navigate_test.dart

+
+  Future<void> init() async {
+    addTearDown(testBinding.reset);
+    testBinding.firebaseMessagingInitialToken = '012abc';


Is this line needed? I'd think this data wouldn't be involved in any of these tests.

gnprice · 2025-05-21T03:28:15Z

test/notifications/display_test.dart

-  group('NotificationOpenPayload', () {
+  group('NotificationNavigationData', () {


Since the code this is testing is getting moved between files, the tests should move to remain in a corresponding file.

gnprice · 2025-05-21T03:38:33Z

lib/notifications/navigate.dart

+
+  /// Parses the iOS APNs payload and retrieves the information
+  /// required for navigation.
+  factory NotificationNavigationData.fromIosApnsPayload(Map<Object?, Object?> payload) {


Hmm, does this function have tests? I don't see them. (I do see a variety of test cases for the logic downstream of here, which is good.)

This logic is fairly densely packed with fiddly details, like parsing logic tends to be, so it's logic that's valuable to have good tests for. And, again typically for parsing logic, it has a pretty crisp interface for both input and output, which makes it nicely amenable to writing plenty of unit tests. So let's go ahead and do that.

For a point of comparison, see the existing tests of NotificationOpenPayload in display_test.dart.

gnprice · 2025-05-21T03:41:28Z

test/notifications/navigate_test.dart

+      matchesNavigation(check(pushedRoutes).single, eg.selfAccount, message);
+    }, variant: const TargetPlatformVariant({TargetPlatform.iOS}));
+
+    testWidgets('(iOS) uses associated account as initial account; if initial route', (tester) async {


I don't understand what a ";" means here.

gnprice · 2025-05-21T03:48:40Z

test/notifications/navigate_test.dart

+      // Set up a value for `PlatformDispatcher.defaultRouteName` to return,
+      // for determining the initial route.
+      final message = eg.streamMessage();
+      final payload = messageApnsPayload(message, account: eg.selfAccount);
+      testBinding.notificationPigeonApi.setNotificationDataFromLaunch(
+        NotificationDataFromLaunch(payload: payload));


Is this comment accurate? I don't see anything about PlatformDispatcher.defaultRouteName here.

It looks like this test case is copied from an existing one in display_test.dart. But that one says:

// Set up a value for `PlatformDispatcher.defaultRouteName` to return, // for determining the initial route. final account = eg.selfAccount; final message = eg.streamMessage(); final data = messageFcmMessage(message, account: account); final intentDataUrl = NotificationNavigationData( /* … */).buildAndroidNotificationUrl(); addTearDown(tester.binding.platformDispatcher.clearDefaultRouteNameTestValue); tester.binding.platformDispatcher.defaultRouteNameTestValue = intentDataUrl.toString();

so PlatformDispatcher.defaultRouteName really is what it's about.

gnprice · 2025-05-21T03:53:48Z

test/notifications/display_test.dart

      final account = eg.selfAccount;
      final message = eg.streamMessage();
      final data = messageFcmMessage(message, account: account);
-      final intentDataUrl = NotificationOpenPayload(
+      final intentDataUrl = NotificationNavigationData(


Speaking of this test, it looks like it (and several of its neighbors) should also move to navigate_test.dart / open_test.dart as part of the code-moving commit — the code they're testing is part of what's getting moved.

(In particular the way these tests exercise the code they're testing is via ZulipApp — and the relevant call sites in ZulipApp switch from NotificationDisplayManager methods to NotificationNavigationService methods.)

As a bonus, those moves may allow you to outright move some of the helpers from this test file, rather than copy them as the current version does.

gnprice · 2025-05-21T03:56:58Z

lib/notifications/display.dart

-    final route = routeForNotification(context: context, url: url);
+    assert(url.scheme == 'zulip' && url.host == 'notification');
+    final payload =
+      NotificationNavigationService.tryParseAndroidNotificationUrl(context, url);


This navigateForNotification method seems like it should move too — it's logically closely related to the other methods like routeForNotification which are moving.

It's also quite similar to the _navigateForNotification method which the last commit introduces on the other class. It might be fine to have some code duplication between these two methods — but if we do that, it's definitely better if they're right next to each other, so that the parallelism is more visible.

rajveermalviya force-pushed the dev-ios-notif-2 branch 5 times, most recently from 463b9ee to 8478226 Compare March 6, 2025 14:53

rajveermalviya marked this pull request as ready for review March 6, 2025 14:54

rajveermalviya force-pushed the dev-ios-notif-2 branch 2 times, most recently from 0142dbd to 89df63b Compare March 6, 2025 17:29

rajveermalviya mentioned this pull request Mar 6, 2025

notif ios: Handle opening of conversation on tap #1261

Closed

rajveermalviya force-pushed the dev-ios-notif-2 branch from 89df63b to 4f3224a Compare March 10, 2025 11:09

rajveermalviya added the maintainer review PR ready for review by Zulip maintainers label Mar 10, 2025

rajveermalviya assigned chrisbobbe Mar 10, 2025

rajveermalviya requested a review from chrisbobbe March 10, 2025 11:09

rajveermalviya force-pushed the dev-ios-notif-2 branch 2 times, most recently from 80a34eb to 9c07740 Compare March 10, 2025 18:37

rajveermalviya force-pushed the dev-ios-notif-2 branch 3 times, most recently from 3b50218 to 2178fe6 Compare March 13, 2025 22:07

chrisbobbe reviewed Mar 19, 2025

View reviewed changes

rajveermalviya force-pushed the dev-ios-notif-2 branch from 2178fe6 to 616defe Compare March 20, 2025 10:58

rajveermalviya requested a review from chrisbobbe March 20, 2025 11:17

gnprice mentioned this pull request Mar 25, 2025

notif: Ignore notifications for logged out accounts #1349

Merged

chrisbobbe reviewed Mar 27, 2025

View reviewed changes

rajveermalviya mentioned this pull request Mar 27, 2025

ios build: Take auto updates to Podfile.lock and an Xcode file #1444

Merged

gnprice mentioned this pull request Mar 27, 2025

Run iOS build in CI #773

Open

rajveermalviya force-pushed the dev-ios-notif-2 branch 2 times, most recently from 173f11f to 9813a4d Compare March 27, 2025 19:32

rajveermalviya force-pushed the dev-ios-notif-2 branch from 07290de to c4cad8f Compare April 22, 2025 11:28

rajveermalviya force-pushed the dev-ios-notif-2 branch from c4cad8f to 7ba7cc4 Compare April 22, 2025 11:59

gnprice reviewed May 7, 2025

View reviewed changes

gnprice reviewed May 8, 2025

View reviewed changes

rajveermalviya force-pushed the dev-ios-notif-2 branch 2 times, most recently from f7c0a46 to 865341e Compare May 15, 2025 16:51

rajveermalviya requested a review from gnprice May 15, 2025 18:14

gnprice reviewed May 18, 2025

View reviewed changes

rajveermalviya and others added 9 commits May 20, 2025 18:09

pigeon [nfc]: Rename notifications.dart to `android_notifications.d…

029d4a5

…art` This makes it clear that these bindings are for Android only.

dialog [nfc]: Document required ancestors for BuildContext

e59e47a

And fix a typo.

notif: Fix error message when account not found in store

8b1d409

binding test [nfc]: Reorder androidNotificationHost getter

1aad36e

docs: Document testing push notifications on iOS Simulator

21d8c6e

docs: Clarify and expand a few spots in the iOS simulator notif doc

9198792

Also make use of a handy shorthand within `jq`.

store: Add "blocking future" option on GlobalStoreWidget

346069a

notif [nfc]: Rename NotificationOpenPayload -> NotificationNavigation…

1f5e518

…Data And rename it's methods to be clear that they are Android only.

notif [nfc]: Introduce NotificationNavigationServer

80a89e3

And move the notification navigation data parsing utilities to the new class.

rajveermalviya force-pushed the dev-ios-notif-2 branch from 5df6033 to 920ee7a Compare May 20, 2025 13:52

rajveermalviya added 2 commits May 20, 2025 19:56

notif ios: Navigate when app running but in background

1c03950

rajveermalviya force-pushed the dev-ios-notif-2 branch from 920ee7a to 1c03950 Compare May 20, 2025 14:27

gnprice reviewed May 21, 2025

View reviewed changes

		@@ -0,0 +1,167 @@
		// Autogenerated from Pigeon (v24.2.1), do not edit directly.

		/// The widget to build when [future] completes, with it's result
		/// passed as `result`.

	+ logger.info("APNS payload %s", orjson.dumps(apns_payload))
	+ logger.info("APNS payload %s", orjson.dumps(apns_payload).decode())


		</details>

		To receive a notification on the iOS Simulator, we need to push

	## 1. (Optional) Setup dev server
	## 1. (Optional) Set up dev server

	## 3. (Optional) Login to the dev user on zulip-flutter.
	## 3. (Optional) Log in as the dev user on zulip-flutter.

		// Setup handler for notification tap while the app is running.
		UNUserNotificationCenter.current().delegate = self

		/// The context argument is used to look up [ZulipLocalizations],
		/// the [Navigator] and [Theme] for the dialog.

		/// Service for handling notification navigation.
		class NotificationOpenManager {

	.toList(growable: false)..sort(),
	.toList(growable: false)
	..sort(),

		@EventChannelApi()
		abstract class NotificationHostEvents {

	/// The context argument is used to look up the [Navigator] for the dialog.
	/// The context argument should be a descendant of the app's main [Navigator].

		/// Service for handling notification navigation.
		class NotificationNavigationService {

		onGenerateRoute: (_) => null,

		onGenerateInitialRoutes: _handleGenerateInitialRoutes);

		addTearDown(NotificationService.debugReset);
		addTearDown(NotificationNavigationService.debugReset);

		group('NotificationOpenPayload', () {
		group('NotificationNavigationData', () {

notif ios: Handle opening of conversation on tap; take 2 #1379

Are you sure you want to change the base?

notif ios: Handle opening of conversation on tap; take 2 #1379

Conversation

rajveermalviya commented Feb 26, 2025 • edited by gnprice Loading

chrisbobbe commented Mar 12, 2025

rajveermalviya commented Mar 13, 2025

chrisbobbe left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rajveermalviya commented Mar 20, 2025

chrisbobbe left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chrisbobbe Mar 27, 2025 • edited Loading

Choose a reason for hiding this comment

rajveermalviya commented Apr 22, 2025

gnprice left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gnprice left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gnprice left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gnprice left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rajveermalviya commented May 15, 2025

gnprice commented May 16, 2025 • edited Loading

gnprice left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gnprice commented May 18, 2025

rajveermalviya commented Feb 26, 2025 •

edited by gnprice

Loading

chrisbobbe left a comment •

edited

Loading

chrisbobbe Mar 27, 2025 •

edited

Loading

gnprice commented May 16, 2025 •

edited

Loading