Référence de l'API JavaScript (V3)

Cette référence décrit chaque méthode, chaque événement et chaque paramètre que le moteur frontend V3 met à disposition sur window.Configento – avec signature, valeur renvoyée, cas d'erreur et un court exemple. Elle s'adresse aux développeurs de thèmes de boutique, de plugins et d'intégrations personnalisées. Le guide Interface JavaScript (V3) montre comment résoudre les tâches courantes et migrer depuis du code Legacy.

Les signatures sont écrites en notation TypeScript. Tout fonctionne aussi en JavaScript pur.

Cycle de vie

1. La page charge https://cloud.configento.app/configento-v3/configento.js (avec defer).
2. Le script crée window.Configento, recherche une seule fois tous les éléments portant data-configento et enregistre une instance pour chacun. Son id est l'id de l'élément, sinon configento-anon-<n>.
3. Pour chaque instance, le chargement du composant démarre aussitôt (ou le composant intégré est utilisé, voir component).
4. Dès qu'un composant est chargé, son instance reçoit les méthodes ci-dessous. Avant, elles lèvent Configento instance not ready — await Configento.ready first.
5. Configento.ready est résolue lorsque toutes les instances de la page sont chargées.

Les éléments qui n'arrivent dans la page qu'après l'étape 2 ne sont pas reconnus. Une référence d'instance reste valable pendant tout le chargement : si vous détenez Configento.instances.get(id) avant ready, le même objet reçoit ensuite les vraies méthodes.

Global : window.Configento

Propriété / méthode	Type	Description
version	string	Version du moteur, p. ex. 3.0.0-alpha.0
frontendVersionTag	'v3'	Identifiant de la génération du moteur. Testez cette valeur, et non version, si votre code ne fonctionne qu'avec une génération.
ready	Promise<void>	Résolue lorsque toutes les instances sont chargées
instances	ReadonlyMap<string, ConfiguratorInstance>	Toutes les instances, la clé étant l'id de l'instance
first()	ConfiguratorInstance ou null	La première instance de la page
forElement(el)	(el) => ConfiguratorInstance (ou null) ; el est un HTMLElement ou une string	L'instance correspondant à un élément ou à un sélecteur CSS ; cherche aussi vers l'extérieur (closest('[data-configento]'))
loadAsset(id, opts?)	(id: string, opts?: { instance?: ConfiguratorInstance }) => Promise<AssetPayload>	Lit une configuration enregistrée, voir Enregistrer et charger
setModalAdapter(adapter?)	(adapter?: ModalAdapter) => void	Fenêtre personnalisée pour les images en grand format, voir Adaptateur de fenêtre modale
CloudError	Classe	Classe d'erreur de storeAsset() et loadAsset(), voir CloudError

window.addEventListener('DOMContentLoaded', async () => {
  await Configento.ready;
  const k = Configento.forElement('#product-form');
});

Instance : ConfiguratorInstance

Propriétés (lecture seule) :

Propriété	Type	Description
id	string	id de l'instance
componentId	string ou null	ID du composant
element	HTMLElement	L'élément portant data-configento
config	WebshopConfig ou null	Les paramètres au chargement, figés – voir Intégration

Vous indiquez les caractéristiques par leur nom interne (string) ou leur ID numérique (CharacteristicRef), les valeurs par le champ Valeur (string) ou leur ID numérique (ValueRef). Un nom inconnu, une valeur inconnue ou un type de donnée inadapté lève une Error.

Lire

getValue(characteristic): unknown

Valeur d'une caractéristique sous la forme que voient aussi les formules :

Caractéristique	Résultat	Vide
Sélection, boutons radio, liste avec images	Champ Valeur de l'entrée choisie (sans valeur : son ID)	null
Sélection multiple, case à cocher	Liste des valeurs	[]
Champs de saisie	Texte, sans espaces en début et en fin	''
Sélection multiple avec quantités	{ [ID de valeur]: quantité }	{}
Formule, liste de prix, combinaison, attribut de produit, service web	Résultat du calcul	null

Une caractéristique qu'une règle masque renvoie toujours « vide ».

k.getValue('largeur');      // → '120'
k.getValue('accessoires');  // → ['manivelle', 'telecommande']

getSelections(): SelectionsMap

La sélection actuelle de toutes les caractéristiques sous la forme { [ID de caractéristique]: sélection } – voir Sélection. Les caractéristiques qu'une règle masque n'y figurent pas ; les valeurs bloquées sont retirées.

getState(): ConfiguratorSnapshot

{
  selections: SelectionsMap;                     // comme getSelections()
  evaluated: Record<number, number | string | null>;  // résultats de tous les calculs par ID de caractéristique
  hiddenCharacteristics: number[];               // caractéristiques masquées par des règles
  blacklistedValues: number[];                   // valeurs bloquées par des règles
  price: PriceSnapshot;                          // comme getPriceBreakdown()
}

