Développer une application web qui utilise desévènements envoyés par le serveur (server-sent events en anglais) est relativement simple. Côté serveur, on aura besoin d'un bout de code qui puisse transmettre des évènements à l'application web ; côté client, le fonctionnement est quasi identique à celui qu'on utilise pour leswebsockets et notamment la gestion d'évènements entrants. Il s'agit d'une connexion unidirectionnelle : on ne peut pas envoyer d'évènements du client vers le serveur.

Recevoir des évènements du serveur

L'API des évènements serveur est exposée par l'interfaceEventSource ; pour ouvrir une connexion vers le serveur afin de commencer à recevoir des évènements de celui-ci, on crée un nouvel objetEventSource, en spécifiant l'URL d'un script côté serveur qui va générer les évènements. Par exemple :

const evtSource = new EventSource("ssedemo.php");

Si le script qui génère les évènements est hébergé sur une origine différente, le nouvel objetEventSource doit être créé en spécifiant à la fois l'URL et un dictionnaire d'options. Par exemple, en supposant que le script client est sur example.com :

const evtSource = new EventSource("//api.example.com/ssedemo.php", {  withCredentials: true,});

Une fois que la source d'évènement a été instanciée, on peut écouter les messagessans propriétéevent provenant du serveur en attachant un gestionnaire d'évènement pourmessage :

evtSource.onmessage = function (event) {  const newElement = document.createElement("li");  const eventList = document.getElementById("list");  newElement.textContent = "message: " + event.data;  eventList.appendChild(newElement);};

Ce code écoute les messages entrants (plus précisément, les notifications venant du serveur qui n'ont pas de champevent attaché) et ajoute le texte des messages à une liste dans le contenu HTML du document.

On peut écouter les évènements de messageavec un champevent grâce àaddEventListener() :

evtSource.addEventListener("ping", function (event) {  const newElement = document.createElement("li");  const time = JSON.parse(event.data).time;  newElement.textContent = "ping at " + time;  eventList.appendChild(newElement);});

Ce fragment de code sera appelé si le serveur envoie un message dont le champevent estping ; il analysera alors le JSON dans le champdata et l'affichera.

Envoyer un évènement depuis le serveur

Le script côté serveur qui envoie les évènements doit répondre en utilisant le type MIMEtext/event-stream. Chaque notification est envoyée sous la forme d'un bloc de texte se terminant par une paire de caractères saut de ligne (\n). Pour plus de détails sur le format du flux d'évènements, voirla section ci-après.

Voici le codePHP que nous utilisons pour notre exemple :

date_default_timezone_set("America/New_York");header("Cache-Control: no-cache");header("Content-Type: text/event-stream");$counter = rand(1, 10);while (true) {  // Chaque seconde, on envoie un évènement "ping".  echo "event: ping\n";  $curDate = date(DATE_ISO8601);  echo 'data: {"time": "' . $curDate . '"}';  echo "\n\n";  // Envoi d'un message simple à fréquence aléatoire.  $counter--;  if (!$counter) {    echo 'data: Message envoyé à ' . $curDate . "\n\n";    $counter = rand(1, 10);  }  ob_end_flush();  flush();  // On ferme la boucle si le client a interrompu la connexion  // (par exemple en fermant la page)  if ( connection_aborted() ) break;  sleep(1);}

Ce code génère un évènement de type « ping » à chaque seconde. La donnée de chaque évènement est un objet JSON contenant un horodatage ISO 8601 qui correspond à l'heure à laquelle l'évènement a été généré. À des intervalles aléatoires, un message simple (sans type d'évènement) est envoyé.

La boucle s'exécute indépendamment du statut de la connexion, on a donc une vérification pour terminer l'exécution si la connexion a été terminée.

Gestion des erreurs

Quand un problème survient (tel qu'un délai de réponse dépassé ou une erreur liée aucontrôle d'accès), un évènementerror est généré. Vous pouvez traiter ces cas d'erreur en implémentant la fonction de rappelonerror sur l'objetEventSource.

evtSource.onerror = function (err) {  console.error("EventSource failed:", err);};

Fermer les flux d'évènements

Par défaut, si la connexion entre le client et le serveur est rompue, elle sera relancée. Il est possible de la fermer explicitement à l'aide de la méthode.close().

evtSource.close();

Format du flux d'évènements

Le flux d'évènements est un simple flux de données de texte, qui doit être encodé enUTF-8. Les messages dans le flux d'évènements sont séparés par une paire de sauts de ligne. Un caractère deux-points « : » en début de ligne représente un commentaire, et est ignoré.

Chaque message consiste en une ou plusieurs lignes de texte décrivant les champs de ce message. Chaque champ est représenté par le nom du champ, suivi d'un « : », suivi des données de texte pour la valeur de ce champ.

Champs

Chaque message reçu contient un ou plusieurs de ces champs, un par ligne :

event

Une chaîne identifiant le type d'évènement décrit. S'il est spécifié, un évènement sera envoyé dans le navigateur à l'écouteur défini pour l'évènement spécifié. Le code source de l'application doit utiliseraddEventListener() pour écouter des évènements nommés. Le gestionnaireonmessage est appelé si aucun nom d'évènement n'est spécifié dans un message.

data

Le champ de données du message. Lorsque l'EventSource reçoit plusieurs lignes de message consécutives commençant pardata:,il les concatène, en ajoutant un caractère saut de ligne entre chacune d'elles. Les sauts de ligne en fin de message sont supprimés.

id

L'identifiant d'évènement, qui sera mémorisé comme valeur d'identifiant du dernier évènement de l'objetEventSource.

retry

Le délai de reconnexion à utiliser lors de la tentative d'envoi de l'évènement. Il doit être un nombre entier, spécifiant le temps de reconnexion en millisecondes. Si une valeur non entière est spécifiée, le champ est ignoré.

Tous les autres noms de champs sont ignorés.

Exemples

Messages contenant uniquement des données

Dans l'exemple suivant, trois messages sont envoyés. Le premier est simplement un commentaire, car il débute par un caractère deux-points. Comme mentionné précédemment, cela peut être utile pour maintenir la connexion si des messages doivent être transmis de façon irrégulière.

Le deuxième message contient un champdata avec la valeur"du texte". Le troisième message contient un champdata avec la valeur"un autre message\nsur deux lignes". On notera le caractère saut de ligne dans la valeur.

: this is a test streamdata: du textedata: un autre messagedata: sur deux lignes

Évènements nommés

Cet exemple envoie une série d'évènements nommés. Chacun a un nom d'évènement spécifié par le champevent, et un champdata dont la valeur est une chaîne JSON appropriée avec les données nécessaires au client pour réagir à l'évènement. Le champdata peut évidemment contenir n'importe quelles données textuelles, il n'est pas obligatoirement au format JSON.

event: userconnectdata: {"username": "bobby", "time": "02:33:48"}event: usermessagedata: {"username": "bobby", "time": "02:34:11", "text": "Hi everyone."}event: userdisconnectdata: {"username": "bobby", "time": "02:34:23"}event: usermessagedata: {"username": "sean", "time": "02:34:36", "text": "Bye, bobby."}

Mélanger les types de message

Il n'est pas obligatoire d'utiliser uniquement des messages sans nom ou des évènements nommés. Vous pouvez mélanger les deux dans un même flux d'évènements.

event: userconnectdata: {"username": "bobby", "time": "02:33:48"}data: Ici un message système quelconque qui sera utilisédata: pour accomplir une tâche.event: usermessagedata: {"username": "bobby", "time": "02:34:11", "text": "Hi everyone."}

Compatibilité des navigateurs