Web Notifications API

Notifications are Ubiquitous in Life

Notifications on Desktop and Mobile Devices

W3C Web Notifications

W3C Candidate Recommendation 19 May 2015

• "... an API to display notifications to alert users outside the context of a web page."
• "It does not specify exactly how a user agent should display these notifications."
• "... notifications as specified here only can contain text and icon content."

Notification API

[Constructor(DOMString title, optional NotificationOptions options)]
interface Notification : EventTarget {
  static readonly attribute NotificationPermission permission;
  static void requestPermission(optional NotificationPermissionCallback callback);

  attribute EventHandler onclick;
  attribute EventHandler onshow;
  attribute EventHandler onerror;
  attribute EventHandler onclose;

  readonly attribute DOMString title;
  readonly attribute NotificationDirection dir;
  readonly attribute DOMString lang;
  readonly attribute DOMString body;
  readonly attribute DOMString tag;
  readonly attribute DOMString icon;

  void close();
};
      

NotificationOptions

dictionary NotificationOptions {
  NotificationDirection dir = "auto";
  DOMString lang = "";
  DOMString body;
  DOMString tag;
  DOMString icon;
};
      

Language

• Specifies the primary language for the notification's title and body.
• Is a valid BCP 47 language tag (tests, validator), or the empty string.
• The empty string indicates that the primary language is unknown.

NotificationPermission

enum NotificationPermission {
  "default",
  "denied",
  "granted"
};

callback NotificationPermissionCallback = void (NotificationPermission permission);
      

NotificationDirection

enum NotificationDirection {
  "auto",
  "ltr",
  "rtl"
};
      

EventTarget from DOM Standard

[Exposed=(Window,Worker)]
interface EventTarget {
  void addEventListener(DOMString type, EventListener? callback, optional boolean capture = false);
  void removeEventListener(DOMString type, EventListener? callback, optional boolean capture = false);
  boolean dispatchEvent(Event event);
};

callback interface EventListener {
  void handleEvent(Event event);
};
      

• EventTarget is an object to which an event is dispatched when something has occurred.
• Each EventTarget has an associated list of event listeners.
• An event listener associates a callback with a specific event.
• Each event listener consists of a type (of the event), callback, and capture variable.

EventHandler from HTML Standard

[TreatNonObjectAsNull]
callback EventHandlerNonNull = any (Event event);
typedef EventHandlerNonNull? EventHandler;
      

• Every event handler ends up registering the same listener.
• Listeners are called in the order they were registered.
• When an event handler H of an element or object T implementing the EventTarget interface is first set to a non-null value, the user agent must append an event listener to the list of event listeners associated with T with type set to the event handler event type corresponding to H, capture set to false, and listener set to the event handler processing algorithm.

Demo

Demo Code

if (!("Notification" in window)) {
  alert("This browser does not support desktop notification");
} else if (Notification.permission === "granted") {
  var notification = new Notification("Hi there!");
} else if (Notification.permission !== 'denied') {
  Notification.requestPermission(function (permission) {
    if (permission === "granted") {
      var notification = new Notification("Hi there!");
    }
  });
}
      

WHATWG Notifications API

Living Standard — Last Updated 1 May 2015

• "... an API to display notifications to the end user, typically outside the top-level browsing context’s viewport."
• "It is designed to be compatible with existing notification systems, while remaining platform-independent."

Notification API

[Constructor(DOMString title, optional NotificationOptions options),
 Exposed=(Window,Worker)]
interface Notification : EventTarget {
  static readonly attribute NotificationPermission permission;
  [Exposed=Window] static void requestPermission(optional NotificationPermissionCallback callback);

  attribute EventHandler onclick;
  attribute EventHandler onerror;

  readonly attribute DOMString title;
  readonly attribute NotificationDirection dir;
  readonly attribute DOMString lang;
  readonly attribute DOMString body;
  readonly attribute DOMString tag;
  readonly attribute USVString icon;
  readonly attribute USVString sound;
  // vibrate not exposed for now; see bug 23682
  readonly attribute boolean renotify;
  readonly attribute boolean silent;
  readonly attribute boolean noscreen;
  readonly attribute boolean sticky;
  [SameObject] readonly attribute any data;

