Utiliser l'API Notifications

Un des cas d'usage parmi les plus évidents pour les notifications est un client mail web ou une application de messagerie instantanée qui notifie dès qu'un nouveau message a été reçu, y compris lorsqu'on utilise l'appareil pour autre chose avec une autre application. De nombreux exemples existent, comme Slack.

Nous avons écrit un exemple concret : une application pour gérer des listes de tâches pour vous donner une meilleure idée de la façon dont les notifications web peuvent être utilisées. Les données sont stockées localement avec IndexedDB et les personnes sont notifiées lorsque les tâches arrivent à échéance grâce aux notifications système. Téléchargez le code de cette application, ou testez l'application en live.

Avant qu'une application puisse envoyer une notification, l'utilisatrice ou l'utilisateur doit lui accorder le droit de le faire. Il s'agit d'un prérequis courant pour les API qui doivent interagir en dehors d'une page web : la personne doit au moins une fois et explicitement accorder la permission à l'application d'afficher des notifications. La personne contrôle ainsi quels sites ou applications sont autorisés à afficher des notifications.

En raison d'abus des notifications par le passé, les équipes des navigateurs web ont commencé à mettre en place des stratégies pour limiter ce problème. Dans la pratique, vous ne devriez demander la permission à une personne uniquement après que celle-ci a interagi avec votre site/application (par exemple en ayant cliqué sur un bouton). Il ne s'agit pas seulement d'une bonne pratique (on ne devrait pas ennuyer les utilisatrices et utilisateurs avec de trop nombreuses notifications indésirées) mais d'une méthode qui sera implémentée par les différents navigateurs : Firefox le fait depuis Firefox 72 et Safari le fait également depuis quelque temps.

De plus, pour Chrome et Firefox, il n'est pas possible de demander la permission d'afficher des notifications à moins que le site soit servi dans un contexte sécurisé (c'est-à-dire avec HTTPS) et il n'est plus possible de demander une telle permission depuis une <iframe> d'une origine tierce.

Vous pouvez vérifier si la permission a déjà été accordée ou non grâce à la propriété en lecture seule Notification.permission. Cette dernière peut avoir l'une de ces trois valeurs :

default

La permission n'a pas encore été demandée à l'utilisatrice ou l'utilisateur, les notifications ne seront pas affichées.

granted

La permission d'afficher des notifications a été accordée après que la demande a été affichée.

denied

La permission d'afficher des notifications a été explicitement refusée.

Si la permission n'a pas encore été accordée, l'application devra utiliser la méthode Notification.requestPermission() afin de la demander. Une version très basique consiste à inclure :

Notification.requestPermission().then((resultat) => {
  console.log(resultat);
});

Cela utilise la version de la méthode sous forme de promesse. Si vous souhaitez ou avez besoin de prendre en charge les versions antérieures, vous pourrez avoir besoin de version sous forme d'une fonction de rappel (callback) :

Notification.requestPermission((resultat) => {
  console.log(resultat);
});

Cette version accepte en paramètre une fonction de rappel qui sera appelée une fois que l'utilisatrice ou l'utilisateur aura répondu à la demande de permission.

Dans notre application de démonstration, nous avons inclus un bouton « Activer les notifications » qui, lorsqu'il est pressé, demande la permission pour l'application.

<button id="enable">Activer les notifications</button>

Cliquer sur ce bouton déclenche l'appel à la fonction askNotificationPermission() :

function askNotificationPermission() {
  // On vérifie si le navigateur prend en charge les notifications
  if (!("Notification" in window)) {
    console.log("This browser does not support notifications.");
    return;
  }
  Notification.requestPermission().then((permission) => {
    // On affiche ou non le bouton en fonction de la réponse
    notificationBtn.style.display = permission === "granted" ? "none" : "block";
  });
}

Commençons par jeter un œil au deuxième bloc de code : vous verrez qu'on commence par vérifier la prise en charge de l'API Notifications. Si celle-ci est bien disponible, on utilise la version à base de promesses pour Notification.requestPermission().

Dans le gestionnaire de résolution de la promesse passé à then(), on affiche ou on masque le bouton selon ce que la personne a choisi. On ne veut pas le montrer si la permission a déjà été donnée, mais si la personne a décliné, on veut pouvoir le montrer plus tard au cas où elle change d'avis.

Pour créer une notification, on utilisera le constructeur Notification(). Ce constructeur attend un titre à afficher au sein de la notification et permet d'utiliser différentes options pour améliorer la notification comme une icône ou un texte (body).

Par exemple, dans notre application de démonstration, on utilise le fragment de code suivant pour créer une notification lorsque c'est nécessaire (ce fragment se trouve dans la fonction createNotification()) :

const img = "/to-do-notifications/img/icon-128.png";
const text = `Coucou ! Votre tâche "${titre}" arrive maintenant à échéance.`;
const notification = new Notification("Liste de trucs à faire", {
  body: text,
  icon: img,
});

On utilisera la méthode close() afin de retirer une notification qui n'est plus pertinente (par exemple parce que la personne l'a déjà lue sur la page web s'il s'agit d'une messagerie ou, dans le cas d'un lecteur de musique, si la chanson en cours de lecture a déjà changé). La plupart des navigateurs effacent les notifications après un certain délai (généralement autour de 4 secondes), mais ça ne devrait pas être un souci particulier, car cette tâche est souvent gérée par la personne ou l'agent utilisateur. La fermeture peut également être gérée par le système d'exploitation et les utilisatrices et utilisateurs doivent avoir la main sur ce comportement. D'anciennes versions de Chrome ne retiraient pas les automatiquement les notifications et vous pouvez donc utiliser un setTimeout() uniquement pour ces versions historiques.