Simple requête – peut être appelée aussi souvent que nécessaire.

getPriceBreakdown(): PriceSnapshot

{ total: number; currency: string; priceIncludesTax: boolean }

total est déjà converti selon le taux de taxe et la devise de la boutique (data-configento-tax-rate, data-configento-currency).

getSummary(opts?): string

Option	Par défaut	Effet
format	'text'	'html' renvoie <dl><dt>Caractéristique</dt><dd>Valeur</dd>…</dl>
includePrices	false	Supplément après la valeur
separator	'; '	Séparateur au format texte

Ne contient que les caractéristiques visibles. Si le composant affiche la référence combinée dans le récapitulatif, elle figure à la fin.

k.getSummary({ format: 'html', includePrices: true });

getCombinedSku(): string

Référence du produit configuré à partir des numéros d'article des valeurs choisies, reliés par -, p. ex. CL-W-GR-TXT. Pour chaque caractéristique, dans l'ordre du composant : le numéro d'article de la valeur choisie (pour une sélection multiple, le premier disponible), sinon celui de la caractéristique. Les parties vides sont omises, les caractéristiques masquées ne comptent pas. '' si rien ne porte de numéro d'article. Si elle n'est pas vide, elle figure aussi sous _combined_sku dans chaque payload de commande.

getAssetPayload(): AssetPayload | null

La configuration en JSON, classée par noms internes – la même forme que finalize().payload, mais sans vérification. null tant que rien n'est sélectionné. Outre les caractéristiques, elle contient _component_title, _locale, le cas échéant _combined_sku et – pour les composants avec Captcha – altcha.

getHeaderValue(opts?): string | null

La même configuration encodée en Base64 (compatible UTF-8) – la forme que les plugins de boutique transmettent au panier et que Legacy avait dans le champ configurator1-header. Avec opts.assets (résultat de storeCombinedImage() sous la forme { type: 'imgData', id, url, file }), la liste d'images est ajoutée ; le plugin Magento, par exemple, y lit l'image du panier.

Modifier

Méthode	Signature	Pour
selectValue	(characteristic, value) => void ; value peut être null	Sélection, boutons radio, liste avec images. null vide la sélection.
toggleValue	(characteristic, value) => void	Case à cocher, sélection multiple, liste avec images à sélection multiple
setText	(characteristic, text: string) => void	Champs de saisie
setQuantity	(characteristic, value, quantity: number) => void	Sélection multiple avec quantités ; les quantités négatives deviennent 0
resetSelection	(characteristic) => void	Tous les types de données ; les règles peuvent ensuite présélectionner à nouveau la caractéristique
setProductAttributes	(attributes: Record<string, string>) => void	Remplace les valeurs des attributs de produit, p. ex. après un changement de variante. Peut aussi être appelée avant ready.
showLanguageSelect	() => void	Affiche à nouveau le choix de la langue (uniquement avec languageSelect et plusieurs langues) ; la sélection est conservée

Chaque modification agit comme une saisie du client : règles, formules et prix sont recalculés, puis suivent change et – si le prix change – price.

Conclure

finalize(): Promise<FinalizeResult>

Vérifie toute la configuration comme un clic sur le bouton d'action et affiche les erreurs sur la caractéristique.

{
  ok: boolean;
  validationErrors: ValidationError[];
  payload?: AssetPayload;        // uniquement si ok
  priceTotal: number;
  summary: string;               // texte, 1024 caractères au maximum
  combinedImage?: string;        // PNG en URL de données si le composant a une image combinée
}

finalize() n'envoie rien et déclenche ensuite l'événement finalize.

Enregistrer et charger

Méthode	Signature	Description
storeAsset	() => Promise<{ id: string; url: string }>	Enregistre la configuration. id est la clé du lien profond, url l'adresse du fichier JSON enregistré.
Configento.loadAsset	(id, { instance? }) => Promise<AssetPayload>	Lit une configuration enregistrée. Sans instance, la première s'applique.
restoreFromAssetJson	(payload) => void	Transfère dans l'instance une configuration lue
storeCombinedImage	() => Promise<{ id: string; url: string }> (ou null)	Enregistre l'image de produit combinée pour le panier ou la commande ; null si le composant n'en a pas

Si quelqu'un ouvre la page produit avec ?dl=<id> (ou ?configento_asset=<id>), V3 restaure de lui-même la configuration dans le premier configurateur. Pour d'autres paramètres ou un autre configurateur, appelez vous-même loadAsset() et restoreFromAssetJson().

const { id } = await k.storeAsset();
const lien = new URL(location.href);
lien.searchParams.set('dl', id);

storeAsset() et loadAsset() ont besoin des paramètres de la boutique (ID client, jeton). Dans l'aperçu de l'administration, elles lèvent donc CONFIG_MISSING. Le configurateur ne relance pas de lui-même les téléversements échoués – sinon des entrées en double seraient créées.

