Événements

Le widget rapporte ce qu’il fait par options.onEvent. Quarante-quatre événements couvrent tout le parcours : l’instance, les écrans, le consentement, le détecteur de visage, la caméra, le placement, les jetons, la mesure, le transport, la chaîne temps réel, et les panneaux superposés au parcours.

const instance = SaphereScan.create("#scan", {
    onEvent: event => console.log(event.type, event),
    proxy: { retrieveAccessToken: { strategy: "delegate", url: "/api/saphere-token" } }
})

Deux canaux, une différence

onEvent et les hooks se ressemblent et ne sont pas la même chose. La différence est le contrat, non le vocabulaire.

Le widget n’attend pas onEvent et ne lit pas ce qu’il retourne. C’est ce qui garantit qu’un gestionnaire lent ou fautif ne peut pas emporter une mesure avec lui. Si vous avez besoin de refuser quelque chose plutôt que de l’observer, c’est à cela que servent les hooks.

Lire un événement

Les noms sont de la forme domaine:événement. Chaque événement porte à plat ce qui le décrit — votre gestionnaire lit event.percent, non event.data.percent.

Le widget est distribué en JavaScript : aucune déclaration de type n’est servie avec le paquet. L’union que suivent tous les événements s’appelle SaphereScanEvent dans le widget ; déclarée de votre côté, elle rend exhaustif un switch sur event.type, chaque branche étant affinée à sa charge utile :

import type { SaphereScanEvent } from "./saphere-scan-events" // votre propre déclaration de l'union

const onEvent = (event: SaphereScanEvent) => {
    switch (event.type) {
        case "measure:result":  return save(event.result)
        case "measure:failed":  return report(event.code)
        case "camera:error":    return explain(event.code)
    }
}

En JavaScript, utilisez SAPHERE_SCAN_EVENTS, exporté par le module à côté de la classe, pour disposer des noms sous forme de constantes — une faute de frappe dans un littéral de chaîne nu est une branche qui ne s’exécute jamais en silence.

widget — l’instance

widget:error existe parce que la promesse rejetée est facile à manquer : une intégration qui appelle bootstrap() sans l’attendre n’aurait autrement aucun signe de l’échec du montage.

screen — le parcours

path est la route (/onboarding/1, /measurement, /result) ; name est l’écran (intro, onboarding, load-face-detectors, measurement, realtime, result, error).

Un écran d’essai affiché par previewScreen() rapporte le nom de l’écran qu’il représente, sous un chemin /preview/….

consent et form — ce que l’utilisateur accorde

checks porte une clé par case que l’écran montre : { check1: true, check2: false }. L’écran en propose quatre, dont les deux premières sont montrées d’origine ; une case que votre customisation retire ne demande rien, elle n’y figure donc pas. Toute case montrée doit être cochée pour que l’utilisateur puisse avancer.

consent:accepted est émis en quittant l’écran dans les deux sens, non au moment où la dernière case est cochée : tant que l’écran est là, l’utilisateur peut encore décocher. Un écran dont toutes les cases ont été retirées ne demande rien, et ne rapporte rien.

form:completed ne porte rien. Ce sont des données de santé, et elles vous parviennent déjà dans le userData du résultat — elles n’ont aucune raison de voyager deux fois.

detector — le détecteur de visage

detector:error mérite d’être branché. Il laisse l’écran de chargement sans issue : une seule ligne disant que les détecteurs n’ont pas pu être chargés — en anglais, quelle que soit la langue — et aucun bouton, rien sur quoi l’utilisateur puisse agir. C’est le seul cas où votre propre traitement des erreurs doit prendre le relais.

Ces trois-là concernent le détecteur de la mesure de trente secondes. L’écran temps réel charge les siens, et en signale l’échec par realtime:unavailable.

camera — la caméra

code vaut NOT_ALLOWED, NOT_FOUND, NOT_READABLE, ABORT, NOT_SUPPORTED ou UNKNOWN. name est le nom d’exception brut produit par le navigateur, les navigateurs ne les employant pas tous de la même façon — conservez-le pour le diagnostic, branchez sur code. Dans camera:ready, chacun des trois réglages vaut null quand le navigateur ne le rapporte pas.

