JavaScript-Schnittstelle (V3)

Mit der JavaScript-Schnittstelle verbindest du den Konfigurator mit deiner eigenen Logik auf der Seite: den Preis in deiner Kaufleiste zeigen, die Auswahl in ein eigenes Formular übernehmen, Werte von außen setzen oder eine Konfiguration speichern und später wieder öffnen. Die Frontend-Engine V3 stellt dafür das Objekt window.Configento bereit – egal, ob sie über das HTML-Snippet oder ein Shop-Plugin auf die Seite kommt. Dieser Leitfaden zeigt an fertigen Beispielen, wie du typische Aufgaben löst und Code für die Legacy-Engine auf V3 umstellst. Jede Methode mit Signatur, alle Ereignisse, Datentypen und Einstellungen stehen in der JavaScript-API-Referenz (V3).

Wo die Schnittstelle verfügbar ist

window.Configento gibt es überall dort, wo die Seite die Engine V3 lädt:

Integration	JavaScript-Schnittstelle
HTML-Snippet (Karte HTML5 (V3 Beta))	Immer
Shopify	Immer
PrestaShop	Immer
Magento 2	Wenn die Komponente auf V3 (Beta) steht oder V3 braucht, siehe Frontend-Engine: Legacy oder V3
Shopware 6 und das klassische HTML5-Snippet	Nein – beide laden Legacy

Die Plugins nutzen die Schnittstelle selbst, etwa um Preis und Konfiguration in den Warenkorb zu bringen. Dein eigener Code läuft daneben – du musst nichts abschalten.

Erste Schritte

<script>
  window.addEventListener('DOMContentLoaded', function () {
    Configento.ready.then(function () {
      var konfigurator = Configento.first();

      konfigurator.on('price', function (p) {
        document.querySelector('#mein-preis').textContent = p.total.toFixed(2) + ' ' + p.currency;
      });

      konfigurator.on('change', function () {
        console.log('Breite:', konfigurator.getValue('breite'));
      });
    });
  });
</script>

Drei Regeln, die fast alle Probleme vermeiden:

1. Warte auf Configento.ready. Erst dann sind alle Konfiguratoren der Seite geladen. Rufst du eine Methode vorher auf, meldet sie, dass der Konfigurator noch nicht bereit ist.
2. window.Configento gibt es erst, wenn das Skript configento.js gelaufen ist. Es wird mit defer geladen, also nach dem Aufbau der Seite. Starte deinen Code deshalb bei DOMContentLoaded oder später – nicht direkt in einem Skript im <head>.
3. Der Konfigurator sucht seine Plätze nur einmal, beim Laden: jedes Element mit data-configento. Elemente, die dein Code erst später einfügt, erkennt er nicht.

Merkmale sprichst du über ihren internen Namen (ID) an, Werte über das Feld Wert. Die numerischen IDs funktionieren ebenfalls.

Schneller laden und Platz freihalten

Drei Einstellungen am Element mit data-configento helfen beim Seitenaufbau:

Attribut	Wirkung
data-configento-min-height="640px"	Hält die Höhe frei, solange der Konfigurator lädt – die Seite darunter springt nicht, wenn der erste Schritt erscheint. Danach passt sich die Höhe wieder an.
data-configento-min-height-keep	Behält die Höhe auch danach bei
data-configento-component-json='{…}'	Die Komponente direkt in der Seite, genau so, wie GET /api/v3/components/{id} sie liefert. Dann entfällt der Abruf beim Laden. Nur sinnvoll, wenn deine Seite die veröffentlichte Fassung serverseitig aktuell hält – nach dem Veröffentlichen muss die Seite die neue Fassung ausliefern.

Im JSON-Attribut data-configento-config heißen sie minHeight, minHeightKeep und component.

Außerdem lohnt im <head> ein Hinweis an den Browser, die Verbindung zur Cloud früh aufzubauen:

<link rel="preconnect" href="https://cloud.configento.app" crossorigin>

Der Konfigurator lädt die Komponente gleich beim Start des Skripts. Wiederkehrende Besucher laden sie nicht erneut: Hat sie sich seit dem letzten Besuch nicht geändert, bestätigt der Server das nur noch kurz.

Preis in deiner Kaufleiste zeigen

window.addEventListener('DOMContentLoaded', function () {
  Configento.ready.then(function () {
    var k = Configento.first();
    var feld = document.querySelector('#kaufleiste-preis');
    k.on('price', function (p) {
      feld.textContent = p.total.toLocaleString('de-DE', { style: 'currency', currency: p.currency });
    });
  });
});