Groupes et assistant

Méthode	Signature	Description
getGroups	() => GroupInfo[]	Groupes affichés, dans l'ordre ; ceux masqués par des règles n'y figurent pas
getActiveGroup	() => ActiveGroup (ou null)	Groupe affiché ; null avec Aucun groupe ou un seul groupe
setActiveGroup	(ref, opts?: { validate?: boolean }) => Promise<boolean> ; ref est un number ou une string	Change de groupe par ID ou nom interne. En avançant, vérifie chaque étape du parcours (validate: false l'évite) et interroge le step guard. true si l'étape a changé.
nextGroup	() => Promise<boolean>	Comme Suivant
prevGroup	() => Promise<boolean>	Comme Retour – sans vérification
setStepGuard	(guard, opts?: { backward?: boolean }) => void ; guard est un StepGuard ou null	Votre propre vérification avant le changement

type GroupRef   = { id: number; key: string | null; index: number };
type GroupInfo  = GroupRef & { title: string };
type ActiveGroup = GroupRef & { total: number };

type StepGuard = (step: { from: GroupRef; to: GroupRef; direction: 'forward' | 'back' | 'jump' })
  => boolean | void | Array<{ characteristic: number | string; message: string }>
   | Promise<boolean | void | Array<{ characteristic: number | string; message: string }>>;

key est le nom interne du groupe défini dans l'éditeur, index la position parmi les groupes affichés. Le step guard s'exécute après la vérification intégrée, par défaut uniquement en avançant. false retient l'étape sans message, une liste la retient et affiche chaque message sur la caractéristique (code d'erreur guard). Tant qu'une promesse est en attente, Suivant et Retour sont bloqués. Si le guard lève une erreur, l'étape change malgré tout.

En outre, une règle d'erreur dont « Exécuter lorsque » vaut Assistant et dont le Type d'erreur est Erreur retient l'étape à laquelle elle appartient.

Événements

on(event, callback) renvoie une fonction de désabonnement. Les écouteurs restent abonnés même si l'instance est reconnectée en interne (p. ex. lorsque des valeurs de service web arrivent plus tard).

Événement	Quand	Contenu
change	Après chaque modification de la sélection	{ selections: SelectionsMap } – comme getSelections()
price	Lorsque le prix total, la devise ou la base de taxe changent ; une fois juste après le chargement	{ total, currency, priceIncludesTax, delta } – delta par rapport au prix précédent
finalize	Lorsque finalize() est terminé	FinalizeResult
error	Lorsque des erreurs apparaissent sur la caractéristique	{ errors: ValidationError[] }
group	Après chaque changement du groupe affiché, pas lors du premier affichage	{ from, to, direction } ; to est un GroupRef, from un GroupRef ou null

onChange(callback) est l'ancienne forme de on('change', …) sans contenu et sera supprimée.

Types de données

Sélection

SelectionsMap est { [ID de caractéristique]: sélection } ; selon le type de donnée, une sélection est :

kind	Champs	Caractéristiques
single	valueId (number ou null), qty?: number	Sélection, boutons radio, liste avec images
multi	valueIds: number[], qtys?: { [ID de valeur]: number }	Case à cocher, sélection multiple
text	value: string	Champs de saisie
quantities	quantities: { [ID de valeur]: number }	Sélection multiple avec quantités
files	files: Array<{ id, folder, type, … }>	Téléchargement de fichier
captcha	payload: string	Captcha

ValidationError

{ characteristicId: number; altTitle: string; code: string; message: string }

message est déjà traduit dans la langue du configurateur. code est l'un des suivants : required, pattern, range, length, numeric, integer, gt-zero, gte-zero, email, url, zip, phone, iban, bic, vat, code, alpha, alphanum, data, lowercase, uppercase, rule (règle d'erreur), guard (step guard).

CloudError

storeAsset() et loadAsset() rejettent avec une Configento.CloudError : code, retryable et, pour les erreurs HTTP, status.

