--- title: Utilisation des Notifications Web slug: Web/API/notification/Using_Web_Notifications tags: - Avancé - DOM - Firefox OS - Guide - Notifications translation_of: Web/API/Notifications_API/Using_the_Notifications_API ---

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 notifications, il faut commencer par demander la permission appropriée et d'instancier un objet {{domxref("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 {{domxref("Notification.permission")}} . Il peut avoir l'une des trois valeurs possibles :

default: l'utilisateur n'a pas encore donné sa permission (et donc aucune notification ne sera affichée à l'utilisateur).
granted: l'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 {{domxref("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 permettait pas l'appel à {{domxref("Notification.requestPermission()")}} dans l'event load jusqu'à sa version 37 (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 {{domxref("Notification")}}. Ce constructeur s'attend à recevoir un titre à afficher dans la notification et quelques options pour la personnaliser telles qu'une icône {{domxref("Notification.icon","icon")}} ou un texte {{domxref("Notification.body","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 {{domxref("Notification")}} :

{{event("show")}}: déclenché quand la notification est affichée à l'utilisateur.
{{event("click")}}: déclenché quand l'utilisateur clique sur la notification.
{{event("close")}}: déclenché quand la notification est fermée.
{{event("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 {{domxref("Notification.onshow","onshow")}}, {{domxref("Notification.onclick","onclick")}}, {{domxref("Notification.onclose","onclose")}}, ou {{domxref("Notification.onerror","onerror")}}. Car {{domxref("Notification")}} hérite également de {{domxref("EventTarget")}}, Il est possible d'utiliser cette {{domxref("EventTarget.addEventListener","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 {{domxref("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:

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.
Sinon un message système

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

Spécifications

Spécification	Statut	Commentaire
{{SpecName('Web Notifications')}}	{{Spec2('Web Notifications')}}	Spécification initiale

Compatibilité Navigateurs

A lire aussi

{{ domxref("Notification") }}