Utilisation des Notifications Web

Cette fonction est expérimentale
Puisque cette fonction est toujours en développement dans certains navigateurs, veuillez consulter le tableau de compatibilité pour les préfixes à utiliser selon les navigateurs.
Il convient de noter qu'une fonctionnalité expérimentale peut voir sa syntaxe ou son comportement modifié dans le futur en fonction des évolutions de la spécification.

En bref

L'API de Notifications Web permet à une page Web d'envoyer des notifications qui s'affichent hors de la page au niveau du système. Cela permet aux applications web d'envoyer des informations à un utilisateur, même si l'application est inactive. Un des principaux cas d'utilisation évidente est une application de messagerie Web qui informe l'utilisateur à chaque fois qu'un nouvel e-mail est reçu, même si l'utilisateur fait autre chose avec une autre application.

Pour afficher des notification, il faut commencer par demander la permission appropriée et d'instancier un objet Notification :

Notification.requestPermission( function(status) {
  console.log(status); // les notifications ne seront affichées que si "autorisées"
  var n = new Notification("title", {body: "notification body"}); // this also shows the notification
});

Obtenir l'autorisation

Avant qu'une application ne soit capable d'envoyer une notification, l'utilisateur doit donner son accord. C'est une exigence commune quand une API tente d'interagir avec quoi que ce soit en dehors d'une page Web. Cela permet d'éviter les notifications "spam" pour le bien-être de l'utilisateur.

Vérifier l'état de la permission

Une application qui a besoin d'envoyer une notification peut vérifier l'état d'autorisation actuel grâce à la propriété non modifiable Notification.permission . Il peut avoir l'une des trois valeurs possibles:

  • defaultl'utilisateur n'a pas encore donné sa permission (et donc aucune notification ne sera affichée à l'utilisateur).
  • grantedl'utilisateur a explicitement accepté d'être notifié par l'application.
  • denied: l'utilisateur a explicitement refusé d'être notifié par l'application.

Note: Safari et Chrome antérieurs à v32 n'appliquent pas encore la propriété  permission .

Recevoir la permission

Si l'autorisation n'est pas accordée, l'application doit utiliser la méthode Notification.requestPermission() pour permettre à l'utilisateur de faire un choix. Cette méthode accepte une fonction de rappel qui reçoit la permission choisie par l'utilisateur pour réagir.

C'est une pratique usuelle de demander l'autorisation à l'initialisation de l'application:

window.addEventListener('load', function () {
  Notification.requestPermission(function (status) {
    // Cela permet d'utiliser Notification.permission avec Chrome/Safari
    if (Notification.permission !== status) {
      Notification.permission = status;
    }
  });
});

Note: Chrome ne permet pas l'appel à Notification.requestPermission() dans l'event load (voir issue 274284).

Manifeste des permissions pour l'API de Notification

Notez que tant que que l'API de Notification API n'est pas privileged ou certifiée, il vous faudra toujours ajouter une entrée dans votre ficher manifest.webapp pour l'inclure dans une application web ouverte:

"permissions": {
  "desktop-notification": {
    "description": "Needed for creating system notifications."
  }
}

Remarque : quand une application est installée, vous ne devriez pas avoir besoin de demander la permission explicitement par le code ci-dessus, mais vous aurez toujours besoin de l'entrée des autorisations ci-dessus pour que les notifications soient lancées.

Créer une notification

Créer une notification peut être simplement réalisé en utilisant le constructeur Notification. Ce constructeur s'attend à recevoir un titre à afficher dans la notification et quelques options pour la personnaliser telles qu'une icône icon ou un texte body.

Une notification sera affichée dès que possible. Pour connaître son statut d'affichage, quatre événements peuvent être déclenchés au niveau de Notification :

  • show: déclenché quand la notification est affichée à l'utilisateur.
  • click: déclenché quand l'utilisateur clique sur la notification.
  • close: déclenché quand la notification est fermée.
  • error: déclenché quand quelque chose n'a pas fonctionné avec cette notification (surtout quand quelque chose empêche la notification d'être affichée)

Ces événements peuvent être suivis en utilisant les gestionnaires d'événements onshow, onclick, onclose, ou onerror. Car Notification hérite également de EventTarget, Il est possible d'utiliser cette addEventListener() méthode..

Note: Firefox et Safari ferment automatiquement les notifications après un certain temps, de l'ordre de 4 secondes.

Cela peut aussi être fait au niveau de l'application web en utilisant la méthode Notification.close(),  comme par exemple dans le code suivant:

var n = new Notification("Salut!");
n.onshow = function () { 
  setTimeout(n.close.bind(n), 5000); 
}

Quand vous recevez un événement "close", il n'y a aucune garantie que l'utilisateur ait lui-même fermé la notification. C'est en accord avec la spécification, qui dit : "When a notification is closed, either by the underlying notifications platform or by the user, the close steps for it must be run." soit "Quand une notification est fermée, que ce soit par la plateforme ou par l'utilisateur, on procède à l'étape de clôture."

Un petit exemple

En considérant ce petit bout de HTML assez simple :

<button>Notifiez moi!</button>

Il est possible de gérer les notifications de cette façon :

