Charger le module
Les URL du CDN, les deux variantes de build, et l’API Handler complète.
Une nouvelle intégration devrait utiliser Saphere Scan v2. Ce qui suit documente le module v1 pour les produits qui le font déjà tourner.
Les deux builds
Le même widget est publié deux fois, et celui que vous chargez décide de la façon dont vous l’atteignez.
| Build | URL | Comment obtenir Handler |
|---|---|---|
| Script classique | https://cdn.saphere.ai/saphere-scan/v1/js/main.min.js | window.Handler, ou l’événement handler-ready |
| Module ES | https://cdn.saphere.ai/saphere-scan/v1/mjs/main.min.js | import { Handler } from … |
Les deux acceptent un paramètre de requête facultatif ?customizationId=<uuid>, qui applique une personnalisation configurée dans la console avant que vos propres options ne soient fusionnées par-dessus. La valeur doit être un UUID de version 4 : toute autre valeur fait refuser la requête par le CDN, et le script ne se charge pas. Un identifiant qui ne désigne aucune personnalisation v1 n’est pas une erreur — le module se charge sans personnalisation.
Deux adresses plus anciennes servent encore le même module : /saphere-scan/js/main.min.js et /modules/M1/<version>/js/main.min.js, avec leurs pendants mjs. Elles sont dépréciées ; passez aux chemins /saphere-scan/v1/ ci-dessus.
Les URL ci-dessus sont celles de la Production. Seul l’hôte change d’un environnement à l’autre ; les chemins sont identiques :
| Environnement | Base du CDN |
|---|---|
| Production | https://cdn.saphere.ai |
| Test | https://cdn.test.saphere.ai |
Comme en v2, c’est le CDN depuis lequel vous chargez qui décide de l’environnement contre lequel le module travaille. Environnements couvre le reste.
Le build en module ES
À préférer lorsque vous maîtrisez la page et pouvez utiliser des modules.
<script type="module">
import { Handler } from "https://cdn.saphere.ai/saphere-scan/v1/mjs/main.min.js"
Handler.load("#container", options)
</script>
Le build classique
Pour les pages qui ne peuvent pas utiliser de modules — une coquille Ionic, par exemple, où le script se trouve dans le gabarit de l’application.
<script src="https://cdn.saphere.ai/saphere-scan/v1/js/main.min.js"></script>
Le paquet pose window.Handler puis émet un événement handler-ready sur window.
Lisez la variable globale, ou attendez l’événement — pas l’un sans l’autre
window.Handler n’est défini qu’une fois le script exécuté, et handler-ready n’est émis qu’une fois, à ce moment-là. Une balise <script> ordinaire s’exécute avant le code qui la suit : la variable globale est alors déjà là, et un écouteur ajouté ensuite ne se déclenche jamais. Un script chargé en async, injecté à l’exécution ou chargé par un cadriciel peut s’exécuter plus tard, et la variable n’est alors pas encore là. Traitez les deux cas :
const mount = Handler => Handler.load("#container", options)
if (window.Handler)
mount(window.Handler)
else
window.addEventListener("handler-ready", ({ detail: { Handler } }) => mount(Handler), { once: true })
L’événement porte Handler dans son detail, de sorte que la seconde branche n’a pas besoin de la variable globale.
L’API Handler
Tout y est statique. Il y a un widget par page.
Handler.load(target, options)
Monte le widget. Ne rend rien.
| Paramètre | Accepte |
|---|---|
target | Une chaîne de sélecteur CSS, ou un HTMLDivElement |
options | L’objet d’options — voir Options |
Le contenu du conteneur est remplacé. Donnez-lui une hauteur, car le widget le remplit.
Lève :
| Message | Cause |
|---|---|
SaphereScan is already loaded. | Un widget est déjà monté. Appelez destroy() d’abord, ou utilisez reload(). |
Module must be loaded in an HTMLDivElement | Le sélecteur n’a rien trouvé, ou a trouvé autre chose qu’un div. |
Bad integrator module options! | Vos options ont échoué à la validation. Le détail est écrit dans la console. |
Bad module options! | Les options fusionnées ont échoué à la validation : createMeasure absent ou incomplet, une clé de premier niveau inconnue, ou une personnalisation en conflit avec vos options. |
Lisez la console quand des options sont refusées
Les deux erreurs d’options écrivent la sortie de validation complète avant de lever. Le message levé seul ne dit pas quel champ était fautif ; l’entrée de console, si.Handler.destroy()
Asynchrone. Démonte le widget, vide le conteneur et libère la caméra.
await Handler.destroy()
Sans risque lorsque rien n’est monté — la fonction rend la main immédiatement.
Handler.reload(target, options)
Asynchrone. Équivaut à await destroy() puis load(...). C’est ainsi qu’on relance une mesure, ou qu’on applique de nouvelles options.
Accesseurs
| Accesseur | Type | Valeur |
|---|---|---|
Handler.isLoaded | boolean | Si un widget est actuellement monté |
Handler.langs | string[] | ["ar","de","en","es","fr","it","pl","pt","pt_BR","tr"] |
Handler.defaultModuleOptions | object | Les valeurs par défaut, avant fusion des vôtres |
Handler.isMobile | boolean | La détection d’appareil — l’estimation propre du widget, qu’une option isMobile remplace à l’intérieur du widget |
Handler.isMobile est utile pour la mise en page. Sur un navigateur de bureau, on veut en général contraindre le widget à une colonne au format téléphone plutôt que de le laisser occuper toute la largeur.
Une page complète
<!doctype html>
<html lang="fr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, height=device-height, initial-scale=1, minimum-scale=1, maximum-scale=1, user-scalable=0">
<title>Saphere Scan v1</title>
<style>
html, body { padding: 0; margin: 0; overflow: hidden; }
#container { height: 100vh; }
/* Sur un navigateur de bureau, garder le widget dans une colonne au format téléphone. */
#container:not(.mobile) { aspect-ratio: 9 / 16; margin: auto; }
</style>
</head>
<body>
<div id="container"></div>
<script type="module">
import { Handler } from "https://cdn.saphere.ai/saphere-scan/v1/mjs/main.min.js"
const container = document.getElementById("container")
const options = {
createMeasure: {
// Votre serveur crée la mesure et rend { id }.
// Ne placez jamais une clé d'API dans une page — voir l'avertissement ci-dessous.
strategy: "delegate",
url: "/api/saphere-measure"
},
onEvent: event => {
console.log(event.type, event)
if (event.type === "result")
console.log("variables:", event.variables)
},
allowLeave: true,
lang: "fr"
}
if (Handler.isMobile)
container.classList.add("mobile")
Handler.load(container, options)
</script>
</body>
</html>
La clé d’API n’a pas sa place dans la page
Les exemples v1 publiés montrent headers: { Authorization: "Bearer <apiKey>" } écrit directement dans la page. Cela place une habilitation qui ouvre tout votre compte, et qui vaut jusqu’à ce qu’on la révoque dans la console ou qu’elle atteigne son dernier jour, dans tout ce qui peut lire votre JavaScript.
Pointez createMeasure.url vers un point d’accès de votre propre serveur, authentifiez-y votre utilisateur, et faites appeler l’API Saphere par ce point d’accès avec la clé. Voir Options pour les deux stratégies.
Servez la page en HTTPS ou depuis localhost. Les navigateurs refusent l’accès à la caméra sur une origine non sécurisée.