camera:ended et camera:released sont deux états distincts. Le premier n’est pas voulu — la source s’est arrêtée d’elle-même, et la mesure est compromise. Le second est le widget qui fait le ménage.

placement — le cadrage du visage

guidance vaut "up", "down", "back" ou null — null signifiant soit que rien n’est à corriger, soit qu’aucun visage n’est vu. stable vaut true tant que le visage reste immobile — il a bougé d’au plus un pixel depuis la détection précédente — et false quand aucun visage n’est vu ; le départ attend un visage à la fois bien placé et immobile.

L’événement n’est émis qu’au changement. La détection tourne à chaque image de la caméra ; rapporter chaque image noierait un gestionnaire sans bénéfice.

token — le jeton d’accès

code sépare votre échec du nôtre — voyez les jetons d’accès pour le tableau. C’est le seul point du parcours où la faute peut être de votre côté, ce qui est la raison pour laquelle un code générique unique ne suffisait pas.

Sans proxy.retrieveAccessToken déclaré, token:error (NO_PROXY) arrive seul : il n’y avait rien à demander. Sur l’écran temps réel, un jeton qui n’arrive pas en cinq secondes mène à realtime:unavailable sans token:error avant lui.

La valeur du jeton n’est jamais portée par un événement.

measure — la mesure

La séparation entre aborted et failed existe pour votre supervision. Une annulation par l’utilisateur est un déroulement normal et ne doit pas apparaître dans vos tableaux de bord comme un incident.

attempt compte les tentatives d’une même visite de l’écran de mesure. Une deuxième suit l’utilisateur qui renonce à attendre (CANCELED_WHILE_PROCESSING), ce qui relance une mesure sur place. « Réessayer » sur l’écran de fin anormale, comme une nouvelle mesure depuis l’écran de résultat, rouvrent l’écran de mesure : le compte repart de un.

code est un motif d’échec, et il y en a quinze. Trois sont des arrêts, les autres des pannes.

Les quatre codes WS_ nomment l’acheminement vers le serveur de mesure. Les trois sur lesquels vous pouvez agir seul sont UNDEFINED_ACCESS_TOKEN_PROXY, CREATE_MEASURE_OPTIONS_ERROR et CREATE_MEASURE_OPTIONS_TIMEOUT : tous trois viennent de votre intégration, non de l’utilisateur ni du réseau.

measure:result est émis une fois la charge utile reçue et validée. Entre l’arrivée du résultat par le réseau et cet événement, le widget en vérifie la forme. Un résultat qui manque ce contrôle produit measure:failed à la place — de sorte que vous ne recevez jamais un résultat que le widget lui-même n’afficherait pas.

transport — l’acheminement vers le serveur

transport:disconnected n’arrive qu’une fois que rien ne sera retenté : quand le serveur ferme la connexion — c’est ainsi que se termine chaque mesure, une fois son résultat livré — ou quand le widget la ferme en quittant la mesure. Ce n’est donc pas une panne en soi ; c’est measure:failed qui en dit une. Pendant qu’une connexion se rétablit, vous recevez transport:reconnecting à la place — rapporter une reprise automatique comme une déconnexion ferait passer chaque bref à-coup pour une panne.

Ces cinq-là décrivent la connexion de la mesure de trente secondes. La chaîne temps réel a la sienne, dont la perte mène à realtime:unavailable.

realtime — la chaîne temps réel

Ces quatre-là ne valent que lorsque realtime est posé.

realtime:started est le seul événement qui dise que l’attente est finie : l’écran temps réel ne change pas entre le chargement et la mesure, donc screen:enter n’en rapporte rien. C’est le pendant de measure:start pour l’autre chaîne.

variables porte ce que le serveur calcule, tel quel — la charge est celle que décrivent les grandeurs de la chaîne temps réel. Rien n’arrive tant que la fenêtre est trop courte : l’absence veut dire « pas encore », non « rien à mesurer », et mature puis confident disent ensuite ce qui peut être affiché comme une mesure. L’écran du widget, lui, n’en montre aucune sous le seuil de qualité.

realtime:presence n’est émis qu’au changement. Le cadre de détection est recalculé à la cadence de capture ; ce qui vous est promis est l’entrée et la sortie du champ, non leur suivi — l’écran temps réel est celui du widget, calque de détection compris, et vous n’avez rien à dessiner par-dessus. L’absence de visage à l’ouverture de l’écran n’est pas rapportée : ce serait annoncer une sortie qui n’a pas eu lieu.

