push notifications (v1)

[knguyenBC]

Description of feature / user story

Notifications require OS level permissions to allow push notifications, alerts, badges etc. The wallet will need a place to request the permission.

Acceptance Criteria

Given the user has NOT been presented the notifications prompt to enable/disable push notifications When they continue from the biometrics enable prompt from onboarding Then they are presented with this Notifications screen And tapping Continue displays the OS notifications prompt

Given the user HAS been presented the notifications prompt to enable/disable push notifications When they tap Notifications from the menu Then they are presented with this Notifications screen and tapping the toggle with change the current state of the notifications

Given the user has enabled/disabled notifications from the OS level When they tap Notifications from the menu Then they are presented with this Notifications screen that informs them of how to change the notifications settings in their device settings

Wireframes or relevant image assets / links

Notifications permissions user flow

updated onboarding flow

updated menu

Tasks

• bcgov/DITP-DevOps#106

• 1729

[jleach]

On hold. Clecio mentioned this may be done via a Code with Us.

[jamshale]

Here is my thoughts on this feature. I would really appreciate any comments, concerns or ideas. I have done work making this work as an agent protocol and think option 1 is the most valid strategy. Although I do have some concerns I outlined in the document.

---

HackMD link --> https://hackmd.io/@GOCrY5e8TOSM65ME5EhgeQ/HkL9dFBi3/edit

---

Option 1 - Integrate with a push notification service and manage push tokens in mediator.

This will target firebase as the push notification service (fcm). Similar work would be required to use apple push notification (apn). Additional, but similar work would be needed to use one signal or expo services.

Description:

Mobile App:

• A firebase project would be created for bc wallet and the service would be integrated into the app. This would use the well maintained library @react-native-firebase/app. Some setup info here https://rnfirebase.io/. This requires loading config information as environment variables at build time.
• Using @react-native-firebase/messaging library. The app would create a background handler for handling notifications when the app is closed. It would create a foreground handler when app is in use. It could ignore the foreground notifications or have a simple toast notification.
• After login the app would get the firebase token and send it to the mediator using the library @aries-framework/push-notifications. Would need some logic for dealing with possible token changes on re-installs.

Mediator Agent:

• A new plugin would be created to handle the push notification (firebase) protocol. There was some work done as an RFC here https://github.com/hyperledger/aries-rfcs/blob/main/features/0734-push-notifications-fcm/README.md. It would be similar to this but the @aries-framework/push-notifications library is a little different. The protocol should match the extension library.
• The mediator agent would save the firebase token in the connection information.
• The plugin would include a service for sending push notifications. It needs to be configured with information from the firebase project and needs a firebase service account which would be loaded as env variables. Here is an example in python https://github.com/firebase/quickstart-python/blob/2c68e7c5020f4dbb072cca4da03dba389fbbe4ec/messaging/messaging.py#L26-L35
• This service could then be triggered from the mediator when messages arive for any connection which has a firebase token.

Benefits:

• Only have to configure the plugin for one agent.
• Can "instantly" notify the wallet user about received messages.

Drawbacks:

• The mediator doesn't know anything about the message. All it can do it send a notification saying something like Your wallet received new information - Please open your wallet. The mobile wallet could then read the messages and route the UI to the correct screen.
  • What if the message isn't important? Will it bother the user to get a push notification and open the app?
• Quite a bit of setup.
  • Need to create an android and ios app in firebase console. Then need to manage and load the google-services.json and GoogleService-Info.plist files at build time securely.
  • Need to create and manage a firebase service account for the plugin and load the json securely at runtime.

Possibilities:

• Could the plugin open another protocol to allow external agents to send push notifications to mobile wallets with detailed information only when specific events happen? This "send" protocol is outlined in rfcs/features/0734.
• Could another agent seperate from mediator be created who's sole purpose was managing push tokens and sending push notifications?

Option 2 - Wake up app on schedule and check for messages

Description:

The idea for this strategy is to have a background task that checks messages on a schedule and opens a local notification if there is message waiting for the user.

