Options
Tout ce que Handler.load() accepte : la stratégie de mesure, la fonction de rappel d’événements, la palette de onze couleurs, les écrans et les textes.
Une nouvelle intégration devrait utiliser Saphere Scan v2. Ce qui suit documente l’objet d’options de la v1.
Vos options sont validées, puis fusionnées par-dessus les valeurs par défaut — et par-dessus toute personnalisation appliquée par ?customizationId=, de sorte que ce que vous passez dans votre code l’emporte sur la personnalisation. Les clés de premier niveau inconnues sont refusées plutôt qu’ignorées : load() lève Bad module options!.
Premier niveau
| Clé | Type | Défaut | Remarques |
|---|---|---|---|
createMeasure | objet | — | Requis. Comment une mesure est obtenue. |
onEvent | fonction | — | Appelée à chaque événement. |
allowLeave | booléen | false | Affiche une commande permettant à l’utilisateur de quitter le widget. |
allowSkip | booléen | false | Affiche un lien passer sur chaque écran de consignes sauf le formulaire d’informations personnelles. Quand le parcours comporte ce formulaire et que l’utilisateur ne l’a pas encore atteint, le lien y mène, puis le formulaire mène directement à la caméra ; sinon il mène directement à la caméra. Tout ce qui se trouve entre les deux, écran de consentement compris, n’est pas montré. |
lang | chaîne | première langue du navigateur que le widget prend en charge, sinon "en" | L’une des dix langues prises en charge. |
useShadow | booléen | true | Monte dans un shadow root. |
isMobile | booléen | détection de l’appareil | Impose la présentation téléphone ou bureau : illustrations, caméra frontale, changement de caméra. |
desiredVariables | string[] | — | Transmis à createMeasure ; réduit ce qui est calculé une fois que votre serveur le transmet à POST /measures. |
tags | string[] | — | Transmis à createMeasure ; conservés avec la mesure une fois que votre serveur les transmet. |
colors | objet | voir Handler.defaultModuleOptions | Les onze couleurs. |
pages | objet | voir Handler.defaultModuleOptions | Les écrans que le parcours comporte, et le logo. |
texts | objet | intégrés, dix langues | Chaque chaîne, par langue. |
colors, pages et texts décrivent l’apparence. Leur forme est celle que montre Handler.defaultModuleOptions, et n’importe quelle partie peut en être passée. colors et pages se préparent de préférence dans la console plutôt que dans votre code — voir l’apparence plus bas — mais l’atelier de la console, qui n’a que deux onglets, Colors et Pages, n’en couvre qu’une partie : sept des onze couleurs (color04, color09, color10 et color11 se posent dans le code), les écrans de consignes (pages.validates 1, 2 et 4 à 8), le logo et la notice. Tout le reste ne se pose que dans le code : chaque chaîne (texts), le formulaire d’informations personnelles (pages.validates[3] : { ignore: false, fields: { … } }, les six champs externalId, height, weight, age, sex et smokingStatus donnés chacun en { ignore }, l’un d’eux au moins conservé), pages.result, pages.staticFacePlacement et pages.finalForm. Une couleur s’écrit #RGB ou #RRGGBB. Une charge partielle est fondue dans les défauts, discriminant compris : pages: { logo: { data: "data:image/png;base64,…" } } suffit à poser un logo, sans ignore: false à côté, et une entrée de pages.validates qui omet ignore garde celui des défauts.
useShadow: false laisse votre CSS entrer
createMeasure
Le widget a besoin d’une mesure à laquelle rattacher la capture. Il existe deux stratégies, et elles diffèrent par qui fait l’appel.
delegate — le widget appelle votre point d’accès
createMeasure: {
strategy: "delegate",
url: "/api/saphere-measure",
headers: { "X-Session": sessionId } // facultatif
}
Le widget émet POST <url> avec un corps JSON portant userData, desiredVariables et tags — chacun seulement s’il a une valeur — et attend { "id": "<measureId>" } en retour. Il pose Content-Type: application/json par-dessus vos headers.
Votre point d’accès authentifie votre utilisateur, appelle POST /measures sur l’API Saphere avec votre clé, et relaie l’identifiant. La réponse de l’API porte le champ id, si bien qu’elle peut être relayée telle quelle.
handle — votre code fait l’appel
fetch reçoit le même objet que celui que porte le corps de delegate, { userData, desiredVariables, tags }, et résout vers la mesure.
createMeasure: {
strategy: "handle",
fetch: async ({ userData, desiredVariables }) => {
const response = await fetch("/api/saphere-measure", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ userData, desiredVariables })
})
return await response.json() // doit être { id: "…" }
}
}
fetch doit résoudre vers un objet portant un id
Rendre l’identifiant sous la forme d’une chaîne nue fait échouer la création, et la mesure s’arrête sur CREATE_MEASURE_ERROR. Le contrat est { id: string } — un objet.
Cela vaut d’être vérifié en premier quand une intégration v1 échoue dès le départ : certains exemples publiés rendaient json["token"], qui est une chaîne, et ne le satisfait pas.
Quand la mesure est créée
Le widget demande une mesure à chaque tentative, au moment où le visage est accepté — juste après l’événement start — et en parallèle du compte à rebours et de la capture. La création échoue quand votre point d’accès delegate répond un statut hors 2xx, quand votre fetch rejette, quand la réponse ne porte pas d’id sous forme de chaîne, ou quand aucune réponse n’arrive sous 25 secondes. Le widget arrête alors la mesure : onEvent reçoit aborted avec CREATE_MEASURE_ERROR, et l’utilisateur voit l’écran d’erreur. Rien n’est levé vers votre code.
Rendez une mesure neuve à chaque appel. Un identifiant de mesure ne sert qu’une fois, et le réutiliser ne produit pas de seconde mesure. Quand le serveur de mesure refuse un identifiant, le module retente la connexion six fois — sept poignées de main, en six secondes environ — puis arrête la mesure : onEvent reçoit aborted avec WS_CONNECTION_ERROR. Une fois la connexion établie, la reprise après une coupure n’est plus limitée. L’ouverture d’une mesure est aussi bornée par compte — voir la limitation de débit ; une ouverture refusée pour cette raison est retentée d’elle-même.
onEvent
onEvent: async event => {
console.log(event.type, event)
}
Appelée pour chaque événement ci-dessous. La valeur rendue est significative : rendre littéralement false annule la transition que l’événement annonce. Tout le reste l’autorise, y compris undefined, et y compris une exception levée par votre propre code, qui est journalisée et ignorée.
Le gestionnaire est attendu.
Un gestionnaire lent ralentit le widget
Parce que la valeur rendue peut opposer un veto à une transition, la v1 attend votre gestionnaire avant de poursuivre. Un gestionnaire qui fait un appel réseau à chaque événement retarde le parcours utilisateur d’autant.
C’est le comportement que la v2 a délibérément abandonné : là, onEvent n’est jamais attendu, et le veto a migré vers une API hooks distincte, réduite à deux points et bornée par un délai.
L’union des événements
type | Charge utile | Quand |
|---|---|---|
video-stream-loading | { status: "start" } | La caméra est demandée |
video-stream-loading | { status: "ready" } | Le flux est ouvert |
video-stream-loading | { status: "error", reason } | La caméra n’a pas pu être ouverte |
start | — | Le visage est accepté et le cadrage figé |
record | — | La capture commence |
end | — | Toutes les images sont mises en file et le marqueur de fin est en attente |
result | { id, userData?, variables } | La mesure a abouti |
aborted | { reasons } | La mesure s’est arrêtée |
leave | — | L’utilisateur a demandé à quitter (exige allowLeave) ; le widget ne fait rien d’autre — démontez-le avec Handler.destroy() |
transition | { from, to } | Déclaré, mais jamais émis |
Le reason de video-stream-loading vaut "denied", "no-device", "not-supported" ou "already-used". Une erreur de caméra que le navigateur ne range sous aucun des noms que le module connaît (contraintes impossibles, contexte refusé…) arrive en "not-supported", et le module montre son écran « non pris en charge ».
Si le navigateur n’expose aucune API de caméra — origine non sécurisée, WebView qui n’en fournit pas — le module montre aussitôt son écran « non pris en charge » et n’émet aucun événement video-stream-loading d’erreur : le seul événement video-stream-loading reçu est celui de status: "start".
Le reasons d’aborted est un code unique, malgré son nom. Il vaut l’un des suivants :
- l’utilisateur a annulé :
CANCELED_WHILE_COUNTDOWN,CANCELED_WHILE_CAPTURING,CANCELED_WHILE_SENDING,CANCELED_WHILE_PROCESSING; - la capture a été interrompue :
WIDGET_RESIZED,FOCUS_LOST,VIDEO_SOURCE_ENDED; - les contrôles que le module mène pendant la capture :
CONFORMITY_POOR_LIGHT,CONFORMITY_MUCH_VARIATIONS,CONFORMITY_LOW_FPS; - l’échange avec les serveurs :
CREATE_MEASURE_ERROR,WS_CONNECTION_ERROR,UNEXPECTED_WS_RESULT.
Les codes que calcule le serveur — CONFORMITY_FACE_PRESENCE, CREDIT_EXCEEDED, MISSING_USER_DATA_* et les autres — ne passent jamais par aborted. Ils arrivent dans l’événement result, comme error d’une variable. CONFORMITY_POOR_LIGHT, CONFORMITY_MUCH_VARIATIONS et CONFORMITY_LOW_FPS existent aussi côté serveur : quand c’est le contrôle du serveur qui refuse une mesure, ils arrivent dans result, comme error d’une variable, et non par aborted.
transition n’est jamais émis
transition figure dans le tableau ci-dessus parce que le type d’événement du module le déclare. Rien dans le module n’en construit. N’y bâtissez pas un suivi de navigation.Dans un événement result, chaque variable vaut { value, error: null } en cas de succès, ou { value: null, error } en cas d’échec ; le résultat décrit la forme de chaque value. userData n’est présent que si un identifiant externe a été donné, et ne porte alors que { externalId }.
Le formulaire de fin
Après l’écran des résultats, le widget peut afficher un formulaire de fin : une note, une remarque et — quand bp figure parmi les variables rendues, quelle que soit sa valeur — les lectures de référence, la tension entre autres, dont la calibration de bp a besoin pour une personne identifiée par un externalId. Sans bp, c’est pages.finalForm qui décide : { version: "1" } montre les lectures, { version: "2" } la note et la remarque seules, et sans lui il n’y a pas de formulaire. Le widget envoie lui-même le formulaire à Saphere, une fois par mesure : un second envoi, ou un envoi fait plus d’un jour après la fin de la mesure, est refusé. L’événement result est émis avant cet écran, si bien qu’une page qui démonte le widget dès result ne le montre jamais.
L’apparence : écrans et couleurs
L’apparence du widget gagne à ne pas être écrite dans votre code. Elle se prépare dans la console ops, avec l’atelier de personnalisation, et s’attache au widget par son identifiant.
Chaque personnalisation est listée sous Scan tools → Scan customization, avec l’identifiant que vous utiliserez. En la créant, réglez Widget version sur v1 : la valeur par défaut est v2, et l’identifiant d’une personnalisation v2 n’applique rien à ce module.

En ouvrir une donne l’atelier. Un widget en fonctionnement se tient à côté des réglages, de sorte que ce que vous approuvez est ce que vos utilisateurs verront.
Colors — la palette que le widget s’applique.

Pages — les écrans que le parcours comporte, ceux qu’il laisse de côté, et le logo affiché en tête.

Une fois la personnalisation enregistrée, ajoutez son identifiant à l’adresse depuis laquelle vous chargez le module :
<script src="https://cdn.saphere.ai/saphere-scan/v1/js/main.min.js?customizationId=8f1c2d34-5a6b-4c7d-8e9f-0a1b2c3d4e5f"></script>
Le module arrive en la portant déjà. Rien ne change dans votre code, et modifier la personnalisation plus tard prend effet au chargement suivant, sans aucun déploiement de votre côté. Ce que vous passez dans colors, pages ou texts l’emporte toujours sur elle.
Préparez-la dans l’environnement où vous chargez
Une personnalisation enregistrée sur le Test n’est pas le même enregistrement qu’une personnalisation enregistrée en Production : son identifiant ne s’y transpose pas. Préparez-la là où vous l’utiliserez.