JavaScript-API-Referenz (V3)

Diese Referenz beschreibt jede Methode, jedes Ereignis und jede Einstellung, die die Frontend-Engine V3 auf window.Configento bereitstellt – mit Signatur, Rückgabe, Fehlerfällen und einem kurzen Beispiel. Sie richtet sich an Entwickler von Shop-Themes, Plugins und eigenen Integrationen. Wie du typische Aufgaben löst und vom Legacy-Code umsteigst, zeigt der Leitfaden JavaScript-Schnittstelle (V3).

Die Signaturen stehen in TypeScript-Schreibweise. Alles funktioniert auch in reinem JavaScript.

Lebenszyklus

1. Die Seite lädt https://cloud.configento.app/configento-v3/configento.js (mit defer).
2. Das Skript legt window.Configento an, sucht einmal alle Elemente mit data-configento und registriert für jedes eine Instanz. Ihre id ist die id des Elements, sonst configento-anon-<n>.
3. Für jede Instanz startet sofort das Laden der Komponente (oder es wird die eingebettete genommen, siehe component).
4. Sobald eine Komponente geladen ist, bekommt ihre Instanz die Methoden unten. Vorher werfen sie Configento instance not ready — await Configento.ready first.
5. Configento.ready wird erfüllt, wenn alle Instanzen der Seite geladen sind.

Elemente, die erst nach Schritt 2 in die Seite kommen, werden nicht erkannt. Eine Instanz-Referenz bleibt über den Ladevorgang hinweg gültig: Wer Configento.instances.get(id) vor ready hält, bekommt danach am selben Objekt die echten Methoden.

Global: window.Configento

Eigenschaft / Methode	Typ	Beschreibung
version	string	Version der Engine, z. B. 3.1.0
frontendVersionTag	'v3'	Kennung der Engine-Generation. Prüfe darauf, nicht auf version, wenn dein Code nur mit einer Generation funktioniert.
ready	Promise<void>	Erfüllt, wenn alle Instanzen geladen sind
instances	ReadonlyMap<string, ConfiguratorInstance>	Alle Instanzen, Schlüssel ist die Instanz-id
first()	ConfiguratorInstance oder null	Die erste Instanz der Seite
forElement(el)	(el) => ConfiguratorInstance (oder null); el ist ein HTMLElement oder ein string	Die Instanz zu einem Element oder CSS-Selektor; sucht auch nach außen (closest('[data-configento]'))
loadAsset(id, opts?)	(id: string, opts?: { instance?: ConfiguratorInstance }) => Promise<AssetPayload>	Liest eine gespeicherte Konfiguration, siehe Speichern und laden
setModalAdapter(adapter?)	(adapter?: ModalAdapter) => void	Eigenes Fenster für Bild-Großansichten, siehe Modal-Adapter
registerRenderer(name, renderer)	(name: string, renderer: CharacteristicRenderer) => () => void	Eigene Darstellung für Merkmale, siehe Eigene Darstellung. Gibt eine Funktion zum Abmelden zurück.
CloudError	Klasse	Fehlerklasse von storeAsset() und loadAsset(), siehe CloudError

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

Instanz: ConfiguratorInstance

Eigenschaften (nur lesbar):

Eigenschaft	Typ	Beschreibung
id	string	Instanz-id
componentId	string oder null	ID der Komponente
element	HTMLElement	Das Element mit data-configento
config	WebshopConfig oder null	Die Einstellungen beim Laden, eingefroren – siehe Einbinden

Merkmale gibst du als internen Namen (string) oder numerische ID an (CharacteristicRef), Werte als Feld Wert (string) oder numerische ID (ValueRef). Ein unbekannter Name, ein unbekannter Wert oder ein unpassender Datentyp löst einen Error aus.

Lesen

getValue(characteristic): unknown

Wert eines Merkmals in der Form, die auch Formeln sehen:

