Migrer depuis la v1
Ce qui change entre le module v1 et Saphere Scan v2, dans l’ordre où vous le rencontrerez.
La version 2 est un module distinct plutôt qu’une mise à jour de la version 1. Une intégration ne migre pas d’elle-même : vous remplacez le script, renommez quelques options, et adaptez la façon d’obtenir une habilitation.
Rien ne change du côté de Saphere. Le même compte, les mêmes mesures, les mêmes variables. Ce qui change est le code de votre page, et celui de votre propre point d’accès, celui que le widget appelle.
Ce qui change, dans l’ordre
| v1 | v2 | |
|---|---|---|
| Le script | Un script classique, ou un module ES, depuis /saphere-scan/v1/… | Un module ES, depuis /saphere-scan/v2/main.js |
| Le montage | Handler.load("#container", options) | SaphereScan.create("#container", options) puis bootstrap() |
| L’habilitation | Votre point d’accès crée une mesure et rend son identifiant | Votre point d’accès délivre un jeton d’accès de courte durée |
| Les événements | Huit noms, et votre gestionnaire, attendu, pouvait retenir le widget | Quarante-quatre noms, jamais attendus, et le refus est passé aux hooks |
| L’apparence | Préparée dans la console | Préparée dans la même console, comme personnalisation v2 |
1. Le script et le montage
<!-- v1 -->
<script src="https://cdn.saphere.ai/saphere-scan/v1/js/main.min.js"></script>
<script>
Handler.load("#scan", options)
</script>
<!-- v2 -->
<script type="module">
import SaphereScan from "https://cdn.saphere.ai/saphere-scan/v2/main.js"
const instance = SaphereScan.create("#scan", options)
await instance.bootstrap()
</script>
Deux différences derrière cela. create() rend une instance au lieu d’agir sur un objet global, de sorte que plusieurs widgets peuvent coexister sur une même page. Et le montage se fait désormais en deux temps : create() valide vos options tout de suite et lève si quelque chose ne va pas, bootstrap() met le widget à l’écran.
Le contrat du conteneur est le même : vous donnez un div qui a une hauteur, le widget le remplit, et il garde ses styles pour lui.
L’API Handler se transpose ainsi :
| v1 | v2 |
|---|---|
Handler.load(target, options) | SaphereScan.create(root, options), puis await instance.bootstrap() |
await Handler.destroy() | instance.destroy(), synchrone et appelable à tout moment |
Handler.reload(target, options) | instance.setOptions(options) pour appliquer de nouvelles options sans remonter le widget ; pour repartir de zéro, destroy(), puis de nouveau create() et bootstrap() |
Handler.defaultModuleOptions | SaphereScan.describeDefaults() |
Handler.isLoaded, Handler.langs, Handler.isMobile | Aucun équivalent |
2. L’habilitation
C’est le changement qui demande votre serveur, et la raison d’être de la v2.
En v1, votre point d’accès créait une mesure et rendait son identifiant. Cet identifiant ouvrait la session de mesure.
En v2, votre point d’accès délivre un jeton d’accès : valable pour la durée que vous choisissez — 48 heures au plus —, n’ouvrant pas plus de sessions de mesure que vous n’en autorisez — une, d’ordinaire —, et ne portant que l’autorisation de mesurer. Votre clé d’API reste sur votre serveur dans les deux versions, mais un jeton qui fuit ne vaut presque rien, là où un identifiant de mesure valait une mesure entière.
// v1
createMeasure: { strategy: "delegate", url: "/api/saphere-measure" }
// v2
proxy: { retrieveAccessToken: { strategy: "delegate", url: "/api/saphere-token" } }
Ce que votre point d’accès ne porte plus, c’est la mesure elle-même. En v1 vous la décriviez dans le corps de l’appel qui la créait ; en v2 c’est une option du widget, createMeasureOptions, où vont les données patient que vous détenez déjà. Le jeton autorise ; l’option décrit.
En v2, la mesure n’existe pas avant la capture : le serveur la crée une fois la capture reçue, de sorte que son identifiant n’est pas connu avant la fin. Le widget ne le rapporte que dans measure:result, sous event.result.id ; pour rattacher une mesure à vos propres enregistrements, mettez un externalId (dans userData) ou des tags dans createMeasureOptions.
Les stratégies gardent leurs noms et leur sens, non leur contrat : delegate reste le widget qui appelle votre point d’accès, handle votre propre code qui obtient la valeur. delegate envoyait { userData, desiredVariables, tags } et lisait { id } ; il envoie maintenant { measurement: "scan" | "realtime" } avec le body que vous déclarez, le cas échéant, et lit la value du jeton (ou une chaîne nue) ; l’id du jeton n’ouvre rien. handle recevait { userData, desiredVariables, tags } et rendait { id } ; il reçoit maintenant l’AbortSignal de la tentative, puis { measurement }, et rend le jeton (une chaîne, ou un objet portant value). Les jetons d’accès décrivent ce que votre point d’accès doit appeler.
3. Les événements
La v1 déclarait huit événements — dont un, transition, jamais émis en réalité ; la v2 en rapporte quarante-quatre, et aucun des anciens noms ne survit. La nomenclature est désormais domaine:événement : result est devenu measure:result, start est devenu placement:accepted, et ainsi de suite. La liste complète, avec une table de correspondance v1 vers v2, est dans les événements.
Un comportement a déménagé plutôt que d’être renommé. En v1, votre gestionnaire onEvent était attendu, et rendre false empêchait le widget de passer à l’étape suivante — ce qui permettait à un gestionnaire lent de retenir l’interface. En v2, onEvent n’est jamais attendu, et le pouvoir de refuser est passé aux hooks, réduit à deux points — un changement d’écran et le départ d’une mesure — et borné par un délai de garde.
4. Les options qui changent de nom
| v1 | v2 |
|---|---|
createMeasure | proxy.retrieveAccessToken |
onEvent | Même nom, jamais attendue, retour ignoré — voir plus haut |
allowLeave | Disparue : la v2 n’offre aucune commande pour quitter le widget ; votre page décide quand l’arrêter par destroy() |
allowSkip | Disparue en tant que lien offert à l’utilisateur ; les écrans de consignes que le parcours comporte relèvent de la personnalisation |
colors, texts, pages | Relèvent de la personnalisation, dans la console ; dans le code, sous components |
isMobile | Disparue |
useShadow | Disparue ; le widget garde toujours ses styles pour lui |
lang | Inchangée |
desiredVariables, tags | Inchangées, et désormais rejointes par createMeasureOptions |
5. Ce qui ne change pas
La mesure elle-même. Les mêmes trente secondes, les mêmes variables, la même forme pour chaque valeur. Un utilisateur qui compare les deux versions voit une interface différente, non une mesure différente.
L’endroit où se prépare l’apparence ne change pas non plus : écrans, couleurs et textes se préparent dans le même atelier de la console pour les deux versions. Une personnalisation, elle, est rattachée à une version du widget — une personnalisation v1 n’est pas appliquée par le module v2, et son identifiant sur l’adresse v2 n’apporte rien. Préparez une personnalisation v2, et attachez son identifiant comme le décrit la personnalisation.
Trois choses autour de la mesure diffèrent pourtant :
- La tension. Le formulaire de fin de la v1 est ce qui enregistre la lecture de référence sur laquelle
bpest calibrée ; la v2 n’a pas de tel formulaire. Une personne déjà calibrée garde sa calibration — envoyez le mêmeexternalIddanscreateMeasureOptions— tandis quebprevient avecNOT_CALIBRATEDpour une personne pas encore calibrée. - La lumière, le mouvement et la cadence. La v1 les juge sur l’appareil et arrête la mesure (
abortedavecCONFORMITY_POOR_LIGHT,CONFORMITY_MUCH_VARIATIONSouCONFORMITY_LOW_FPS) ; la v2 ne s’arrête jamais sur elles : la capture va à son terme et le verdict revient dansmeasure:result, commeerrord’une variable. - Le résultat. La v1 donne
event.idetevent.variables, avecevent.userDataréduit à{ externalId }; la v2 donne toute la mesure sousevent.result.
Faites tourner les deux côte à côte
Rien n’empêche un compte de servir la v1 sur une page et la v2 sur une autre, en même temps. C’est la façon la plus sûre de migrer : posez la v2 sur un seul parcours, comparez, puis déplacez le reste.La v2 est en bêta
Vérifiez avec i-Virtual où elle en est pour votre compte avant de planifier une migration complète.