Ecwid-Integration#

Verwenden Sie eine benutzerdefinierte Ecwid-Onlineshop-App und den dokumentierten Lebenszyklus der Storefront JS API, um Room Visualizer-Steuerelemente auf Ecwid-Produktseiten hinzuzufügen.

Überprüfungsstatus: Die Dokumentation der Ecwid Storefront JS API wurde am 7. September 2026 geprüft. Es stand weder eine Ecwid-App noch ein Händler-Testshop zur Verfügung. Die genauen Felder der Seitendaten müssen vor der Bereitstellung anhand der aktuellen OnPageLoaded-Referenz geprüft werden.

Vor dem Laden des SDK: Öffnen Sie Dashboard → Einstellungen, fügen Sie den Origin Ihres Onlineshops zu Allowed Origins (CORS) hinzu und klicken Sie auf Speichern. Berücksichtigen Sie den veröffentlichten Hostnamen sowie alle verwendeten Vorschau- oder Staging-Origins; trennen Sie mehrere Origins durch Kommas. Siehe Konfigurationsschritte.

Voraussetzungen und unterstützter Pfad#

Ecwid erfordert eine benutzerdefinierte App mit einer selbst gehosteten JavaScript-Datei für dauerhafte Storefront-Anpassungen. Bereiten Sie einen Ecwid-Entwicklungsstore/App, eine über HTTPS gehostete Adapter-Datei, Shop ID, Publishable Key und importierte Produkt-/Varianten-SKUs vor.

Wenn Ecwid in ein anderes CMS eingebettet ist, bleibt die benutzerdefinierte Onlineshop-App der zuverlässige Ort für den Code, da sie zusammen mit dem Ecwid-Onlineshop ausgeführt wird. Ein Skript der übergeordneten Seite teilt nicht in jedem Einbettungsmodus denselben Lebenszyklus oder dasselbe Dokument.

Minimale SDK-Schnittstelle#

html

<script
  src="https://sdk.ideal.house/sdk.js"
  data-shop-id="<SHOP_ID>"
  data-publishable-key="<PUBLISHABLE_KEY>"
  async
></script>

<div data-idealhouse-button-container data-product-code="CHAIR-OAK-01"></div>

Verwenden Sie exakt die Ecwid-SKU, die Sie als ideal.house-sku importiert haben.

Initialisieren Sie Ihre Ecwid Storefront-App#

Folgen Sie dem Ecwid-Schnellstart für benutzerdefinierte Onlineshops, um die selbst gehostete Datei zu registrieren. Starten Sie sie über den dokumentierten Callback für die Bereitschaft der API und laden Sie dann das ideal.house-SDK einmal:

Ecwid.OnAPILoaded.add(function () {
  if (document.querySelector('script[src="https://sdk.ideal.house/sdk.js"]')) return;

  const script = document.createElement('script');
  script.src = 'https://sdk.ideal.house/sdk.js';
  script.async = true;
  script.dataset.shopId = '<SHOP_ID>';
  script.dataset.publishableKey = '<PUBLISHABLE_KEY>';
  document.head.append(script);
});

Für eine Multi-Store-App rufen Sie die beiden öffentlichen ideal.house-Werte aus der sicheren öffentlichen Konfiguration Ihrer App ab. Geben Sie niemals ein Ecwid-App-Geheimnis, Access Token oder ideal.house Client Secret in diese Datei ein.

Auf Produktseiten rendern#

Ecwid dokumentiert Ecwid.OnPageLoaded.add() und übergibt Seiteninformationen an dessen Callback. Prüfen Sie anhand der aktuellen API-Referenz den Typ und die Kennung der Produktseite. Rufen oder lesen Sie die Produktdaten über die unterstützte Clientschnittstelle von Ecwid ab und übergeben Sie anschließend die ermittelte SKU an:

function mountIdealhouse(host, sku) {
  host.replaceChildren();
  const code = String(sku || '').trim();
  if (!code) return;

  const container = document.createElement('div');
  container.dataset.idealhouseButtonContainer = '';
  container.dataset.productCode = code;
  host.append(container);
}

Fügen Sie host an einer stabilen Stelle innerhalb der Produktdetails ein, nachdem Ecwid die Seite fertig gerendert hat. Entfernen Sie das vorherige Hostelement, wenn sich der Seitentyp ändert. Der DOM-Selektor und die Zuordnung der Seitendaten zum Produkt sind kundenseitiger Adaptercode, da sich Ecwid-Onlineshop-Layouts und Versionen der Seitendaten ändern können.

Warten Sie nach der Auswahl von Produktoptionen, bis Ecwid die kaufbare Variante und deren SKU ermittelt hat. Rufen Sie mountIdealhouse() mit dieser SKU auf oder leeren Sie das Hostelement bei einer unvollständigen Auswahl. Setzen Sie Optionsbeschriftungen nicht zusammen, um daraus einen Code zu erzeugen.

Ecwid ist ein Onlineshop als Einzelseitenanwendung. Verwenden Sie seinen dokumentierten Seitenlebenszyklus (OnPageLoaded/Callbacks für Seitenwechsel), statt ausschließlich auf DOMContentLoaded im Browser zu reagieren. Bei Kategorie- und Suchnavigation, Browser-Zurück/Vorwärts, eingebetteten Widgets und Produkt-Pop-ups müssen veraltete Produkthostelemente entfernt und nach dem Rendern neue Container eingefügt werden.

Produkte importieren#

Exportieren Sie die Ecwid-Produkt- und -Varianten-SKU-Felder und ordnen Sie sie den ideal.house-sku-Feldern zu. Verwenden Sie Produkt-Upload, einschließlich Produkte importieren, Aufgabenstatus, Produkte auflisten, Produkte aktualisieren, Produkt löschen und Fehler und Wiederholungen.

Jede Ecwid REST API-Export-, Webhook-, OAuth-Installation oder wiederkehrende Synchronisation liegt in der Verantwortung des Kunden und muss serverseitig mit der entsprechenden Ecwid-Autorisierung implementiert werden.

Überprüfung und Entfernen#

Testen Sie App-Installation, API-Initialisierung, Wechsel zwischen Produkt-, Kategorie- und Suchseiten, jede Variante, fehlende und unbekannte SKUs, Browser-Zurück/Vorwärts, ein auf einer anderen Website eingebettetes Ecwid-Widget, mobiles Layout, Einwilligungen sowie angemeldete und abgemeldete Kunden. Prüfen Sie, dass im Dokument mit dem Hostelement genau eine SDK-Anfrage erfolgt und die SKU exakt übereinstimmt.

Trennen Sie zum Entfernen die selbst gehostete JavaScript-Datei von der benutzerdefinierten App oder deinstallieren Sie die App. Entfernen Sie eingefügte Hostelemente und Listener und prüfen Sie, dass die SDK-URL und alle data-idealhouse-*-Knoten nach der Onlineshop-Navigation und einem vollständigen Neuladen verschwinden.