Personnalisation

Vous ne décrivez pas l’apparence du widget dans votre code. Vous préparez une personnalisation dans la console ops, et vous l’attachez au widget par son identifiant.

Cette séparation est le but recherché. Les personnes qui décident de l’allure du widget sont rarement celles qui déploient la page, et un changement de palette ne devrait pas demander une livraison.

1. Créer une personnalisation dans la console

Dans la console ops, l’atelier de personnalisation permet de préparer et de prévisualiser ce que le widget affichera. Pour une personnalisation v2, il couvre la quasi-totalité de la surface, écran par écran :

Le contenu d’un écran est un arbre d’éléments — conteneurs, paragraphes, textes, images, liens. On y ajoute un enfant, on le déplace, on le duplique, on change son type, on règle ce qu’il porte. L’atelier ne propose que ce que le widget accepte à cet endroit : un arbre construit là est un arbre que le widget affichera.

Trois choses restent telles que le widget les livre : les trois documents du menu — notice d’utilisation, conditions d’utilisation, politique de confidentialité —, qui sont le texte propre du fabricant ; les noms des langues dans le panneau des langues, chacun écrit dans sa propre langue ; et la courte ligne d’état sous le cadre, sur l’écran de placement.

Un widget en fonctionnement se tient à côté des réglages, sur l’écran même que vous éditez — tous les écrans, y compris ceux qu’aucun réglage n’atteint : le résultat, les deux fins anormales et les cinq refus de la caméra sont montrés avec des données fabriquées, de sorte que leur apparence se juge sans avoir à les provoquer. Ce que vous validez est ce que vos utilisateurs verront, et le widget refuse de démarrer sur un arbre qu’il ne saurait pas afficher, ce qui est la façon dont une erreur se voit avant d’être enregistrée. Le même atelier sert aux deux versions du widget ; la page v1 montre celui de la v1 en images.

À côté de cette vue écran par écran, l’aperçu montre aussi le widget entier, tel qu’un intégrateur le monte : les commandes fonctionnent, le parcours se déroule de bout en bout, et une mesure peut y être prise. C’est ce vers quoi on va pour juger un enchaînement plutôt qu’un écran — au prix que chaque modification recharge le widget, donc reprend le parcours à son début.

Une personnalisation appartient à votre compte, porte un nom et une description, et est rattachée à une version du widget. Plusieurs peuvent coexister : une par produit, par marque, par campagne.

2. L’attacher au widget

Ajoutez son identifiant à l’adresse depuis laquelle vous chargez le widget.

<script type="module">
    import SaphereScan from "https://cdn.saphere.ai/saphere-scan/v2/main.js?customizationId=8f1c2d34-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
</script>

Rien d’autre ne change dans votre intégration : même appel, mêmes options, mêmes événements. Le widget est servi en portant déjà la personnalisation.

Un identifiant qui ne désigne aucune personnalisation v2 sur cet environnement — une personnalisation préparée sur l’autre environnement, une autre préparée pour le widget v1, une faute de frappe — n’est pas une erreur : le widget est servi avec ses propres défauts, sans rien signaler. Une valeur qui n’est pas du tout un identifiant fait répondre une erreur à l’adresse, et l’import échoue. Pour savoir ce que porte une adresse donnée, importez depuis elle et appelez describeDefaults().

Elle se comporte comme une charge d’options partielle, posée entre les défauts du widget et les vôtres : ce qu’elle ne dit pas reste au défaut, et ce que vous passez à create() ou à setOptions() l’emporte sur elle. C’est ce qui permet de laisser une personnalisation décider de l’apparence tout en gardant la main, dans le code, sur ce qui dépend de l’utilisateur.

Ce qui reste dans votre code

Certains réglages relèvent de l’intégration et non de l’apparence, et restent donc dans les options que vous passez à create(). Vos options s’appliquent en dernier : partout où elles et la personnalisation disent quelque chose, ce sont les vôtres qui l’emportent.

Modifier une personnalisation

Modifiez-la dans l’atelier. Le widget reprend la nouvelle version au chargement suivant, sans aucun déploiement de votre côté, puisque l’identifiant dans votre page ne change pas.

C’est aussi pourquoi une personnalisation mérite d’être relue avant d’être enregistrée : elle prend effet pour tous ceux qui utilisent cet identifiant.

Partir de ce que le widget livre

L’atelier part des contenus par défaut du widget plutôt que d’une page blanche, et ne garde que ce que vous avez changé : ce que vous laissez tel quel suit le widget et ses évolutions, ce que vous éditez reste comme vous l’avez laissé.

Si vous construisez votre propre outillage, le même point de départ s’obtient depuis le module :

import SaphereScan from "https://cdn.saphere.ai/saphere-scan/v2/main.js"

// ce que le widget appliquerait sans rien lui passer : toute l'arborescence des options, en JSON
const defaults = SaphereScan.describeDefaults()

// ce qu'il appliquerait pour les options envisagées, sans rien monter
const resolved = SaphereScan.describeDefaults({ components: { onboarding: { onboarding3: { ignore: false } } } })

La résolution est exactement celle de create(), personnalisation comprise : chargé depuis une adresse portant un customizationId, le module décrit ce que ce bundle appliquerait, et non les défauts nus. Elle lève sur des options que le widget refuserait — de quoi vérifier une charge avant de la livrer. Deux choses n’en ressortent pas : tout ce qui est une fonction — onEvent, les hooks, le fetch d’une stratégie handle, un createMeasureOptions écrit en fonction —, et les dessins que le widget embarque, qui sont du code et non des données.