Ubuntu Wiki

bla fasel foo bar

#title Ubuntu Touch 3rd-party developer-guidelines for Notifications

Rationale

The notification-system used on a unity7-based Ubuntu desktop is not ideal for devices such as smartphones and tablets running UbuntuTouch, which does not use the usual windowing-concept and are rather operated via touch than a mouse. Still there is the requirement for applications and services, running on these devices, to be able provide small pieces of information to the user or ask the user a simple yes/no-question outside the context of said applications or services. The new notification-system in unity8 does provide the needed functionality for UbuntuTouch.

Differences to desktop-notifications

The intentional differences of UbuntuTouch notifications when compared to the NotifyOSD-based desktop-notifications are - apart from their visual apperance - the lack of the click-through property and the missing fade-on-hover behaviour of notifications.

Use-cases

To give a better understanding of situations, when the use of a notification under UbuntuTouch is recommended, we provide a list of some typical use-cases.

• incoming phone-call: The user has the web-browser focused on his/her smartphone and is receiving a phone-call. Since the telephony-app is not open a so called snap-decision notification (see below details) pops up at the top of the screen, above the browser, displaying some contact-information of the caller (like avatar-photo, name and phone-number if present in the address-book) and two buttons allowing the user to either accept and pick up the call or reject it.
• received text-message: While the user is searching for some songs in the music-scope he/she is receiving a sms text-message from a friend. Without the messaging-app open a special interactive notification (see below for details) pops up at the top of the screen, above the music-scope, showing the sender's avatar-photo and name, if present in the address-book, along with the message-text itself as the body of the interactive notification. The secondary icon - at the top right to the avatar-photo - indicates what kind of messaging-system the text-message was send over. This could be via regular SMS indicated by an envelope-icon, the facebook-logo if it's was a personal chat-message by one of the user's facebook-friends and so on. The whole interactive notification acts as a button, so the user can just tap anywhere on the interactive notification to bring the responsible messaging-application to the front in order to reply right away.
• alarm/reminder: During some game the user is playing to pass some time while on a bus-ride, a scheduled reminder-alarm is triggered by the calendar. This opens a snap-decision notification (see below for details) displaying a clock-icon as a visual clue to the user, that this is a reminder-alarm, a summary-text describing the reminder and a body-text with further details the user might have added when the reminder was set in the calendar in the past. Two buttons at the bottom of the snap-decision notification allow the user to either accknowledge the alarm or be reminded again in 5 minutes.
• upload completed: The user triggered a lengthly upload of some photos to an image-sharing service and brought a rss-reader application to to the front. Once the upload-process is completed, the image-sharing client-app triggers an ephemeral notification with a very short text-message indicating that the upload finished.

Notification Types

There are three distinct types of notifications on UbuntuTouch. Ephemeral notifications, which are also found on the unity7-based desktop, interactive notifications and snap-decision notifications. The latter two notification-types are new and introduced first with UbuntuTouch.

• Ephemeral notifications are of medium impact on the users work-flow, but do disruptive it. Typical use-cases for ephemeral notifications are for example the need to inform the user of completed time-consuming background-processes like file-uploads/downloads.
  • - looks - behaviour/timeout

* Interactive notifications have a high impact on the users work-flow and are disruptive. They allow the user to switch to the triggering application from where ever they are currently. Or trigger any other action the issuing applications seems fitting. Typical use-cases are giving the user a direct path to reply to an incoming private chat- or text-message being received.

• - looks - behaviour/timeout

• snap-decision high impact, disruptive
  • - typical use-cases: incoming call, file-transfer request, date-reminders - looks - behaviour/timeout

Look, Behaviour

Hints

The hint-system used by UbuntuTouch notifications covers two roles. Firstly it allows the notification-daemon to expose supported functionality to an application and secondly it is a means for the application to provide additional information about the notification to trigger to the daemon.

It is recommended practise to query the notification-daemon regarding a specific hint before using it. Do not just assume the support of a hint your going to use and do not write code that crashes, if a hint is not supported!

You might see source-code using hints starting with "x-canonical-private-...". These hints are reserved for system-only services, can change without prior notice and are not guaranteed to be supported for life-cycle of a LTS release. Do not write code based on those hints!

• "actions"
• "body"
• "body-markup"
• "icon-static"
• "image/svg+xml"
• "urgency"
• "x-canonical-snap-decisions" (implies "actions")
• "x-canonical-switch-to-application"
• "x-canonical-secondary-icon"
• "x-canonical-non-shaped-icon"
• "x-canonical-truncation"
• "x-canonical-append"

Code-Examples/Videos

Like the desktop-notifications UbuntuTouch-notifications uses libnotify to trigger a notification. Thus notifications can be triggered from any language a libnotify-binding exists for. The most popular are the C/C++- and Python-bindings. QML-bindings do not exist yet. The notification-daemon, which receives and handles all notifications, will allow only one notification per application in queue at a time. Should an application try to trigger another notification, if it still has one in the queue, it will be rejected and not added to the queue.

• ephemeral

  • append-hint example / video

  • icon-summary layout example / video

  • summary-only layout example / video

  • dynamically updating notifications / video

  • non-shaped-icon hint example / video

  • low urgency / video

  • normal urgency / video

  • critical urgency / video

• interactive

  • interactive notification / video

• snap-decision

  • incoming call canceled / video

  • incoming call / video

  • incoming file / video

  • morning alarm reminder / video