Merkmal	Ergebnis	Leer
Auswahl, Radio Buttons, Liste mit Bildern	Feld Wert des gewählten Eintrags (ohne Wert: seine ID)	null
Mehrfachauswahl, Checkbox	Liste der Werte	[]
Eingabefelder	Text, ohne Leerzeichen am Rand	''
Mehrfachauswahl mit Mengen	{ [Wert-ID]: Menge }	{}
Formel, Preisliste, Kombination, Produktattribut, Webservice	Ergebnis der Berechnung	null

Ein Merkmal, das eine Regel ausblendet, liefert immer „leer“.

k.getValue('breite');      // → '120'
k.getValue('zubehoer');    // → ['kurbel', 'fernbedienung']

getSelections(): SelectionsMap

Die aktuelle Auswahl aller Merkmale als { [Merkmals-ID]: Auswahl } – siehe Auswahl. Merkmale, die eine Regel ausblendet, fehlen; gesperrte Werte sind entfernt.

getState(): ConfiguratorSnapshot

{
  selections: SelectionsMap;                     // wie getSelections()
  evaluated: Record<number, number | string | null>;  // Ergebnisse aller Berechnungen nach Merkmals-ID
  hiddenCharacteristics: number[];               // von Regeln ausgeblendete Merkmale
  blacklistedValues: number[];                   // von Regeln gesperrte Werte
  price: PriceSnapshot;                          // wie getPriceBreakdown()
  characteristicPrices: Record<string, number>;  // Aufpreis je Merkmal nach internem Namen
}

Reine Abfrage – beliebig oft aufrufbar. characteristicPrices nennt, was jedes Merkmal zu price.total beiträgt, in Währung und Steuerbasis des Shops. Merkmale ohne Preisanteil, ohne internen Namen oder von einer Regel ausgeblendet fehlen.

getPriceBreakdown(): PriceSnapshot

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

total ist schon auf Steuersatz und Währung des Shops umgerechnet (data-configento-tax-rate, data-configento-currency).

getSummary(opts?): string

Option	Standard	Wirkung
format	'text'	'html' liefert <dl><dt>Merkmal</dt><dd>Wert</dd>…</dl>
includePrices	false	Aufpreis des Merkmals hinter dem Wert, wie in characteristicPrices; Merkmale ohne Aufpreis bleiben ohne
separator	'; '	Trenner im Textformat

Enthält nur sichtbare Merkmale. Zeigt die Komponente die kombinierte Artikelnummer in der Zusammenfassung, steht sie am Ende.

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

getCombinedSku(): string

Artikelnummer des konfigurierten Produkts aus den Artikelnummern der gewählten Werte, mit - verbunden, z. B. CL-W-GR-TXT. Je Merkmal in Reihenfolge der Komponente: die Artikelnummer des gewählten Werts (bei Mehrfachauswahl die erste vorhandene), sonst die des Merkmals. Leere Teile entfallen, ausgeblendete Merkmale zählen nicht. '', wenn nichts eine Artikelnummer trägt. Ist sie nicht leer, steht sie als _combined_sku auch in jeder Bestell-Payload.

getCharacteristics(): CharacteristicInfo[]

Beschreibt alle Merkmale der Komponente in ihrer Reihenfolge – unabhängig von Regeln und Auswahl. Damit liest du die CSS-Klasse und die benutzerdefinierten Felder von Merkmalen und Werten.

type CharacteristicInfo = {
  id: number;
  key: string | null;          // interner Name, Schlüssel in getAssetPayload()
  groupId: number;
  groupKey: string | null;
  title: string;
  type: string;                // z. B. 'radiobuttons', 'text'
  visibility: 'visible' | 'hidden' | 'shop' | 'backend';
  cssClass: string;            // Feld „CSS-Klasse“ wie eingetragen, '' wenn leer
  customFields: { [Feldnummer]: CustomField };
  values: Array<{
    id: number;
    key: string | null;        // value des Werts
    label: string;
    sku: string | null;
    customFields: { [Feldnummer]: CustomField };
  }>;                          // alle Werte, auch gesperrte; leer bei Eingabefeldern
};

CustomField beschreibt Payload-Eintrag. Einen Wert über den Inhalt eines Felds finden:

const farbe = k.getCharacteristics().find((c) => c.key === 'farbe');
const wert = farbe.values.find((v) =>
  Object.values(v.customFields).some((f) => f.id === 'checkout-titel' && f.value === 'Rot'));

