Push Notifications API Design

[proneon267]

So, here is my preliminary API for push notification widget:

Toga.App.send_push_notification(title, text, timer, on_press)

It is very simple and doesn't give much customization options. This because I am not sure whether all the platforms do support these customization. Like for example, in macos, I have read that it doesn't allow you to change the notification icon. But other platforms do allow it. So the question arises, can we provide these customization options uniformly?

Further, it also doesn't check whether the notification sent was successful or not. There maybe cases where the notification will not be shown like in Do not distrub mode is on, or notifications are disabled. But, in each of these cases these settings are set by the user according to their preferences.

If we allow the app developers to know if the notification was sent successfully or if the app has the permission to sent notifications, then I fear these options would be misused. The situation would turn like the situation of websites and adblockers where the websites refuse to work if the notification permission is not given. What if the apps do something similar?

Notifications should act as supplementary to an app. I mean they should not solely depend on the notification to display progress or related things.

Anyways, can you give names of the API that you would want to be implemented?

[freakboy3742]

I haven't got any ideas for API names - because I haven't done any research on the topic. However ... it appears that you haven't either (something that you say explicitly - "I'm not sure if all platform support this customisation")

Without even leaving this project, there is an open ticket that contains at some research and design suggestions: #907.

That discussion also addresses one of the biggest issues with what you've described here - the name of what you're suggesting. You've called this a "push notification". A push notification is server initiated. The server "pushes" a notification. If Toga had an API to send a push notification, the user wouldn't see anything (unless they were pushing a notification that was addressed to themselves somehow). As with that older ticket, I suspect what you actually mean is a popup notification, sometimes called a toast (because it pops up like cooked toast from a toaster).

The first step on any new feature proposal is to do platform research. That's why I pointed you at Dan's blog post and video - the first step was to research the capabilities of the new widget he wanted to implement. We're not going to commit to an API design until we have a reasonable degree of confidence that it can be implemented on every platform that Toga supports.

[proneon267]

I agree with you. I'll check what I can find and keep you updated.

[proneon267]

Nomenclature

Researching on the topic, I found distinction between the different notifications:

• Push Notification: Web server pushed notification.
• Toast Notification: In-app notification:

• User Facing Non in-app notification:

On Windows:

On GTK:

On MacOS:

This API design focuses on User Facing Non in-app notifications

Windows seems to use the nomenclature of "toast" notification. But, gtk differentiates between in-app(toast) notification and desktop notfication.

Calling them desktop notification would be good but on mobile platforms, it would not be very logical sounding. Hence, we can call them app notifications would be better.

The major components of a desktop notfication seems to be:

• App Icon
• App Name
• Title
• Text Body
• Notification Icon
• Buttons(Apple HIG specifies maximum of 4 buttons are allowed.) or other widgets
• Urgency of the notification
• Permission to send notification
• Timeout to show notification
• "on_press" like event which is triggered when the body of the notification is clicked(not the notification buttons).

All platforms have a notification center to display all the notifications from different apps.

On platforms like Apple, Notification Icon is not changeable. Timeout is also not changeable on some of the platforms. App icon and App Name will remain constant and cannot & should not be changed.

Urgency of the notification determines whether a sound will be played or should the notification be silently displayed in the notification center.

[proneon267]

I am proposing that we have a Notification urgency option, that will have: Low, Normal, Critical options with each mapped to the behavior of the native platform notification.

I'll write a preliminary API for the features described so far and let you know.

[proneon267]

Toga.App.send_notification(title, text, timer, priority, on_press)

• title - title of the notification.
• text - body text of the notification.
• timer - short lived won't disapper long lived - Not actual API values, just pseudo values.
• priority - Low Normal Critical
• on_press - takes the function to call when the body of the notification is clicked.
• additional_widgets_box - takes a Toga.Box containing the widgets to be displayed on the notfication - Will not be included in the first iteration of the notifcation design.

I think the timer and priority parameters have overlapping goals. If a notification is Low priority, it should be short lived and if it is Critical then it should be won't disappear.

@freakboy3742 please take a look at this and let me know.

[freakboy3742]

Toga.App.send_notification(title, text, timer, priority, on_press)

"Send" implies it's going somewhere; I'd prefer show_notification(), since it's a lot more "local" as terminology.

• title - title of the notification.
• text - body text of the notification.
• timer - short lived won't disapper long lived - Not actual API values, just pseudo values.

Timer implies there's a configurable duration. Something like transient = True/False or persistent=False/True would make more sense to me.

• priority - Low Normal Critical
• on_press - takes the function to call when the body of the notification is clicked.
• additional_widgets_box - takes a Toga.Box containing the widgets to be displayed on the notfication - Will not be included in the first iteration of the notifcation design.

Not sure this will be viable as a design, but since it's not in this iteration, I guess it doesn't matter at this stage.

I think the timer and priority parameters have overlapping goals. If a notification is Low priority, it should be short lived and if it is Critical then it should be won't disappear.

If they're overlapping, why define both? What's the implementation if priority=Critical, timer=short lived or priority=Low, timer=won't disappear?

@freakboy3742 please take a look at this and let me know.

There's no need to ping me every time you want a response. Firstly, it implies nobody else is welcome to respond; secondly, I get notified of every post in every BeeWare forum. The only reason to tag me specifically is if (a) there is some reason that my input specifically is required, and I haven't been involved in the discussion to date, or (b) you've posted something needing a response and haven't received one for a couple of days (allowing for weekends, etc when someone may not be able to post).

[proneon267]

"Send" implies it's going somewhere; I'd prefer show_notification(), since it's a lot more "local" as terminology.

I agree.

Timer implies there's a configurable duration. Something like transient = True/False or persistent=False/True would make more sense to me.

I agree.

If they're overlapping, why define both? What's the implementation if priority=Critical, timer=short lived or priority=Low, timer=won't disappear?

I meant which one of the following: priority and timer should be keep, since they are overlapping. For example, a critical notification should be won't disappear.

There's no need to ping me every time you want a response. Firstly, it implies nobody else is welcome to respond; secondly, I get notified of every post in every BeeWare forum. The only reason to tag me specifically is if (a) there is some reason that my input specifically is required, and I haven't been involved in the discussion to date, or (b) you've posted something needing a response and haven't received one for a couple of days (allowing for weekends, etc when someone may not be able to post).

Won't happen again :)

[freakboy3742]

If they're overlapping, why define both? What's the implementation if priority=Critical, timer=short lived or priority=Low, timer=won't disappear?

I meant which one of the following: priority and timer should be keep, since they are overlapping. For example, a critical notification should be won't disappear.

Ah - I didn't read what you'd written as a question. If that's the case, I'd say "priority" is the option that makes more sense - it's a "higher level" concept that is required on the native APIs anyway, and the implied mapping to notification persistence makes sense.

[NickVanelli]

friend, I have the same goal, can you give me some form of contact with you so that we can talk about our projects?

[annunal]

Is there any news about this subject ? It seems stopping at June 2023; was a solution found in the meantime ?

[freakboy3742]

No, there hasn't been any further work on this proposal since the last update in May. We're still interested in adding it, but it's not on the short-term roadmap of the core team.