price kommt einmal direkt nach dem Laden und danach bei jeder Preisänderung. Ohne eigenen Code geht es auch mit data-configento-price-mount="#kaufleiste-preis" – dann zeichnet der Konfigurator den Preis selbst in dein Element.

Auswahl in ein eigenes Formular übernehmen

Für eine Anfrage über dein eigenes Formular prüfst du die Konfiguration mit finalize() und schreibst das Ergebnis in versteckte Felder:

<form id="anfrage" action="/anfrage" method="post">
  <input type="hidden" name="konfiguration">
  <input type="hidden" name="zusammenfassung">
  <input type="hidden" name="artikelnummer">
  <input type="hidden" name="preis">
  <button type="submit">Angebot anfordern</button>
</form>

<script>
  document.querySelector('#anfrage').addEventListener('submit', function (e) {
    e.preventDefault();
    var formular = e.target;
    var k = Configento.first();
    k.finalize().then(function (ergebnis) {
      if (!ergebnis.ok) return; // die Fehler stehen jetzt am Merkmal
      formular.konfiguration.value   = JSON.stringify(ergebnis.payload);
      formular.zusammenfassung.value = k.getSummary({ format: 'text', separator: '\n' });
      formular.artikelnummer.value   = k.getCombinedSku();
      formular.preis.value           = ergebnis.priceTotal;
      formular.submit();
    });
  });
</script>

finalize() zeigt fehlende Pflichtfelder und Fehler aus Regeln am Merkmal an, genau wie der Aktions-Button, verschickt aber selbst nichts. getCombinedSku() liefert die kombinierte Artikelnummer aus den gewählten Werten, z. B. CL-W-GR; sie steht als _combined_sku auch in ergebnis.payload.

Werte vorbelegen

Merkmale sprichst du über ihren internen Namen an, Werte über das Feld Wert:

Configento.ready.then(function () {
  var k = Configento.first();
  k.selectValue('farbe', 'anthrazit');      // Auswahl, Radio Buttons, Liste mit Bildern
  k.toggleValue('zubehoer', 'kurbel');      // Checkbox, Mehrfachauswahl
  k.setText('breite', '120');               // Eingabefeld
  k.setQuantity('schrauben', 'm6', 4);      // Mehrfachauswahl mit Mengen
});

Jeder Aufruf wirkt wie ein Klick deines Kunden: Regeln, Formeln und Preis rechnen neu. Mit resetSelection('farbe') setzt du ein Merkmal zurück.

Aus der Adresse: ?farbe=anthrazit&breite=120 übernimmst du so:

var parameter = new URLSearchParams(location.search);
if (parameter.has('breite')) k.setText('breite', parameter.get('breite'));
if (parameter.has('farbe'))  k.selectValue('farbe', parameter.get('farbe'));

Variante im Shop gewechselt: Hängen Formeln an Produktattributen wie Breite oder Gewicht, gibst du die neuen Werte mit k.setProductAttributes({ breite: '140' }) weiter. Die Auswahl bleibt, alles rechnet neu. Die Startwerte stehen beim Einbinden im JSON-Attribut als "productAttributes".

Sprache wechseln

Ist die Sprachauswahl eingeschaltet, zeigt showLanguageSelect() die Fahnen erneut – etwa für einen Button „Sprache wechseln“:

<button type="button" onclick="Configento.first().showLanguageSelect()">Sprache wechseln</button>

Die bisherige Auswahl im Konfigurator bleibt erhalten; nach der neuen Wahl läuft er in der neuen Sprache weiter. Ohne eingeschaltete Sprachauswahl oder bei einer Komponente mit nur einer Sprache passiert nichts. Die Methode darfst du auch aufrufen, bevor der Konfigurator geladen ist.

Wizard und Gruppen steuern

Bei der Darstellung Tabs und im Wizard zeigt der Konfigurator immer eine Gruppe. Mit diesen Methoden baust du eine eigene Schrittanzeige:

<ol id="schritte"></ol>

<script>
  Configento.ready.then(function () {
    var k = Configento.first();
    var liste = document.querySelector('#schritte');

    function zeichnen() {
      var aktiv = k.getActiveGroup();
      liste.innerHTML = '';
      k.getGroups().forEach(function (gruppe) {
        var punkt = document.createElement('li');
        punkt.textContent = gruppe.title;
        if (aktiv && gruppe.id === aktiv.id) punkt.className = 'aktiv';
        punkt.onclick = function () { k.setActiveGroup(gruppe.id); };
        liste.appendChild(punkt);
      });
    }

    zeichnen();
    k.on('group', zeichnen);   // nach jedem Schrittwechsel
    k.on('change', zeichnen);  // Regeln können Gruppen ein- und ausblenden
  });