window.addEventListener('load', function () {
  // Premièrement, vérifions que nous avons la permission de publier des notifications. Si ce n'est pas le cas, demandons la
  if (window.Notification && Notification.permission !== "granted") {
    Notification.requestPermission(function (status) {
      if (Notification.permission !== status) {
        Notification.permission = status;
      }
    });
  }

  var button = document.getElementsByTagName('button')[0];

  button.addEventListener('click', function () {
    // Si l'utilisateur accepte d'être notifié
    if (window.Notification && Notification.permission === "granted") {
      var n = new Notification("Coucou !");
    }

    // Si l'utilisateur n'a pas choisi s'il accepte d'être notifié
    // Note: à cause de Chrome, nous ne sommes pas certains que la propriété permission soit définie, par conséquent il n'est pas sûr de vérifier la valeur par défaut.
    else if (window.Notification && Notification.permission !== "denied") {
      Notification.requestPermission(function (status) {
        if (Notification.permission !== status) {
          Notification.permission = status;
        }

        // Si l'utilisateur est OK
        if (status === "granted") {
          var n = new Notification("Coucou !");
        }

        // Sinon, revenons en à un mode d'alerte classique
        else {
          alert("Coucou !");
        }
      });
    }

    // Si l'utilisateur refuse d'être notifié
    else {
      // We can fallback to a regular modal alert
      alert("Coucou !");
    }
  });
});

Et voici le résultat:

Gestion des notifications répétitives

Dans certains cas, il peut être dérangeant pour l'utilisateur de lui envoyer un nombre élevé de notifications - par exemple, si une application pour la messagerie instantanée peut notifier à un utilisateur pour chaque message entrant. Pour éviter une invasion de "bulles" sur le bureau de l'utilisateur avec des centaines de notifications inutiles, il est possible de prendre en charge la file d'attente des notifications en attente.

Pour ce faire, il est possible d'ajouter un tag à toute nouvelle notification. Si une notification a déjà le même tag et n'a pas encore été affichée, la nouvelle notification va remplacer l'ancienne. Si la notification avec le même tag a déjà été affichée, l'ancienne notification est fermée et la nouvelle est affichée.

Exemple de Tag

Considérons le code HTML suivant:

<button>Notifie moi!</button>

Il est possible de gérer plusieurs notifications de cette manière:

window.addEventListener('load', function () {
  // Premièrement, vérifions que nous avons la permission de notifier
  // Sinon, demandons la permission
  if (window.Notification && Notification.permission !== "granted") {
    Notification.requestPermission(function (status) {
      if (Notification.permission !== status) {
        Notification.permission = status;
      }
    });
  }

  var button = document.getElementsByTagName('button')[0];

  button.addEventListener('click', function () {
    // Si l'utilisateur accepte les notifications
    // essayons d'envoyer 10 notifications
    if (window.Notification && Notification.permission === "granted") {
      for (var i = 0; i < 10; i++) {
        // Grâce au tag, nous ne devrions voir que la notification "Hey! 9" 
        var n = new Notification("Hey! " + i, {tag: 'soManyNotification'});
      }
    }

    // Si l'utilisateur n'a pas choisi s'il accepte d'être notifié // Note: à cause de Chrome, nous ne sommes pas certains que la
    // propriété permission soit définie, par conséquent il n'est pas
    // sûr de vérifier la valeur par défault.
    else if (window.Notification && Notification.permission !== "denied") {
      Notification.requestPermission(function (status) {
        if (Notification.permission !== status) {
          Notification.permission = status;
        }

        // Si l'utilisateur a accepté les notifications
        if (status === "granted") {
          for (var i = 0; i < 10; i++) {
            // Grâce au tag, nous ne devrions voir que la notification "Hey! 9"
            var n = new Notification("Hey! " + i, {tag: 'soManyNotification'});
          }
        }

        // Sinon on bascule sur une alerte modale
        else {
          alert("Hey!");
        }
      });
    }

    // Si l'utilisateur refuse les notifications
    else {
      // on bascule sur une alerte modale
      alert("Hey!");
    }
  });
});

Et voici le résultat:

Recevoir la notification du clic sur une notification

Quand un utilisateur clique sur une notification générée par une application, il sera notifié de cet événement de deux façons, en fonction de la circonstance:

  1. Un événement click si votre application n'a pas été fermée ou placée en arrière-plan entre le moment où vous créez la notification et celui où l'utilisateur clique dessus.
  2. Sinon un message système

Voir cet extrait de code pour un exemple d'utilisation.

Spécifications

Spécification Statut Commentaire
Notifications API Recommendation Spécification initiale

Compatibilité Navigateurs

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support 5 webkit (see notes)
22
4.0 moz (see notes)
22
Pas de support ? 6 (see notes)
Feature Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support ? 4.0 moz (see notes)
22
Pas de support ? ?

Gecko notes

  • Prior to Firefox 22 (Firefox OS <1.2), the instantiation of a new notification must be done with the navigator.mozNotification object through its createNotification method.
  • Prior to Firefox 22 (Firefox OS <1.2), the Notification was displayed when calling the show method and was supporting the click and close events only.
  • Nick Desaulniers has written a Notification shim to cover both newer and older implementations.
  • One particular Firefox OS issue is that you can pass a path to an icon to use in the notification, but if the app is packaged you cannot use a relative path like /my_icon.png. You also can't use navigator.location.origin + "/my_icon.png" because navigator.location.origin is null in packaged apps. The manifest origin field fixes this, but it is only available in Firefox OS 1.1+. A potential solution for supporting Firefox OS <1.1 is to pass an absolute URL to an externally hosted version of the icon. This is less than ideal as the notification is displayed immediately with the icon missing, then the icon is fetched, but it works on all versions of Firefox OS.

Chrome notes

Safari notes

  • Safari started supporting notification with Safari 6 but only on Mac OSX 10.8+ (Mountain Lion).

A lire aussi

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : Kazquo, Hell_Carlito, JeffD, 3bandiste, Goofy, Moosh
 Dernière mise à jour par : Kazquo,