Intégrer le configurateur dans votre boutique

Le configurateur se résume à un script et un élément HTML. Vous n’installez rien sur votre serveur pour l’intégrer. Tout ce qui suit peut être répété dans un sandbox avant la mise en production.

Le code

La catégorie Embedding code de la console écrit l’extrait pour vous sous la forme que vous choisissez : HTML simple (quatre variantes), WordPress, un bouton SKU WooCommerce, ou un lien autonome avec un code QR. Sa forme est la suivante :

<script type="module" src="https://cfg.cutoptim.com/embed/assets/latest/cutoptim-configurator.js"></script>

<cutoptim-configurator mode="inline" key="YOUR_PUBLISHABLE_KEY"
  api="https://cfg.cutoptim.com" lang="en"></cutoptim-configurator>

La clé, l’adresse du service et la langue proviennent de votre console. Une fenêtre contextuelle ou un panneau latéral utilise un bouton pour l’ouvrir :

<button data-cutoptim-open="#cut" data-material="MDF-18">Cut this board to size</button>
<cutoptim-configurator id="cut" mode="modal" key="YOUR_PUBLISHABLE_KEY"
  api="https://cfg.cutoptim.com" lang="en"></cutoptim-configurator>

Modes et attributs

Attribut	Signification
`mode`	`inline` (par défaut), `modal` (fenêtre contextuelle) ou `drawer` (panneau latéral)
`key`	votre clé publiable
`lang`	la langue côté client
`material`	un panneau de votre catalogue, par identifiant ou nom exact ; le parcours démarre alors sur la liste de coupe
`thickness`	restreint `material` en millimètres ; seul, il ne sélectionne rien
`template`	un modèle de meuble pour démarrer
`start`	`catalog`, `cutlist` ou `template`
`project`	un projet enregistré à charger
`customer-token`	votre propre référence opaque du client connecté, jusqu’à 128 caractères
`width`, `height`	la taille du conteneur hôte, en longueurs CSS simples

Une fenêtre contextuelle ou un panneau latéral ne charge rien avant sa première ouverture, si bien qu’une grille de produits comptant de nombreux boutons reste légère. Plusieurs configurateurs sur une même page fonctionnent de façon indépendante. Un attribut à la valeur invalide est ignoré, jamais appliqué à moitié.

Depuis un script, l’élément propose open(), close(), setMaterial(), loadProject() et setCustomerToken(). Il émet des événements sur lui-même : cutoptim:ready, step, quote, order, project, error, open et close.

Page autonome, QR et iframe

Le même configurateur peut fonctionner comme une page à part entière : faites un lien vers elle, imprimez le code QR pour un comptoir de magasin ou une borne, ou envoyez-la à un client. Une page qui ne peut pas charger de script peut afficher cette page dans une iframe ; seuls les domaines que vous listez peuvent l’afficher, et les messages entre l’iframe et votre page ne sont acceptés que de ces domaines.

Domaines autorisés

La clé publiable ne fonctionne que depuis les domaines listés pour elle. Vous listez les domaines de votre boutique, y compris un éventuel domaine de préproduction, lorsque vous créez la clé dans la catégorie Keys & embedding ; une requête provenant de toute autre origine est refusée.

Habillage de marque

Les couleurs, le rayon des angles, la typographie, le mode clair ou sombre et tous les textes visibles par le client, en dix langues, se règlent dans la console et s’appliquent sans modifier votre page. La page peut aussi styliser des parties du widget grâce aux sélecteurs CSS ::part.

Une version épinglée, avec intégrité

Par défaut, l’extrait charge le build mobile latest. Lorsque le service conserve les versions, la console peut proposer à la place un extrait épinglé : une version numérotée précise avec un hachage integrity, de sorte que le navigateur refuse un fichier qui a été modifié. Une variante plus stricte épingle aussi les parties chargées à la demande. Les versions sont signées, une version publiée ne change jamais, et une version antérieure reste disponible pour que vous puissiez l’épingler aussi longtemps que nécessaire. Pour une Content Security Policy stricte, la console affiche les directives à autoriser. Les extraits épinglés supposent que le service conserve les versions ; d’ici là, la console ne propose que l’extrait mobile.

Projets enregistrés

Un client peut enregistrer une liste de coupe et y revenir. Le premier enregistrement crée un jeton privé que le navigateur conserve ; par défaut, un projet n’est donc disponible que sur ce navigateur. Il n’y a pas de synchronisation entre appareils basée sur une connexion, et le client ne peut pas supprimer un projet enregistré ; les projets non commandés sont effacés après votre durée de conservation.

Retour vers votre panier

Lorsque le client commande, le configurateur émet l’événement de commande sur votre page. Sur la page autonome, il peut aussi renvoyer le client vers votre boutique après une commande réussie : vous définissez une adresse de retour (https uniquement, sur votre propre domaine) et le client voit une brève confirmation avec un bouton Back to the shop. Le prix ne doit jamais être repris du navigateur ni de l’adresse de retour : votre serveur vérifie d’abord le devis. La marche à suivre se trouve sur la page des commandes ; un plug-in prêt à l’emploi pour WooCommerce est sur sa propre page et le code de référence pour toute autre boutique est sur la page des plateformes sur mesure.

FAQ

Que dois-je coller dans ma page ?

Une balise script qui charge le configurateur et un élément cutoptim-configurator portant votre clé publiable. La console génère les deux pour vous dans Embedding code, sous la forme que vous choisissez. La clé publiable est faite pour figurer dans la page ; la clé secrète n’y figure jamais.

Quelles façons de l’afficher existe-t-il ?

Quatre : intégré dans la page (inline), en fenêtre contextuelle (modal), en panneau latéral (drawer), ou comme page autonome à part entière vers laquelle vous faites un lien ou que vous affichez sous forme de code QR. Une page qui ne peut pas charger de script peut intégrer la page autonome dans une iframe.

Le bouton d’une fiche produit peut-il ouvrir le configurateur avec le panneau de ce produit déjà choisi ?

Oui. Placez data-cutoptim-open sur un bouton, et data-material (et éventuellement data-thickness) avec l’identifiant ou le nom exact du panneau. Le configurateur démarre alors sur la liste de coupe avec ce panneau sélectionné. Un panneau qui n’existe pas dans votre catalogue ne sélectionne rien.

N’importe qui peut-il placer mon configurateur sur son propre site ?

Non. Les requêtes portant votre clé publiable ne sont acceptées que depuis les domaines de la liste autorisée de la clé, et l’iframe ne peut être affichée que par ces domaines. Une page sur tout autre domaine reçoit un refus.

Que signifie épingler une version ?

Chaque build du configurateur est publié comme une version numérotée et immuable, avec un hachage d’intégrité pour chaque fichier. La console peut vous fournir un extrait qui pointe vers une version précise et porte le hachage, de sorte que le navigateur refuse un fichier modifié. L’alternative est le canal mobile latest, qui sert toujours le build le plus récent et n’a pas de hachage. Les extraits épinglés sont proposés lorsque le service conserve les versions.

Comment ma page apprend-elle que le client a commandé ?

L’élément émet des événements, dont un événement cutoptim:order avec l’identifiant de la commande et la commande signée. Considérez-le comme une simple notification : votre serveur doit vérifier le devis et récupérer la commande auprès de CutOptim avant d’encaisser quoi que ce soit. Voir la page des commandes.