</script>

getGroups() liefert die angezeigten Gruppen mit id, key, index und title, getActiveGroup() die aktuelle. setActiveGroup() wechselt per ID oder internem Namen und prüft vorwärts jeden Schritt auf dem Weg wie Weiter; nextGroup() und prevGroup() entsprechen Weiter und Zurück.

key ist der interne Name der Gruppe. Du vergibst ihn im Editor in den Einstellungen der Gruppe unter Interner Name (ID), z. B. fahrzeug. Anders als die Position bleibt er gleich, wenn du Gruppen umsortierst oder eine Regel eine Gruppe ausblendet, und er liest sich im Code besser als eine Nummer. Das Element der angezeigten Gruppe trägt ihn zusätzlich als data-configento-group-key.

Eigene Prüfung vor dem Schrittwechsel

Mit setStepGuard() prüfst du selbst, bevor dein Kunde weiterkommt – etwa ein Geburtsdatum oder eine Fahrzeug-Identnummer. Die Prüfung läuft nach der eingebauten Pflichtfeld-Prüfung und nur vorwärts:

k.setStepGuard(function (schritt) {
  if (schritt.from.key !== 'halter') return true;
  if (istVolljaehrig(k.getValue('geburtsdatum'))) return true;
  return [{ characteristic: 'geburtsdatum', message: 'Der Halter muss volljährig sein.' }];
});

true lässt den Kunden weiter, false hält ihn ohne Meldung, eine Liste hält ihn und zeigt jede Meldung am genannten Merkmal. Die Funktion darf auch ein Promise liefern, etwa für eine Prüfung über das Netz; bis zur Antwort sind Weiter und Zurück gesperrt. Wirft sie einen Fehler, wechselt der Schritt trotzdem – dein Kunde soll nicht hängen bleiben.

Eingebaute Navigation abschalten

Baust du die Schrittanzeige selbst, blendest du die eingebaute aus:

data-configento-wizard-nav	Wirkung
full (Standard)	Tabs, Fortschrittsbalken, Zurück und Weiter
buttons	Nur Zurück und Weiter
none	Nichts davon – die Schritte steuert dein Code

Dieselbe Einstellung gibt es im Editor unter Einstellungen → Allgemein → Darstellung → Wizard-Navigation (V3); das Attribut am Element hat Vorrang.

Konfiguration speichern und wieder öffnen

storeAsset() speichert die aktuelle Konfiguration und liefert { id, url }. Mit der id baust du einen Deep Link: die Adresse der Produktseite mit ?dl= und der id. Öffnet jemand diese Adresse, stellt V3 die Konfiguration im ersten Konfigurator der Seite von selbst wieder her.

k.storeAsset().then(function (gespeichert) {
  var link = new URL(location.href);
  link.searchParams.set('dl', gespeichert.id);
  navigator.clipboard.writeText(link.toString());
}).catch(function (fehler) {
  if (fehler instanceof Configento.CloudError && fehler.code === 'NO_SELECTIONS') {
    alert('Bitte zuerst etwas auswählen.');
  }
});

Selbst wiederherstellen – etwa in einem bestimmten von mehreren Konfiguratoren:

Configento.loadAsset(id, { instance: k }).then(function (daten) {
  k.restoreFromAssetJson(daten);
});

In der Vorschau des Admins kann nichts gespeichert werden (CONFIG_MISSING); teste auf deiner Website oder im Shop. Alle Fehlercodes stehen in der Referenz.

Eigenes Fenster für Bildauswahl

Manche Merkmale öffnen ein Fenster, etwa eine Liste mit Bildern in der Großansicht. Standardmäßig zeichnet V3 dieses Fenster selbst. Soll es wie die Fenster deines Shops aussehen, übergibst du einen Adapter:

Configento.setModalAdapter({
  openOverlay: function (args) {
    // args.title, args.container (vom Konfigurator befüllt), args.onClose
    var fenster = meinShop.oeffneFenster(args.title, args.container, args.onClose);
    return { close: function () { fenster.schliessen(); } };
  }
});