code	Signification	retryable
NO_SELECTIONS	Rien n'est encore sélectionné	non
CONFIG_MISSING	Pas de paramètres de boutique (aperçu de l'administration) ou pas d'instance	non
HTTP_4XX	Refusé, p. ex. jeton ou domaine	non
HTTP_5XX	Erreur du serveur	oui
BAD_RESPONSE	Réponse inattendue	non
NETWORK	Pas de connexion, CORS, certificat	oui
NOT_FOUND	La configuration enregistrée n'existe pas	non

try {
  await k.storeAsset();
} catch (err) {
  if (!(err instanceof Configento.CloudError)) throw err;
  if (err.retryable) planifierNouvelEssai();
}

Intégration : attributs et JSON

Chaque paramètre se définit soit comme attribut sur l'élément portant data-configento, soit comme clé dans l'attribut JSON data-configento-config. Si les deux sont présents, le JSON l'emporte.

Attribut	Clé JSON	Valeur
data-component-id	componentId	ID du composant – obligatoire
data-configento-customer	customer	ID client
data-configento-token	token	Jeton de la carte HTML5 (V3 Bêta)
data-configento-token-endpoint	tokenEndpoint	Adresse qui délivre des jetons de courte durée (plugins de boutique)
data-configento-cloud-base-url	cloudBaseUrl	cloud.configento.app
data-configento-asset-base-url	assetBaseUrl	Hôte des configurations enregistrées (plugins de boutique)
data-configento-tax-rate	taxRate	Taux de taxe de la boutique en pourcentage
data-configento-currency	currency	Code de devise, p. ex. EUR
data-configento-currency-rates	currencyRates	Taux de change en JSON, p. ex. {"CHF": 0.94}
data-configento-locale	uiLocale	Langue, p. ex. de_DE
data-configento-content-locale	contentLocale	Langue différente uniquement pour les textes du composant
data-configento-embed-mode	embedMode	storefront (par défaut avec les attributs) ou admin-preview
data-configento-price-mount	priceMount	Sélecteur CSS pour le prix total
data-configento-summary-mount	summaryMount	Sélecteur CSS pour le récapitulatif
data-configento-summary-open	summaryOpen	Récapitulatif déplié ou replié au départ
data-configento-combined-image-mount	combinedImageMount	Sélecteur CSS pour l'image de produit combinée
data-configento-language-select	languageSelect	Choix de la langue avant le configurateur
data-configento-language-select-title	languageSelectTitle	Texte au-dessus du choix de la langue
data-configento-languages	languages	Langues proposées, séparées par des virgules (JSON : liste)
data-configento-min-height	minHeight	Hauteur réservée pendant le chargement, p. ex. 640px
data-configento-min-height-keep	minHeightKeep	Conserver la hauteur également après le chargement
data-configento-wizard-nav	wizardNav	full, buttons ou none
data-configento-component-json	component	Le composant lui-même, tel que GET /api/v3/components/{id} le renvoie
–	productAttributes	Valeurs des attributs de produit, p. ex. {"largeur": "120"}

Les attributs oui/non acceptent true/false, 1/0, yes/no ou l'attribut sans valeur pour « oui ». Les valeurs inconnues laissent la valeur par défaut en place et produisent un avertissement dans la console.

Affichage lors de l'intégration par attributs : en mode storefront, le configurateur n'affiche ni le prix total ni le récapitulatif – la boutique a les siens. Avec price-mount et summary-mount, vous les placez à l'endroit de votre choix. Si un sélecteur ne trouve aucun élément, la partie n'apparaît nulle part, plutôt qu'en double dans le configurateur. summary-open n'agit qu'avec summary-mount ; le récapitulatif y démarre déplié par défaut.

Adaptateur de fenêtre modale

interface ModalAdapter {
  openOverlay(args: { title: string; container: HTMLElement; onClose: () => void }): { close(): void };
}

Le configurateur remplit container après le retour d'openOverlay. Votre adaptateur l'insère dans une fenêtre qui lui est propre et appelle onClose() lorsque le client la ferme. Le configurateur appelle close() lorsqu'il ferme lui-même la fenêtre (p. ex. après la sélection). Définissez l'adaptateur dès que window.Configento existe et avant qu'une fenêtre ne s'ouvre ; setModalAdapter() sans argument rétablit la fenêtre intégrée.

Script de compatibilité

https://cloud.configento.app/configento-v3/configento-compat.js – chargé avant configento.js – fait correspondre les objets globaux du moteur Legacy (Justselling_Configento_App_*, CONFIGENTO_PRODUCT.setPrice, les événements configentoUpdate…InDom…) à cette interface. Ce qu'il prend en charge en détail et comment réécrire l'ancien code est décrit dans le guide sous Migrer depuis Legacy.

Versions et engagements

Configento.version suit le Semantic Versioning. Jusqu'à la version 3.0.0, les textes d'erreur et de petits détails peuvent encore changer ; les méthodes et types de données de cette page restent. À partir de 3.0.0 : les corrections de bogues changent le dernier chiffre, les nouvelles fonctions celui du milieu, et seul un nouveau premier chiffre casse du code existant – avec un guide de migration.

Appuyez-vous sur les méthodes, événements et types de données de cette page, et non sur les classes CSS ou la structure DOM du configurateur. Seuls les attributs data-configento-char-id, data-configento-group-id et data-configento-group-key sont stables.

Étapes suivantes

• Interface JavaScript (V3) – guide avec exemples
• Intégration extrait HTML
• Téléversements & liens profonds
• Moteur frontend : Legacy ou V3