Docs  /  Integrationen  /  JavaScript-API-Referenz (V3)

JavaScript-API-Referenz (V3)

Zuletzt aktualisiert: 20. Oktober 2026

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.0.0-alpha.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
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()
}

Reine Abfrage – beliebig oft aufrufbar.

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 hinter dem Wert
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.

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. 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 };
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. 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

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

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

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 Beta)
data-configento-token-endpoint tokenEndpoint Adresse, die kurzlebige Tokens ausgibt (Shop-Plugins)
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.

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.

Versionen und Zusagen

Configento.version folgt Semantic Versioning. Bis zur Version 3.0.0 können sich Fehlertexte und kleine Details noch ändern; die Methoden und Datentypen dieser Seite bleiben. Ab 3.0.0 gilt: 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, nicht auf CSS-Klassen oder die DOM-Struktur des Konfigurators. Stabil sind nur die Attribute data-configento-char-id, data-configento-group-id und data-configento-group-key.

Nächste Schritte

← Alle Artikel 14 Tage kostenlos testen