Häng args.container in dein Fenster ein und ruf args.onClose() auf, wenn dein Kunde es schließt. close() ruft der Konfigurator auf, wenn er das Fenster selbst schließen will. Setze den Adapter, sobald window.Configento existiert und bevor dein Kunde ein Fenster öffnet. Das Magento-Plugin bringt bereits einen Adapter für die Magento-Fenster mit.

Von Legacy umsteigen

Für die Legacy-Engine gab es eine eigene, ältere Schnittstelle: Einstellungen im Objekt _configentoSettings, das Objekt CONFIGENTO_PRODUCT, globale Objekte wie Justselling_Configento_App_Api und jQuery-Ereignisse wie configentoUpdateOptionsInDomAfter. Wechselst du auf V3, ändern sich drei Dinge:

1. Einbinden: Statt _configentoSettings und html5.js nimmst du das V3-Snippet mit data-configento-*-Attributen. Wie, steht in HTML-Snippet-Integration. Das Token ist ein anderes, es kommt aus der Karte HTML5 (V3 Beta).
2. Eigener Code: Er spricht künftig window.Configento an – oder läuft über das Kompatibilitäts-Skript weiter.
3. Funktionen: Was nur Legacy kann, steht in Frontend-Engine: Legacy oder V3.

Einstellungen

Legacy (_configentoSettings)	V3
_template	data-component-id
_customer	data-configento-customer
_token	data-configento-token – neues Token aus der Karte HTML5 (V3 Beta)
_cloudbase	data-configento-cloud-base-url
_taxrate	data-configento-tax-rate
_currencyCode	data-configento-currency
_cssPathCombinedImage bzw. .configento-combinedImage	data-configento-combined-image-mount
Element #configento-price	data-configento-price-mount
Element #configurator1	Ein Element mit data-configento
_loadjQuery, _loadChart, _loadDropzone	Entfallen – V3 bringt alles mit und braucht kein jQuery

_debug, _development, _cloudport und _productOptionId brauchst du nicht mehr.

Weg 1: Kompatibilitäts-Skript

Vor allem Shop-Themes haben über Jahre Code angesammelt, der auf die alten Objekte zugreift. Damit er unter V3 weiterläuft, lädst du vor configento.js zusätzlich configento-compat.js:

<script src="https://cloud.configento.app/configento-v3/configento-compat.js" defer></script>
<script src="https://cloud.configento.app/configento-v3/configento.js" defer></script>

Das Magento-Plugin lädt es bei V3 von selbst. Das Skript übernimmt:

Legacy	Was das Skript daraus macht
Ereignisse configentoUpdateOptionsInDomBefore/…After und configentoUpdateHeaderInDomBefore/…After	Werden bei jeder Änderung auf document ausgelöst – erreichbar mit jQuery .on() und mit addEventListener
CONFIGENTO_PRODUCT.setPrice(preis)	Wird bei jeder Preisänderung mit dem Gesamtpreis aufgerufen – sofern deine Seite CONFIGENTO_PRODUCT definiert
Element #configurator1	Wird zum Platz für den Konfigurator; die Komponenten-ID kommt aus CONFIGENTO_PRODUCT.getTemplateId()
Justselling_Configento_App_Helper.getConfigurator(), getBackendUrl()	Liefern den V3-Konfigurator bzw. die Cloud-Adresse
Justselling_Configento_App_Webshop.finalizeAction(fertig)	Prüft mit finalize(), schreibt die Konfiguration in die versteckten Formularfelder des Warenkorbs und ruft danach fertig auf
Justselling_Configento_App_CloudAsset.storeCloudAsset(…)	Speichert mit storeAsset(). Der Rückruf bekommt nur die ID, nicht Ordner und Dateiname.
Justselling_Configento_App_Wizard.validateForm() und die anderen Prüf-Funktionen	Liefern immer true – geprüft wird beim Abschließen
Justselling_Configento_App_Wizard.setActivateGroup(nr)	Wechselt zur Gruppe an dieser Position, ohne Prüfung
setDisableGroup, setEnableGroup, updateWizard	Tun nichts

Hat dein Code eines dieser Objekte schon selbst definiert, bleibt deine Fassung erhalten.

Was das Skript nicht übernimmt: Es liest _configentoSettings nicht und legt CONFIGENTO_PRODUCT nicht an – auf einer reinen HTML-Seite hat das bisher html5.js getan. Dort brauchst du also in jedem Fall die data-configento-*-Attribute. Ebenfalls nicht übernommen werden Justselling_Configento_App_Api, Justselling_Configento_App_Summary und alle übrigen Ereignisse. Dafür gibt es die Gegenstücke unten.