Quant à realtime:unavailable, le cas connu est Safari (26/27), dont l’implémentation WebTransport parle un draft du protocole que le serveur ne sert pas encore ; le parcours certifié passe par un WebSocket que ces navigateurs servent, et le widget y bascule plutôt que de laisser l’utilisateur devant un écran sans issue. Un jeton refusé, des détecteurs qui ne se chargent pas ou un lien qui tombe en pleine mesure mènent au même endroit : l’écran temps réel ne propose pas de reprise, le parcours certifié ne dépendant d’aucun de ces pas. Dans tous les cas la mesure que votre utilisateur est venu chercher reste à un écran.

ui — les couches superposées au parcours

ui:language-changed est rapporté quand l’utilisateur choisit une autre langue dans le sélecteur du widget — non quand votre propre setOptions() change lang. Il porte la direction parce que c’est ce sur quoi vous pouvez avoir à agir : une mise en page hôte encadrant le widget peut avoir à se retourner elle aussi.

Garanties d’ordonnancement

Deux, et elles sont structurelles plutôt que fortuites.

widget:ready est toujours le premier événement d’un montage qui réussit. Le démarrage de l’application dessine son premier écran immédiatement, de sorte que ce qui rapporte pendant cette étape — le détecteur de visage, par exemple — rapporterait sinon avant que le widget ne se soit annoncé. Ces événements sont retenus et délivrés derrière widget:ready.

Rien ne suit widget:destroyed. Le démontage de l’application exécute tous les crochets de destruction, dont plusieurs émettent. Le canal se verrouille avant que cela n’arrive, de sorte que l’événement est véritablement le dernier.

Au-delà de ces deux garanties, une mesure rapporte son issue avant l’écran qui la montre : measure:failed, puis screen:enter pour /error ; transport:disconnected, measure:result, puis screen:enter pour /result.

Ce qui n’est délibérément pas émis

Quatre absences, chacune pour une raison qui mérite d’être connue avant d’aller les chercher.

Aucun événement par message ré-émis. Une mesure envoie quelque neuf cents captures, et ce qu’une coupure laisse sans accusé de réception repart une fois la connexion revenue. Rapporter chaque renvoi produirait une rafale d’événements sur un canal qui, dans une intégration mobile, se trouve derrière un pont WebView. transport:reconnecting et transport:degraded couvrent le cas à la place.

Aucun point des deux ondes en temps réel. Le pouls et la respiration sont produits par image mesurée, soit une trentaine de valeurs par seconde chacun sur ce même canal. Les deux ondes sont tracées par l’écran, qui les lit sur place ; realtime:variables porte une fois par seconde ce qui en est tiré. Si ce sont les signaux eux-mêmes que vous voulez, c’est Realtime Measure qui les expose, avec la vidéo et l’affichage à votre main.

Aucun événement de redimensionnement. La taille du conteneur est votre mise en page, que vous connaissez déjà, et ResizeObserver se déclenche à chaque image d’animation pendant un glissement.

Aucun événement « calcul en cours » distinct. La fin de la capture et le passage à l’écran d’attente se produisent dans le même tour synchrone. measure:captures-sent le dit une fois, et porte les totaux.

Migrer

Depuis le widget v1

Correspondance des motifs caméra : denied → NOT_ALLOWED ; no-device → NOT_FOUND, ou NOT_READABLE sous Firefox, que la v1 y rangeait ; already-used → NOT_READABLE ou ABORT, que la v2 distingue ; not-supported → NOT_SUPPORTED. UNKNOWN est nouveau : la v1 n’avait pas de motif pour une exception qu’elle n’attendait pas.

Le contrat a changé sur un point : onEvent n’est plus attendu et son retour n’est plus lu. C’est ce qui garantit qu’un gestionnaire lent ou fautif ne peut pas emporter une mesure. La faculté de refuser n’a pas disparu — elle est passée dans les hooks, où elle est bornée par un délai de garde.

Depuis les premières intégrations v2

Les six premiers noms ont été remplacés par les noms à espace de nommage :