const n = new Notification("Une super chanson");
document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "visible") {
    // L'onglet est désormais visible et la notification n'est plus pertinente
    // on peut la fermer
    n.close();
  }
});

Quatre évènements sont déclenchés sur une instance de Notification :

click

Déclenché lorsque la personne clique sur la notification.

close

Déclenché lorsque la notification a été fermée.

error

Déclenché si une erreur se produit avec la notification. Généralement, cela a lieu lorsqu'il y a un problème d'affichage.

show

Déclenché lorsque la notification est affichée.

Ces évènements peuvent être suivis avec les gestionnaires d'évènement onclick, onclose, onerror, et onshow. Notification héritant également de EventTarget, il est aussi possible d'utiliser la méthode addEventListener().

Il est généralement peu souhaitable de recevoir de nombreuses notifications sur une courte période. Par exemple, que se passerait-il si une messagerie envoyait une notification pour chaque message reçu alors qu'une discussion est en cours ? Pour éviter de submerger l'utilisatrice ou l'utilisateur avec de trop nombreuses notifications, il est possible de modifier les notifications en attente en remplaçant une ou plusieurs notifications avec une nouvelle notification à jour.

Pour cela, on pourra ajouter une balise à toute nouvelle notification. Si une notification existante possède la balise correspondante et qu'elle n'a pas encore été affichée, la nouvelle notification remplacera la précédente. Si une notification avec la même balise a déjà été affichée, elle est fermée et la nouvelle notification est affichée.

Prenons le fragment HTML qui suit :

<button>Envoyez une notification !</button>

Il est possible de gérer plusieurs notifications ainsi :

window.addEventListener("load", () => {
  const button = document.querySelector("button");

  if (window.self !== window.top) {
    // On s'assure que, si le document est dans une frame
    // la personne l'ouvre d'abord dans un onglet ou une
    // fenêtre à part afin de pouvoir gérer la permission
    // des notifications.
    button.textContent = "Voir le résultat de l'exemple de code";
    button.addEventListener("click", () => window.open(location.href));
    return;
  }

  button.addEventListener("click", () => {
    if (Notification?.permission === "granted") {
      // Si la personne a autorisé les notifications
      // On essaie de lui en envoyer 10
      let i = 0;
      // Pour cela, on utilise un intervalle afin d'éviter
      // que les navigateurs bloquent les notifications
      // s'il y en a trop sur une période donnée.
      const interval = setInterval(() => {
        // Grâce à la balise, on devrait uniquement voir
        // la notification "Coucou 9"
        const n = new Notification(`Coucou ${i}`, {
          tag: "tropDeNotifications",
        });
        if (i === 9) {
          clearInterval(interval);
        }
        i++;
      }, 200);
    } else if (Notification && Notification.permission !== "denied") {
      // Dans le cas où la personne n'a pas indiqué
      // si elle voulait recevoir des notifications

      // Note : à cause de Chrome, on ne peut pas être
      // certain que la propriété permission est
      // définie et on ne peut donc pas vérifier la
      // valeur "default".
      Notification.requestPermission().then((status) => {
        // Si la personne a autorisé
        if (status === "granted") {
          let i = 0;
          // Pour cela, on utilise un intervalle afin d'éviter
          // que les navigateurs bloquent les notifications
          // s'il y en a trop sur une période donnée.
          const interval = setInterval(() => {
            // Grâce à la balise, on devrait uniquement voir
            // la notification "Coucou 9"
            const n = new Notification(`Coucou ${i}`, {
              tag: "tropDeNotifications",
            });
            if (i === 9) {
              clearInterval(interval);
            }
            i++;
          }, 200);
        } else {
          // Sinon, on prend comme alternative une
          // fenêtre modale d'alerte
          alert("Coucou");
        }
      });
    } else {
      // Si la personne refuse les notifications, on
      // peut utiliser une fenêtre modale d'alerte
      alert("Coucou");
    }
  });
});

• Notification