Die Klasse im Feld CSS-Klasse darf auch als Steuerwert für dein eigenes Skript dienen. Eine eigene Darstellung greift nur, wenn genau dieser Name mit registerRenderer() registriert ist.

getAssetPayload(): AssetPayload | null

Die Konfiguration als JSON, nach internen Namen geordnet – dieselbe Form wie finalize().payload, aber ohne Prüfung. null, solange nichts gewählt ist. Sie enthält immer alle Gruppen, nicht nur die angezeigte, in der Reihenfolge der Komponente. Die Felder je Merkmal beschreibt Payload-Eintrag. Neben den Merkmalen enthält sie _component_title, _locale, bei Bedarf _combined_sku und – bei Komponenten mit Captcha – altcha.

getHeaderValue(opts?): string | null

Dieselbe Konfiguration Base64-kodiert (UTF-8-sicher) – die Form, die Shop-Plugins an den Warenkorb übergeben und Legacy im Feld configurator1-header hatte. Mit opts.assets (Ergebnis von storeCombinedImage() als { type: 'imgData', id, url, file }) kommt die Bildliste dazu, aus der z. B. das Magento-Plugin das Warenkorbbild liest.

Ändern

Methode	Signatur	Für
selectValue	(characteristic, value) => void; value darf null sein	Auswahl, Radio Buttons, Liste mit Bildern. null leert.
toggleValue	(characteristic, value) => void	Checkbox, Mehrfachauswahl, Liste mit Bildern mit Mehrfachauswahl
setText	(characteristic, text: string) => void	Eingabefelder
setQuantity	(characteristic, value, quantity: number) => void	Mehrfachauswahl mit Mengen; negative Mengen werden 0
resetSelection	(characteristic) => void	Alle Datentypen; Regeln dürfen das Merkmal danach wieder vorbelegen
setProductAttributes	(attributes: Record<string, string>) => void	Ersetzt die Werte der Produktattribute, z. B. nach einem Variantenwechsel. Auch vor ready aufrufbar.
showLanguageSelect	() => void	Zeigt die Sprachauswahl erneut (nur mit languageSelect und mehreren Sprachen), die Auswahl bleibt

Jede Änderung wirkt wie eine Eingabe des Kunden: Regeln, Formeln und Preis rechnen neu, dann folgen change und – wenn sich der Preis ändert – price.

Abschließen

finalize(): Promise<FinalizeResult>

Prüft die ganze Konfiguration wie ein Klick auf den Aktions-Button und zeigt Fehler am Merkmal an.

{
  ok: boolean;
  validationErrors: ValidationError[];
  payload?: AssetPayload;        // nur bei ok
  priceTotal: number;
  summary: string;               // Text, höchstens 1024 Zeichen
  combinedImage?: string;        // PNG als Data-URL, wenn die Komponente ein kombiniertes Bild hat
}

finalize() verschickt nichts und löst danach das Ereignis finalize aus.

Speichern und laden

Methode	Signatur	Beschreibung
storeAsset	() => Promise<{ id: string; url: string }>	Speichert die Konfiguration. id ist der Schlüssel für den Deep Link, url die Adresse der gespeicherten JSON-Datei.
Configento.loadAsset	(id, { instance? }) => Promise<AssetPayload>	Liest eine gespeicherte Konfiguration. Ohne instance gilt die erste.
restoreFromAssetJson	(payload) => void	Überträgt eine gelesene Konfiguration in die Instanz
storeCombinedImage	() => Promise<{ id: string; url: string }> (oder null)	Speichert das kombinierte Produktbild für Warenkorb oder Bestellung; null, wenn die Komponente keines hat

Öffnet jemand die Produktseite mit ?dl=<id> (oder ?configento_asset=<id>), stellt V3 die Konfiguration im ersten Konfigurator von selbst wieder her. Für andere Parameter oder einen anderen Konfigurator rufst du loadAsset() und restoreFromAssetJson() selbst auf.

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

