Migrer depuis la v1

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 côté serveur. Le même compte, les mêmes mesures, les mêmes variables. Ce qui change est le code de votre page.

Les cinq changements, dans l’ordre

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.

2. L’habilitation

C’est le changement qui demande votre serveur, et la raison d’être de la v2.

En v1, votre point d’entrée créait une mesure et rendait son identifiant. Cet identifiant ouvrait la session de mesure.

En v2, votre point d’entrée délivre un jeton d’accès : valable peu de temps, utilisable une fois, et ne portant que l’autorisation de conduire une mesure. 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’entrée 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.

Les stratégies gardent leurs noms et leur sens : delegate pour que le widget appelle votre point d’entrée, handle pour que votre propre code obtienne la valeur. Les jetons d’accès décrivent ce que votre point d’entrée doit appeler.

3. Les événements

La v1 rapportait six événements ; la v2 en rapporte quarante et un, et aucun des anciens noms ne survit. La nomenclature est désormais domaine:événement : ready est devenu widget:ready, result est devenu measure:result, 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 annulait un changement d’écran — 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, où il est borné par un délai de garde.

4. Les options qui changent de nom

5. Ce qui ne change pas

La mesure elle-même. Les mêmes trente secondes, les mêmes conditions, les mêmes variables, la même forme de résultat. Un utilisateur qui compare les deux versions voit une interface différente, non une mesure différente.

Votre personnalisation non plus : écrans, couleurs et textes se préparent dans le même atelier de la console pour les deux versions.