  void close();
};
      

NotificationOptions

dictionary NotificationOptions {
  NotificationDirection dir = "auto";
  DOMString lang = "";
  DOMString body = "";
  DOMString tag = "";
  USVString icon;
  USVString sound;
  VibratePattern vibrate;
  boolean renotify = false;
  boolean silent = false;
  boolean noscreen = false;
  boolean sticky = false;
  any data = null;
};
      

VibratePattern from Vibration API

typedef (unsigned long or sequence<unsigned long>) VibratePattern;

partial interface Navigator {
    boolean vibrate (VibratePattern pattern);
};
      

• Blink Intent to Ship : Notification Options "vibrate" flag.
• navigator.vibrate(1000); navigator.vibrate([1000]);
• navigator.vibrate([1000, 1000, 2000]);
• navigator.vibrate(0); navigator.vibrate([]); navigator.vibrate([0]);

USVString v.s DOMString

  DOMString lang = "";
  DOMString body = "";
  DOMString tag = "";
  USVString icon;
  USVString sound;
      

• A USVString is a DOMString produced by encoding the given sequence of Unicode scalar values in UTF-16.
• USVString type corresponds to the set of all possible sequences of Unicode scalar values.
• The type name of the USVString type is “USVString”.

SameObject from WebIDL

[SameObject] readonly attribute any data;
      

• If the [SameObject] extended attribute appears on a read only attribute, then it indicates that when getting the value of the attribute on a given object, the same value must always be returned.
• The [SameObject] extended attribute must take no arguments.
• The [SameObject] extended attribute must not be used on anything other than a read only attribute whose type is an interface type, an array type or object.

Demo

Demo Code

var notify = function() {
  var options = {
    body: "Click me please!",
    icon: "../../../img/tizen-profiles-small.png",
    sound: "../../../sound/greeting.m4a",
    tag: "whatwg",
  };
  var n = new Notification('Greetings from Zhiqiang!', options);
  n.onclick = function() {
    alert("You have clicked the notification!");
  };
};
      

Service Worker based Notification

dictionary GetNotificationOptions {
  DOMString tag = "";
};

partial interface ServiceWorkerRegistration {
  Promise<void> showNotification(DOMString title, optional NotificationOptions options);
  Promise<sequence<Notification>> getNotifications(optional GetNotificationOptions filter);
};
      

Service Worker API

[Constructor(DOMString type, optional NotificationEventInit eventInitDict),
 Exposed=ServiceWorker]
interface NotificationEvent : ExtendableEvent {
  readonly attribute Notification notification;
};

dictionary NotificationEventInit : ExtendableEventInit {
  required Notification notification;
};

partial interface ServiceWorkerGlobalScope {
  attribute EventHandler onnotificationclick;
};
      

ExtendableEvent from Service Worker

[Constructor(DOMString type, optional ExtendableEventInit eventInitDict),
 Exposed=ServiceWorker]
interface ExtendableEvent : Event {
  void waitUntil(Promise<any> f);
};

dictionary ExtendableEventInit : EventInit {
  // Defined for the forward compatibility across the derived events
};
      

Promise Object from ES6 Draft

• A Promise is an object that is used as a placeholder for the eventual results of a deferred (and possibly asynchronous) computation.
• A Promise is in one of these states: pending, fulfilled, rejected, settled.

required keyword from WebIDL

dictionary identifier {
  required type identifier;
};
      

• If the type of the dictionary member is preceded by the required keyword, the member is considered a required dictionary member and must be present on the dictionary.
• A required dictionary member must not have a default value.

Demo

Tizen Notification API

Since 2.0

• "... provides a way to notify users of events that happen in an application."
• "This feature is supported in mobile applications only."
• "Currently (Tizen 2.3.0), only the StatusNotification subtype is supported. This subtype displays notifications in the status bar."