storeAsset() und loadAsset() brauchen die Shop-Einstellungen (Kunden-ID, Token). In der Vorschau des Admins werfen sie deshalb CONFIG_MISSING. Der Konfigurator wiederholt fehlgeschlagene Uploads nicht selbst – sonst entstünden doppelte Einträge.

Gruppen und Wizard

Methode	Signatur	Beschreibung
getGroups	() => GroupInfo[]	Angezeigte Gruppen in Reihenfolge; von Regeln ausgeblendete fehlen
getActiveGroup	() => ActiveGroup (oder null)	Angezeigte Gruppe; null bei Keine Gruppen oder einer einzigen Gruppe
setActiveGroup	(ref, opts?: { validate?: boolean }) => Promise<boolean>; ref ist number oder string	Wechselt per ID oder internem Namen. Vorwärts prüft es jeden Schritt auf dem Weg (validate: false überspringt) und fragt den Step-Guard. true, wenn gewechselt wurde.
nextGroup	() => Promise<boolean>	Wie Weiter
prevGroup	() => Promise<boolean>	Wie Zurück – ohne Prüfung
setStepGuard	(guard, opts?: { backward?: boolean }) => void; guard ist StepGuard oder null	Eigene Prüfung vor dem Wechsel

type GroupRef   = { id: number; key: string | null; index: number };
type GroupInfo  = GroupRef & { title: string; characteristics: 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 ist der interne Name der Gruppe aus dem Editor, index die Position unter den angezeigten Gruppen. characteristics listet die internen Namen der Merkmale der Gruppe in Anzeigereihenfolge – die Schlüssel, unter denen sie in getAssetPayload() stehen. Von Regeln ausgeblendete Merkmale bleiben in der Liste, Merkmale ohne internen Namen fehlen. Damit gliederst du eine eigene Zusammenfassung nach Schritten, ohne die Zuordnung im eigenen Code zu pflegen:

const payload = k.getAssetPayload() ?? {};
for (const group of k.getGroups()) {
  const rows = group.characteristics
    .map((name) => payload[name])
    .filter((entry) => entry && entry.visibility !== 0);
  // group.title als Überschrift, rows als Zeilen
}

Der Step-Guard läuft nach der eingebauten Prüfung, standardmäßig nur vorwärts. false hält den Schritt ohne Meldung, eine Liste hält ihn und zeigt jede Meldung am Merkmal (Fehlercode guard). Solange ein Promise offen ist, sind Weiter und Zurück gesperrt. Wirft der Guard, wechselt der Schritt trotzdem.

Zusätzlich hält eine Fehler-Regel mit „Ausführen bei: Wizard“ und Meldungstyp Fehler den Schritt an, zu dem sie gehört.

Ereignisse

on(event, callback) gibt eine Funktion zum Abmelden zurück. Listener bleiben angemeldet, auch wenn die Instanz intern neu verbunden wird (etwa wenn Webservice-Werte nachträglich eintreffen).

Ereignis	Wann	Inhalt
change	Nach jeder Änderung der Auswahl	{ selections: SelectionsMap } – wie getSelections()
price	Wenn sich Gesamtpreis, Währung oder Steuerbasis ändern; einmal direkt nach dem Laden	{ total, currency, priceIncludesTax, delta } – delta zum vorigen Preis
finalize	Wenn finalize() fertig ist	FinalizeResult
error	Wenn Fehler am Merkmal erscheinen	{ errors: ValidationError[] }
group	Nach jedem Wechsel der angezeigten Gruppe, nicht beim ersten Anzeigen	{ from, to, direction }; to ist ein GroupRef, from ein GroupRef oder null
action	Wenn die Anfrage eines Aktions-Buttons fertig ist – auch bei Fehlerstatus oder Netzwerkfehler, nicht wenn die Prüfung der Eingaben den Klick stoppt (dann error) – bei der Aktion An die Seite übergeben (event) stattdessen, sobald die Eingaben geprüft sind, vor dem Absenden	ActionEvent, siehe unten

onChange(callback) ist die ältere Form von on('change', …) ohne Inhalt und wird entfernt.

ActionEvent

Feld	Bedeutung
ok	true bei HTTP-Status 2xx. Bei event immer true
status	HTTP-Status der Antwort, 0 ohne Antwort (Netzwerkfehler). Bei event 0
body	Antwort des Endpunkts: als Objekt, wenn sie JSON ist, sonst als Text; null bei einem PDF oder ohne Antwort. Bei event null
characteristic	Interner Name des Aktions-Buttons
action	custom_url, pdf, email oder event (Aktion An die Seite übergeben)
payload	Nur bei event: die Konfiguration zum Absenden, die Captcha-Lösung als altcha
preventDefault()	Der Button zeigt danach weder seine Erfolgs- noch seine Fehlerzeile und leitet nicht weiter. Ein PDF-Download startet trotzdem.
defaultPrevented	true, wenn ein Listener preventDefault() aufgerufen hat

Bei event wartet der Button auf das Promise, das dein Listener zurückgibt: { ok: true, message } zeigt Erfolg (mit deiner Meldung, falls angegeben), { ok: false, message } zeigt deine Meldung als Fehler, ein abgelehntes Promise dessen Fehlertext. Gibt der Listener nichts zurück, gilt das als Erfolg. Seit Version 3.2.0.

Seit Version 3.1.0.

Datentypen

Auswahl

SelectionsMap ist { [Merkmals-ID]: Auswahl }, eine Auswahl ist je nach Datentyp:

kind	Felder	Merkmale
single	valueId (number oder null), qty?: number	Auswahl, Radio Buttons, Liste mit Bildern
multi	valueIds: number[], qtys?: { [Wert-ID]: number }	Checkbox, Mehrfachauswahl
text	value: string	Eingabefelder
quantities	quantities: { [Wert-ID]: number }	Mehrfachauswahl mit Mengen
files	files: Array<{ id, folder, type, … }>	Dateiupload
captcha	payload: string	Captcha

Payload-Eintrag

Jedes Merkmal steht in getAssetPayload() und finalize().payload unter seinem internen Namen. Diese Felder sind zugesagt:

Feld	Typ	Vorhanden
label	string	Immer. Titel des Merkmals in der Sprache des Konfigurators.
value	siehe unten	Immer.
valueLabel	siehe unten	Immer. Bezeichnung des Werts bzw. die Eingabe.
visibility	number	Immer. Folgt der Sichtbarkeit des Merkmals: 1 Ja (sichtbar), 3 Nur Backend, 0 Nein (versteckt) oder von einer Regel ausgeblendet.
valueId	number, null oder number[]	Bei Merkmalen mit Werten.
choiceSku	string oder string[]	Bei Merkmalen mit Werten. Bei Einfachauswahl nur, wenn der gewählte Wert eine Artikelnummer hat; in Arrays steht '' für Werte ohne.
valueQty	number oder number[]	Bei Mehrfachauswahl mit Mengen immer, sonst nur, wenn am Merkmal eine Menge eingestellt ist.
sku	string	Wenn das Merkmal selbst eine Artikelnummer hat.
files	Array<{ id, folder, type, … }>	Bei Dateiupload.
customFields	{ [Feldnummer]: CustomField }	Wenn das Merkmal benutzerdefinierte Felder hat.
choiceCustomFields	{ [Feldnummer]: CustomField }	Bei Auswahl, Radio Buttons und Paket, wenn der gewählte Wert benutzerdefinierte Felder hat.

Je nach Datentyp:

Merkmale	value	valueLabel	valueId
Auswahl, Radio Buttons, Paket	string – value des Werts, '' ohne Auswahl	string	number, null ohne Auswahl
Checkbox, Mehrfachauswahl, Liste mit Bildern	string[]	string[]	number[]
Mehrfachauswahl mit Mengen	string[]	string[]	number[], dazu valueQty: number[] an gleicher Position
Eingabefelder	string	string (wie value)	–
Formel, Einfache Kombination, Produktattribut, Webservice	string – das Ergebnis, '' ohne	string	–
Dateiupload	string – Dateinamen mit Komma	string[]	–

Liste mit Bildern liefert immer Arrays, auch wenn nur ein Wert wählbar ist. Ein von einer Regel ausgeblendetes Merkmal bleibt mit seinem Schlüssel stehen, aber leer: value und valueLabel sind '', visibility ist 0, die übrigen Felder außer sku und customFields fehlen.

CustomField ist { value: string; title: string; id: string }: value ist der eingetragene Text (auch ''), title der Name des Felds aus den Komponenten-Einstellungen und id daraus abgeleitet – ohne Leerzeichen und Sonderzeichen, kleingeschrieben, z. B. Checkout-Titel → checkout-titel. Schlüssel ist die Nummer des Felds. Das ist dieselbe Form wie in Legacy; das Magento-Plugin übernimmt beide Felder in die Bestellung.

Nicht in der Payload stehen Merkmale mit der Sichtbarkeit Nur Shop, Merkmale ohne internen Namen sowie statische Felder, Diagramme, Aktions-Buttons und Captchas. Preise je Merkmal stehen nicht in der Payload – die liefert getState().characteristicPrices.

ValidationError

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

message ist schon in die Sprache des Konfigurators übersetzt. code ist einer von: required, pattern, range, length, numeric, integer, gt-zero, gte-zero, email, url, zip, phone, iban, bic, vat, code, alpha, alphanum, data, lowercase, uppercase, rule (Fehler-Regel), guard (Step-Guard).

CloudError

storeAsset() und loadAsset() lehnen mit einer Configento.CloudError ab: code, retryable, bei HTTP-Fehlern status.

code	Bedeutung	retryable
NO_SELECTIONS	Noch nichts gewählt	nein
CONFIG_MISSING	Keine Shop-Einstellungen (Admin-Vorschau) oder keine Instanz	nein
HTTP_4XX	Abgelehnt, etwa Token oder Domäne	nein
HTTP_5XX	Serverfehler	ja
BAD_RESPONSE	Unerwartete Antwort	nein
NETWORK	Keine Verbindung, CORS, Zertifikat	ja
NOT_FOUND	Gespeicherte Konfiguration gibt es nicht	nein

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

Einbinden: Attribute und JSON

Jede Einstellung geht als Attribut am Element mit data-configento oder als Schlüssel im JSON-Attribut data-configento-config. Steht beides da, gewinnt das JSON.

Attribut	JSON-Schlüssel	Wert
data-component-id	componentId	ID der Komponente – Pflicht
data-configento-customer	customer	Kunden-ID
data-configento-token	token	Token aus der Karte HTML5 (V3)
data-configento-token-endpoint	tokenEndpoint	Adresse, die kurzlebige Tokens ausgibt (Shop-Plugins). Fehlt in der Adresse die Komponenten-ID (?id=), hängt der Konfigurator sie selbst an.
data-configento-cloud-base-url	cloudBaseUrl	cloud.configento.app
data-configento-asset-base-url	assetBaseUrl	Host für gespeicherte Konfigurationen (Shop-Plugins)
data-configento-tax-rate	taxRate	Steuersatz des Shops in Prozent
data-configento-currency	currency	Währungscode, z. B. EUR
data-configento-currency-rates	currencyRates	Kurse als JSON, z. B. {"CHF": 0.94}
data-configento-locale	uiLocale	Sprache, z. B. de_DE
data-configento-content-locale	contentLocale	Abweichende Sprache nur für die Texte der Komponente
data-configento-embed-mode	embedMode	storefront (Standard bei Attributen) oder admin-preview
data-configento-price-mount	priceMount	CSS-Selektor für den Gesamtpreis
data-configento-summary-mount	summaryMount	CSS-Selektor für die Zusammenfassung
data-configento-summary-open	summaryOpen	Zusammenfassung anfangs auf- oder zugeklappt
data-configento-combined-image-mount	combinedImageMount	CSS-Selektor für das kombinierte Produktbild
data-configento-language-select	languageSelect	Sprachauswahl vor dem Konfigurator
data-configento-language-select-title	languageSelectTitle	Text über der Sprachauswahl
data-configento-languages	languages	Angebotene Sprachen, durch Komma getrennt (JSON: Liste)
data-configento-min-height	minHeight	Höhe, die beim Laden frei bleibt, z. B. 640px
data-configento-min-height-keep	minHeightKeep	Höhe auch nach dem Laden behalten
data-configento-wizard-nav	wizardNav	full, buttons oder none
data-configento-component-json	component	Die Komponente selbst, wie GET /api/v3/components/{id} sie liefert
–	productAttributes	Werte der Produktattribute, z. B. {"breite": "120"}

Ja/Nein-Attribute akzeptieren true/false, 1/0, yes/no oder das Attribut ohne Wert für „ja“. Unbekannte Werte lassen den Standard stehen und erzeugen eine Warnung in der Konsole.

Darstellung beim Einbinden per Attribut: Im Modus storefront zeigt der Konfigurator weder Gesamtpreis noch Zusammenfassung – der Shop hat eigene. Mit price-mount und summary-mount holst du sie an eine Stelle deiner Wahl. Findet ein Selektor kein Element, erscheint das Teil nirgends, statt doppelt im Konfigurator. summary-open wirkt nur zusammen mit summary-mount; dort startet die Zusammenfassung standardmäßig aufgeklappt.

Token früher anfordern: Mit tokenEndpoint fragt der Konfigurator erst nach dem Laden nach seinem Token. Schneller geht es, wenn die Seite diese Anfrage schon im <head> startet und das Promise unter window.ConfigentoTokenPrefetch ablegt, mit genau der URL aus tokenEndpoint als Schlüssel. Der Konfigurator nimmt dieses Ergebnis einmal. Liefert das Promise null, einen Fehler oder kein token, fragt er selbst. In die Seite kommt so nur die URL, nie ein Token – das verträgt sich mit Seiten-Caches. Das Magento-Plugin macht das ab Version 5.0.0-beta22 von selbst.

<script>
  (window.ConfigentoTokenPrefetch ||= {})['https://shop.example/configento/v3/token/id/42/'] =
    fetch('https://shop.example/configento/v3/token/id/42/', { method: 'POST', credentials: 'omit' })
      .then((r) => (r.ok ? r.json() : null))
      .catch(() => null);
</script>

Modal-Adapter

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

Der Konfigurator füllt container, nachdem openOverlay zurückkehrt. Dein Adapter hängt ihn in ein eigenes Fenster und ruft onClose(), wenn der Kunde es schließt. close() ruft der Konfigurator, wenn er das Fenster selbst schließt (z. B. nach der Auswahl). Setze den Adapter, sobald window.Configento existiert und bevor ein Fenster aufgeht; setModalAdapter() ohne Argument stellt das eingebaute Fenster wieder her.

Kompatibilitäts-Skript

https://cloud.configento.app/configento-v3/configento-compat.js – vor configento.js geladen – bildet die globalen Objekte der Legacy-Engine (Justselling_Configento_App_*, CONFIGENTO_PRODUCT.setPrice, die Ereignisse configentoUpdate…InDom…) auf diese Schnittstelle ab. Was es im Einzelnen übernimmt und wie du alten Code umschreibst, steht im Leitfaden unter Von Legacy umsteigen.

Eigene Darstellung

Mit Configento.registerRenderer(name, renderer) zeichnet dein Code ein Merkmal selbst. Steht name im Feld CSS-Klasse eines Merkmals, rendert der Konfigurator statt des Eingabeelements einen leeren Container (div.cfg-custom mit data-configento-renderer="<name>"). Seinen Inhalt fasst der Konfigurator nie an. Werte setzt dein Code über ctx – Regeln, Preis, Prüfung, Wizard, Zusammenfassung und Bestellung laufen wie bei einer Eingabe des Kunden.

interface CharacteristicRenderer {
  replace?: 'body' | 'all';     // Standard 'body'
  combine?: boolean;            // Standard false
  mount(el: HTMLElement, ctx: RendererContext): void;
  update?(ctx: RendererContext, el: HTMLElement): void;
  destroy?(el: HTMLElement): void;
}

Teil	Bedeutung
name	Klassenname aus Kleinbuchstaben, Ziffern und -. Eine von mehreren Klassen im Feld CSS-Klasse genügt. Ein zweites registerRenderer mit demselben Namen ersetzt das erste.
replace: 'body'	Der Konfigurator zeigt weiter Titel, Pflicht-Stern, Infotext und Fehlermeldungen, der Container sitzt in .cfg-char__body.
replace: 'all'	Der Container ist das einzige Kind von .cfg-char. Titel und Fehler zeigst du selbst aus ctx.
combine: true	Alle sichtbaren Merkmale derselben Gruppe mit dieser Klasse werden ein Widget, an der Stelle des ersten. Die übrigen zeigen nichts, bleiben aber in Regeln, Prüfung, Preis und Bestellung. Ihre Fehler erscheinen gesammelt am Widget.
mount	Einmal, sobald der Container im DOM steht
update	Wenn sich etwas in ctx ändert: Auswahl, Fehler, erlaubte Werte, Preise, Sprache. Nicht bei Änderungen an anderen Merkmalen.
destroy	Bevor der Container verschwindet: Schrittwechsel im Wizard, eine Regel blendet aus, Abmelden. Danach wirken die Methoden dieses ctx nicht mehr. Kommt das Merkmal zurück, folgt ein neues mount.

ctx:

Eigenschaft / Methode	Inhalt
characteristic	Das Merkmal, bei combine das erste
characteristics	Alle Merkmale des Widgets, sonst nur characteristic
locale	Sprache des Konfigurators, z. B. de_DE
instance	Die Instanz, siehe oben. Ihre Methoden gehen erst nach Configento.ready.
selectValue(wert, merkmal?), toggleValue(wert, merkmal?), setText(text, merkmal?), setQuantity(wert, menge, merkmal?), reset(merkmal?)	Wie die gleichnamigen Methoden der Instanz. Ohne merkmal gilt characteristic, sonst nur ein Merkmal aus characteristics.

Jedes Merkmal in ctx hat: id, key (interner Name), type, title, info (HTML), required, selection (wie getValue()), errors (ValidationError[]), values und bei Eingabefeldern textConstraints (minLength, maxLength, validator). values enthält nur die erlaubten Werte, von Regeln gesperrte fehlen. Jeder Wert hat id, key (Feld Wert), label, info, image, price (Aufpreis in Shop-Währung und -Steuerbasis), priceLabel (formatiert wie im Konfigurator, leer wenn keiner gezeigt wird) und selected.

Registrieren vor dem Bundle: Läuft dein Skript vor configento.js, leg den Renderer unter (window.ConfigentoRenderers ||= {})[name] = renderer ab. Später registrierte Renderer gehen ebenfalls: Bereits gezeigte Merkmale wechseln sofort.

Rückfall: Ist kein Renderer registriert – etwa in der Vorschau des Admins –, zeigt das Merkmal die eingebaute Darstellung. Wirft mount oder update einen Fehler, schreibt der Konfigurator ihn in die Konsole und zeigt für dieses Merkmal wieder das eingebaute Eingabeelement. Gilt nur für V3.

Gestaltung mit CSS

Farben, Schrift und Ecken passt du über Variablen wie --configento-color-accent an, einzelne Elemente über zugesagte Klassen wie .cfg-toggle-item__label. Beides beschreibt die Seite Design anpassen (CSS).

Versionen und Zusagen

Configento.version folgt Semantic Versioning. Fehlerbehebungen ändern die letzte Stelle, neue Funktionen die mittlere, und nur eine neue erste Stelle bricht bestehenden Code – mit einer Anleitung zum Umstieg.

Verlass dich auf die Methoden, Ereignisse und Datentypen dieser Seite – dazu gehören die Felder unter Payload-Eintrag – und auf die Variablen und Klassen unter Design anpassen (CSS), nicht auf andere Klassen oder die übrige DOM-Struktur des Konfigurators. Außerdem stabil sind die Attribute data-configento-group-id und data-configento-group-key.

Nächste Schritte

• JavaScript-Schnittstelle (V3) – Leitfaden mit Beispielen
• HTML-Snippet-Integration
• Uploads & Deep Links
• Frontend-Engine: Legacy oder V3