Utiliser l'API Notifications

Exemples

Un des cas d'usage parmi les plus vidents pour les notifications est un client mail web ou une application de messagerie instantane qui notifie ds qu'un nouveau message a t reu, 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 grer des listes de tches pour vous donner une meilleure ide de la faon dont les notifications web peuvent tre utilises. Les donnes sont stockes localement avec IndexedDB et les personnes sont notifies lorsque les tches arrivent chance grce aux notifications systme. Tlchargez le code de cette application, ou testez l'application en live.

Demander la permission

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 prrequis 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 contrle ainsi quels sites ou applications sont autoriss afficher des notifications.

En raison d'abus des notifications par le pass, les quipes des navigateurs web ont commenc mettre en place des stratgies pour limiter ce problme. Dans la pratique, vous ne devriez demander la permission une personne uniquement aprs 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 indsires) mais d'une mthode qui sera implmente par les diffrents 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 scuris (c'est--dire avec HTTPS) et il n'est plus possible de demander une telle permission depuis une <iframe> d'une origine tierce.

Vrifier l'tat de la permission

Vous pouvez vrifier si la permission a dj t accorde ou non grce la proprit en lecture seule Notification.permission. Cette dernire peut avoir l'une de ces trois valeurs :

default

La permission n'a pas encore t demande l'utilisatrice ou l'utilisateur, les notifications ne seront pas affiches.

granted

La permission d'afficher des notifications a t accorde aprs que la demande a t affiche.

denied

La permission d'afficher des notifications a t explicitement refuse.

Obtenir la permission

Si la permission n'a pas encore t accorde, l'application devra utiliser la mthode Notification.requestPermission() afin de la demander. Une version trs basique consiste inclure :

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

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

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

Cette version accepte en paramtre une fonction de rappel qui sera appele une fois que l'utilisatrice ou l'utilisateur aura rpondu la demande de permission.

Exemple

Dans notre application de dmonstration, 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 dclenche l'appel la fonction askNotificationPermission() :

function askNotificationPermission() {
  // On vrifie 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 rponse
    notificationBtn.style.display = permission === "granted" ? "none" : "block";
  });
}

Commenons par jeter un il au deuxime bloc de code : vous verrez qu'on commence par vrifier 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 rsolution 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 dj t donne, mais si la personne a dclin, on veut pouvoir le montrer plus tard au cas o elle change d'avis.

Crer une notification

Pour crer une notification, on utilisera le constructeur Notification(). Ce constructeur attend un titre afficher au sein de la notification et permet d'utiliser diffrentes options pour amliorer la notification comme une icne ou un texte (body).

Par exemple, dans notre application de dmonstration, on utilise le fragment de code suivant pour crer une notification lorsque c'est ncessaire (ce fragment se trouve dans la fonction createNotification()) :

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

Fermer les notifications

On utilisera la mthode close() afin de retirer une notification qui n'est plus pertinente (par exemple parce que la personne l'a dj 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 dj chang). La plupart des navigateurs effacent les notifications aprs un certain dlai (gnralement autour de 4 secondes), mais a ne devrait pas tre un souci particulier, car cette tche est souvent gre par la personne ou l'agent utilisateur. La fermeture peut galement tre gre par le systme 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 dsormais visible et la notification n'est plus pertinente
    // on peut la fermer
    n.close();
  }
});

vnements relatifs aux notifications

Quatre vnements sont dclenchs sur une instance de Notification :

click

Dclench lorsque la personne clique sur la notification.

close

Dclench lorsque la notification a t ferme.

error

Dclench si une erreur se produit avec la notification. Gnralement, cela a lieu lorsqu'il y a un problme d'affichage.

show

Dclench lorsque la notification est affiche.

Ces vnements peuvent tre suivis avec les gestionnaires d'vnement onclick, onclose, onerror, et onshow. Notification hritant galement de EventTarget, il est aussi possible d'utiliser la mthode addEventListener().

Remplacer les notifications existantes

Il est gnralement peu souhaitable de recevoir de nombreuses notifications sur une courte priode. Par exemple, que se passerait-il si une messagerie envoyait une notification pour chaque message reu 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 remplaant une ou plusieurs notifications avec une nouvelle notification jour.

Pour cela, on pourra ajouter une balise toute nouvelle notification. Si une notification existante possde la balise correspondante et qu'elle n'a pas encore t affiche, la nouvelle notification remplacera la prcdente. Si une notification avec la mme balise a dj t affiche, elle est ferme et la nouvelle notification est affiche.

Exemple d'utilisation des balises

Prenons le fragment HTML qui suit :

<button>Envoyez une notification !</button>

Il est possible de grer 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
    // fentre  part afin de pouvoir grer la permission
    // des notifications.
    button.textContent = "Voir le rsultat de l'exemple de code";
    button.addEventListener("click", () => );
    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 priode donne.
      const interval = setInterval(() => {
        // Grce  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 proprit permission est
      // dfinie et on ne peut donc pas vrifier 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 priode donne.
          const interval = setInterval(() => {
            // Grce  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
          // fentre modale d'alerte
          alert("Coucou");
        }
      });
    } else {
      // Si la personne refuse les notifications, on
      // peut utiliser une fentre modale d'alerte
      alert("Coucou");
    }
  });
});

Rsultat

Voir aussi

• Notification