Ideal House
Zum Hauptinhalt springen

BigCommerce-Integration#

Fügen Sie Room Visualizer zu einer BigCommerce-Stencil-Storefront hinzu, indem Sie das SDK einmal laden und das aktuelle Produkt oder die Variante-SKU in einen generierten Button-Container rendern.

Verifizierungsstatus: BigCommerce-Entwicklerdokumentation am 7. September 2026 überprüft. Es war kein Test-Shop verfügbar. Stencil und Catalyst haben unterschiedliche Render- und Navigationsmodelle; dieser Leitfaden bietet einen umsetzbaren Stencil-Pfad und verweist Catalyst-Storefronts an einen Framework-Adapter.

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.

Wählen Sie einen Storefront-Pfad#

  • Stencil: Installieren Sie den Lader mit dem Script Manager oder der Scripts-API und fügen Sie den Container in eine Custom-Theme-Vorlage hinzu.
  • Catalyst: Fügen Sie das Skript und die Komponente in die Catalyst-React/Next.js-App hinzu; folgen Sie React / Next.js.
  • Älteres Blueprint: Wechseln Sie zu einem unterstützten Onlineshop oder lassen Sie einen BigCommerce-Entwickler einen sicheren Einfügepunkt bestimmen. Die aktuelle Scripts-API-Dokumentation behandelt Blueprint gesondert.

Sie benötigen Theme-Bearbeitungszugriff, ein Staging-Theme/Kanal, ideal.house Shop ID und Publishable Key sowie mindestens einen in ideal.house importierten BigCommerce SKU.

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>

Der Produktcode des Containers muss exakt mit dem importierten Katalog-sku übereinstimmen. Dieser Leitfaden nimmt keine ideal.house BigCommerce-App an.

Installation auf Stencil#

Erstellen Sie in Storefront → Script Manager ein Footer-Skript für den relevanten Storefront/Kanal und die Produktseiten. Fügen Sie nur das SDK-Skripttag aus dem Beispiel mit Ihren browser-sicheren Zugangsdaten ein. Der Script Manager ist das Gegenstück im Control-Panel zur kanalbewussten Scripts-API.

Verwenden Sie für eine wiederverwendbare App stattdessen die Scripts-API von BigCommerce. Diese API-Operation und der App-OAuth-Flow sind die Verantwortung Ihres Integrationsdienstes; exponieren Sie seinen Zugriffstoken nicht im Storefront-Code.

Stellen Sie sicher, dass nur ein SDK-Tag existiert. Fügen Sie es nicht auch in templates/layout/base.html ein.

Rendern Sie das initiale Produkt#

Fügen Sie in einem Custom-Stencil-Theme den Container in der Nähe des Produktformulars in der Produktansicht-Partial hinzu, die von Ihrem Theme verwendet wird:

handlebars
{{#if product.sku}}
  <div
    data-idealhouse-button-container
    data-product-code="{{product.sku}}"
  ></div>
{{/if}}

Die genaue Teilvorlage hängt vom Theme ab. Verwenden Sie Stencil CLI, um das angepasste Theme in der Vorschau anzuzeigen, und verwalten Sie die Änderung in einem versionierten Theme, statt generiertes HTML des Onlineshops zu bearbeiten.

Rendern Sie für Karten den Container nur, wenn der Kartenkontext die exakte SKU offenlegt, die Sie importiert haben. Ein Produkt mit Optionen hat auf einer Kategorie-Seite möglicherweise keine finale Variante-SKU; verlinken Sie zur Produktseite, es sei denn, der Käufer hat eine vollständige Variante ausgewählt.

Synchronisieren Sie Produktoptionen#

Das Stencil-Theme-JavaScript erhält Produktoptionsänderungen über theme-spezifischen Produkt-Details-Code. Fügen Sie einen Kundenadapter an der Stelle hinzu, an der das aktuelle Theme die finale Variantenantwort aufgelöst hat:

js
export function replaceIdealhouseContainer(host, sku) {
  host.replaceChildren();
  const code = typeof sku === 'string' ? sku.trim() : '';
  if (!code) return;

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

Geben Sie die aufgelöste Variante-SKU aus Ihrem Theme-Callback weiter. BigCommerce-Themes können die Standard-Produkt-Details-Implementierung anpassen oder ersetzen, daher erfindet dieser Leitfaden kein globales Optionsänderungsereignis. Entfernen Sie den alten Container, bevor Sie den neuen einfügen.

Schnellansicht und dynamische Seiten#

Schnellansicht, Facetten-Suche, Paginierung und clientseitige Navigation können Produkt-DOM ersetzen. Fügen Sie in jeder gerenderten Vorlage einen sauberen Container hinzu und rufen Sie dieselbe Brücke nach dem dokumentierten Render-Callback des Themes auf. Klonen Sie keinen Container, der bereits vom SDK befüllt wurde.

Catalyst verwendet clientseitiges React-Rendering und besitzt keinen Stencil-Handlebars-Kontext. Laden Sie das SDK einmal in der Anwendungshülle und verwenden Sie die ausgewählte Varianten-SKU als Schlüssel der Visualisierungskomponente, wie im React/Next.js-Leitfaden gezeigt.

Importieren und zuordnen von Produktdaten#

Ordnen Sie BigCommerce-sku-Werte zu ideal.house-sku zu; für Varianten verwenden Sie jede Variante-SKU anstelle der übergeordneten Produkt-ID. BigCommerce-Katalogdaten werden nicht durch den Browser-SDK synchronisiert.

Verwenden Sie Produktimport für den genehmigten Importvertrag und prüfen Sie dann Produkte importieren, Auftragsstatus, Produkte auflisten, Produkte aktualisieren, Produkt löschen und Fehler und Wiederholungsversuche. Jeder BigCommerce-API-Export, Webhook oder geplante Synchronisation ist ein kundengeführter Adapter.

Überprüfung und Entfernen#

Testen Sie vor dem Start ein einfaches Produkt, jede Optionskombination, ein Produkt ohne SKU und eine in ideal.house fehlende SKU. Prüfen Sie die Produktseite, Kategorie-Karten, Schnellansicht, Facetten-Navigation, Browser-Zurück/Weiter, Mobile-Layout, Einwilligungsverhalten und jeden aktiven Storefront-Kanal. Verifizieren Sie in DevTools eine erfolgreiche SDK-Anfrage und eine exakte Produktcode/SKU-Übereinstimmung.

Löschen Sie zum Entfernen der Integration den Script-Manager-Eintrag oder den Scripts-API-Datensatz. Entfernen Sie das gesamte Container-Markup und den Adaptercode aus dem Theme, veröffentlichen Sie das bereinigte Theme und leeren Sie die Onlineshop-/CDN-Caches. Prüfen Sie, dass in keinem Kanal mehr eine SDK-Anfrage erfolgt.

Offizielle Plattformreferenzen#