Weg 2: Auf die neue Schnittstelle umschreiben

Auf Dauer ist Code mit window.Configento übersichtlicher: Er bekommt Inhalte mit den Ereignissen, wirft verständliche Fehler und hängt nicht an Element-IDs. So entsprechen sich alte und neue Aufrufe – alles Neue steht in Configento.ready.then(…) an einem Konfigurator k = Configento.first():

Legacy	V3
Justselling_Configento_App_Helper.getConfigurator()	Configento.first() oder Configento.forElement(…)
Justselling_Configento_App_Api.getOptionValue(merkmal)	k.getValue('merkmal')
Justselling_Configento_App_Api.setOptionValue(merkmal, wert), setOptionValues([…])	Je nach Datentyp k.selectValue(), k.toggleValue(), k.setText() oder k.setQuantity()
Justselling_Configento_App_Api.setEventHook(…)	k.on('change', …) – ebenso price, finalize, error und group
setEventHook('configentoValidateGroupBefore', fn) (Schritt verhindern)	k.setStepGuard(fn)
getConfigurator().getActiveGroup()	k.getActiveGroup()
Justselling_Configento_App_Wizard.setActivateGroup(nr)	k.setActiveGroup(id oder interner Name)
Ereignis configentoSetActiveGroupAfter	k.on('group', …)
CONFIGENTO_PRODUCT.setPrice(preis)	k.on('price', function (p) { … p.total … }) – oder data-configento-price-mount
Justselling_Configento_App_Summary.getSummaryAsText()	k.getSummary()
Justselling_Configento_App_Wizard.validateForm()	k.finalize() → ok
Justselling_Configento_App_Webshop.finalizeAction(fertig)	k.finalize().then(…)
Justselling_Configento_App_CloudAsset.storeCloudAsset(…)	k.storeAsset() → { id, url }
Feld #configurator1-header bzw. generateHeaderValue()	k.getHeaderValue() (Base64, wie bisher) oder k.getAssetPayload() (JSON)
Ereignisse configentoUpdateOptionsInDomAfter, configentoUpdateHeaderInDomAfter, configentoApiSetOptionValueAfter	k.on('change', …)
Ereignis configentoRenderSummaryAfter	k.on('change', …) und darin k.getSummary()
Ereignis configentoFinalizeActionAfter	k.on('finalize', …)
Ereignisse configentoRenderAfter, configentoLoadTemplateAfter	Configento.ready
Ereignisse zu Diagrammen, Vorschaubildern und Datei-Uploads	Kein Gegenstück
?dl=… und ?tb=1 in der Adresse	Unverändert
Merkmale über die Adresse vorbelegen, z. B. ?breite=120	Nicht eingebaut – ein paar Zeilen, siehe Werte vorbelegen

Wie du Merkmale über die Adresse vorbelegst, zeigt Werte vorbelegen.

Unterschied bei Ereignissen: Die Legacy-Ereignisse lösten nur jQuery-Handler aus und lieferten meist keine Daten. Die V3-Ereignisse übergeben die neue Auswahl bzw. den neuen Preis direkt – du musst nichts mehr aus dem DOM lesen.

Fehlersuche

1. Configento is not defined – dein Code läuft, bevor configento.js geladen ist. Starte ihn bei DOMContentLoaded und warte auf Configento.ready. Prüfe auch, ob die Seite überhaupt V3 lädt (siehe oben).
2. Configento instance not ready beim Aufruf einer Methode – der Konfigurator lädt noch. Rufe Methoden erst in Configento.ready.then(…) auf.
3. Configento.first() liefert null – auf der Seite gibt es kein Element mit data-configento, oder es wurde erst nach dem Laden eingefügt.
4. Ein Aufruf wie selectValue() wirft einen Fehler – der interne Name oder der Wert stimmt nicht, oder der Datentyp passt nicht zur Methode. Groß- und Kleinschreibung zählt; den Namen findest du im Editor unter Interner Name (ID).
5. storeAsset() meldet CONFIG_MISSING – in der Vorschau des Admins kann nichts gespeichert werden. Teste auf deiner Website oder im Shop.
6. Alter Theme-Code wirft Fehler wie Justselling_Configento_App_Wizard is not defined – das Kompatibilitäts-Skript fehlt oder steht hinter configento.js.

Nächste Schritte

• JavaScript-API-Referenz (V3)
• HTML-Snippet-Integration
• Frontend-Engine: Legacy oder V3
• Uploads & Deep Links
• Der Aktions-Button