tizen.notification

typedef DOMString NotificationId;
enum NotificationType { "STATUS" };
enum StatusNotificationType { "SIMPLE", "THUMBNAIL", "ONGOING", "PROGRESS" };
enum NotificationProgressType { "PERCENTAGE",  "BYTE" };

[NoInterfaceObject] interface NotificationObject {
    readonly attribute NotificationManager notification;
};
Tizen implements NotificationObject;
      

NotificationManager

[NoInterfaceObject] interface NotificationManager {
    void post(Notification notification) raises(WebAPIException);
    void update(Notification notification) raises(WebAPIException);
    void remove(NotificationId id) raises(WebAPIException);
    void removeAll() raises(WebAPIException);
    Notification get(NotificationId id) raises(WebAPIException);
    Notification[] getAll() raises(WebAPIException);
};
      

Notification

[NoInterfaceObject] interface Notification {
    readonly attribute NotificationId id;
    readonly attribute NotificationType type;
    readonly attribute Date postedTime;
    attribute DOMString title;
    attribute DOMString? content;
};
      

StatusNotification

[Constructor(StatusNotificationType statusType, DOMString title,
 optional StatusNotificationInit? notificationInitDict)]
    interface StatusNotification : Notification {
    readonly attribute StatusNotificationType statusType;
    attribute DOMString? iconPath;
    attribute DOMString? subIconPath;
    attribute long? number;
    attribute NotificationDetailInfo[]? detailInfo;
    attribute DOMString? ledColor;
    attribute unsigned long ledOnPeriod;
    attribute unsigned long ledOffPeriod;
    attribute DOMString? backgroundImagePath;
    attribute DOMString[]? thumbnails;
    attribute DOMString? soundPath;
    attribute boolean vibration;
    attribute ApplicationControl? appControl;
    attribute ApplicationId? appId;
    attribute NotificationProgressType progressType;
    attribute unsigned long? progressValue;
};
      

StatusNotificationInit

dictionary StatusNotificationInit {
    DOMString? content;
    DOMString? iconPath;
    DOMString? soundPath;
    boolean? vibration;
    ApplicationControl? appControl;
    ApplicationId? appId;
    NotificationProgressType? progressType;
    unsigned long? progressValue;
    long? number;
    DOMString? subIconPath;
    NotificationDetailInfo[]? detailInfo;
    DOMString? ledColor;
    unsigned long ledOnPeriod;
    unsigned long ledOffPeriod;
    DOMString? backgroundImagePath;
    DOMString[]? thumbnails;
};
      

NotificationDetailInfo

[Constructor(DOMString mainText, optional DOMString? subText)]
interface NotificationDetailInfo {
    attribute DOMString mainText;
    attribute DOMString? subText;
};
      

Demo

See Tizen tutorial of notification, Notifying Users of Application Events

Recall Notification API

Recall Notification API

Recall Notification API

Crosswalk Implementation Status

• For Android, follow Android-webview's implementation of 'desktop notification', but only support non-persistent notification.
• For Linux, Peter Wang implemented 'desktop notification' based on 'libnotify', independent with chromium code. But only support (1) Notification constructor, (2) permission/requestPermission, (3) onclose.
• For Tizen, not implemented at all (there is an extension to implement a similar Tizen API).

Crosswalk Implementation Code

#if defined(OS_ANDROID)
  return blink::WebNotificationPermissionAllowed;
#elif defined(OS_LINUX) && defined(USE_LIBNOTIFY)
  return blink::WebNotificationPermissionAllowed;
#else
  return blink::WebNotificationPermissionDenied;
#endif
      

xwalk_platform_notification_service.cc

Crosswalk Implementation Next

• Investigate ditching "desktop" notifications support in Crosswalk

Demo

Future

• W3C Web Notifications will be a W3C Recommendation.
• The future is persistent notification (associated service worker registration).
• Notification's permission model shall be specified as part of the Permissions API.
• Support progress based notifications.