This option is left open without the details fully explored. If it's valid more work will be needed to explore the details.

Benefits:

• No need to use a push notification service. Configuration is simpler.
• Can get the decrypted message to add detailed information in the local notification.

Drawbacks:

• Authentication
  • Is it possible to do this securely without the user providing their passcode?
• Notification will be delayed
  • Some use cases may want to notify the user immediately. This wouldn't be possible using this strategy. Background tasks can only be scheduled every 15 mins.
• The app would use more battery. And this would increase with the background process inverval.

[swcurran]

I think the mediator based notification would certainly be welcomed by the community. We will want to do a survey of the community to see what work on this is already underway, and to consider combining this effort with the SocketDock capability introduced by Indicio (https://github.com/hyperledger/aries-socketdock).

[genaris]

As promised through Discord channel, my ARS $0,02 (which definitely worth less than the usual CDN $0,02 @swcurran gives, but it is something 😄) regarding the experience we had so far with Push notifications for DIDComm.

I think the Option 1 you mention is the way to go. Our setup from the Mobile App perspective is the same you are proposing, using React Native Firebase, and it works pretty well in both Android and iOS. We are also recently using @aries-framework/push-notifications, which I plan to update to align with the Aries RFC very soon, so should be ready shortly (next week or so). We are using AFJ also on the mediator side, configured in a way that will send a Push notification to a client which receives a message but does not have any active WebSocket connection (not using aries-socketdock yet but will do soon!)

But I think the most interesting part is about notification handling on the mobile side: we can send remote notifications basically in two ways (naming may vary depending on the platform): normal and silent. The normal notifications are the ones that show a message immediately in the notification bar and allow do a quick action or open the app when tapping on it: this is the kind of notification you are referring when saying "You have new messages". On the other hand, silent notifications do not display a message immediately but open the app in background mode to do anything they want as long as it does not take more than a few seconds: for instance, fetch data from a server and, if anything relevant happened, trigger a local notification (which looks like a regular one, but it is generated within the device).

As you can imagine, considering the drawback you mentioned (mediator does not know anything about messages), it would be ideal to send a silent notification just to trigger the app in background mode, so it connects to the mediator, picks up the messages, process them and, if they are relevant, trigger local notifications with the actual contents of the messages ("proof request from Alice", "Bob says: Hello!!", "connection request from Carol", etc.). This is absolutely possible with FCM and React Native Firebase (with a little help from Notifee) does a great job on launching "JS headless tasks".

However, unfortunately it is not that easy: there are some important concerns that may require do some workarounds, learn more about OS-specific notification management (have you seen that "You may have new messages" from WhatsApp from time to time?) and maybe do further adjustments in the app and the way it handles the data (which might or not might be acceptable depending your use-case):

• In Android, silent notifications arrive instantly in a consistent way, so this approach works pretty well. However, in iOS this kind of notifications are treated as low-priority, and there is no guarantee that they will arrive instantly (in our experience they sometimes do, but may take a few minutes or not arrive at all). Moreover, if the app is killed, it will not receive notifications until the device is restarted. That makes it hard to handle
• Usually, wallets are protected by keys, and you need to input those keys (manually or by user biometrics) in order to unlock them. And you need to do so in order to get the keys to interact with the mediator and read the messages. Hard to do in background. An approach could be to protect the wallet in a way that if the user unlocked the device at least once, the app can access to it in background (not always possible)

BTW, as an alternative to the problem with silent notifications in iOS (which we couldn't solve yet) and trying to answer your question "What if the message isn't important? Will it bother the user to get a push notification and open the app?", an idea that came up was to add somewhere in the protocols (probably in Forward message) a flag to indicate the priority of the message, so mediator will trigger notifications only when it's appropriate. Of course this will make the mediator know something about the message... We could also establish two different DIDComm connections with another party: one for "high priority" messages (relevant to user) and another for "signaling messages" that do not require notifications. This will be cumbersome to implement in clients and probably won't work as expected.

I'm sure I have some other thoughts that I can't remember right now, but will as soon as I find another ARS $0,02 to share 😛.

[jamshale]

Thank you for your input. It is very helpful.

[swcurran]

Great input @genaris — worth way, way more than my $0.02CDN.

I think that @genaris's point about the storage being protected by keys pretty much eliminates the possibility of the silent notifications. If the user doesn’t activate the wallet, then the storage can’t be accessed, and so silent mode is useless. Not to mention that it seems it is unreliable in iOS. Further, given that normal mode is easier, I think it best we use that, and then use in app UX for the notifications new messages that have arrived any time you open the app — because of an OS notification/click to open the app, or just because you opened the app.

It sounds like if we just go normal notifications with a generic message (“You have a message”) it should be “pretty easy” (he says naively), with the trickier part being the UX once the wallet opens and arbitrary messages may have arrived. AFAIK, right now we only have three types of unsolicited DIDComm message types that might arrive while we are offline — a revocation notification, a basic message, and a presentation request from a contact (no QR code needed…). In the future, there will likely be other types of messages not triggered by the Wallet. As well, in theory, the app could go offline between sending a credential request message and getting an issued credential, and restarting the app would pick up the issue message. Figuring out the start up UX to expect one or more arbitrary messages is the tricky part.

[jamshale]

Bifold:

• Load PushNotificationsFcmModule and PushNotificationsApnsModule modules into the agent from @aries-framework/push-notifications

Mobile Wallet Agent:

• Become firebase app for android and ios
• Send device token to mediator
• Set up background and foreground notification handlers
• Notify and route UI according to messages received

Mediator:

• Load firebase plugin with configuration information
• Implement firebase auth token and sending service
• Implement set-device-info protocol
• Save tokens per connection
• Subscribe to acapy::forward::received event
• When receive event and have token tell firebase to send notification
• Don't over send notifications (chat)
• Delete connection/token records when connection deleted

Firebase:

• Set up firebase admin account for bc-wallet
• Create android app and ios in firebase account (google-services.json & GoogleService-Info.plist)
• Setup service account to send notifications from mediator (service-account.json)

Additional Information:

• Notifications cannot display any information to the wallet holder about what messages they received because the mediator doesn't know anything about the message contents.
• Silent notifications aren't a good strategy because the wallet should require login before decrypting and reading mesages.
• The mediator plugin strategy has the benefit of only setting up the firebase service for one acapy instance and many agents can use it.
• If displaying information about the type of message in the notification was really wanted, I think an open endpoint that external agent could use to send push notifications would be better than trying to make silent notifications work securely.

[knguyenBC]

Can the push notification not display the message but if the person were to open the notification and it opens the app, and then person authenticates, could it then take the person to the appropriate connection/contact chat screen or auto open a proof request?

[jamshale]

@knguyenBC I had the same thought and began some work with it but after experimenting with credential and proof request messages it seemed like the app opening on home screen gave the required information in an easy to understand way. The only issue I had was with basic messages (chat) but it sounds like there's work going on with chat notifications on the home screen so I decided not to do anything with routing the UI on startup in the upcoming PR.

[knguyenBC]

With option 1, do we get badges on the app icon itself?

[jamshale]

@knguyenBC There's no way to know who the sender is with the mediator plugin so you wouldn't be able to have icons from the issuing or requesting agent. The icon would be a bc wallet specific icon.

Really option 2 isn't an option anymore. It's insecure.

The only option for getting detailed information would be to have a dedicated agent just for push notification the issuing agents could use. But that adds a lot of complexity and security concerns as well. It might work for some use cases but not when there is several issuers for the same mobile agent.

[knguyenBC]

I meant the notification badges that appear on the app icon itself that designates that you have new messages/new notifications etc. Android, there's a dot and iOS there a red dot with a number indicating the number of messages.

[cvarjao]

@esune , I see that that the push notification code has been merged (hyperledger/aries-mediator-service#93), is it deployed?

[esune]

See this issue for status/tracking: https://github.com/bcgov/DITP-DevOps/issues/106 We still need a Firebase account to configure the plugin: is this something you can spearhead since it will be for the wallet