Ideal House
Zum Hauptinhalt springen

Integration von React / Next.js#

Verwenden Sie die ideal.house-Browser-SDK direkt in React oder Next.js. In dieser Anleitung gibt es kein separates ideal.house React npm-Paket.

Verifizierungsstatus: Das SDK-Markup wurde mit der aktuellen Dashboard-Vorlage abgeglichen. Die offiziellen Lebenszyklus- und Skriptdokumentationen von React und Next.js wurden am 7. September 2026 geprüft. Es standen keine Kundenanwendung und keine Produktionszugangsdaten zur Verfügung. Validieren Sie daher die fertig gebaute Anwendung vollständig.

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 Grenzen#

Bereiten Sie Shop ID, Publishable Key, eine importierte Katalog-SKU und einen clientseitig gerenderten Produkt-/Variantenwert vor. Der Publishable Key darf im Browser-Markup enthalten sein. Bewahren Sie Client Secrets, AI API-Schlüssel und alle privaten Zugangsdaten für den Produktimport auf dem Server auf.

Das SDK erkennt DOM-Container. React steuert, wann diese Knoten eingebunden werden. Ihre Integration ist dafür verantwortlich, die aktuelle Variante zu ermitteln und den Container auszutauschen, wenn sich deren SKU ändert.

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>

data-product-code muss exakt mit dem ideal.house-Katalog-sku übereinstimmen.

React-Komponente#

Binden Sie bei jeder Änderung des Produktcodes einen neuen Container ein. Ein key zwingt React, den DOM-Knoten zu ersetzen, anstatt einen Container zu wiederverwenden, den die SDK möglicherweise bereits befüllt hat:

tsx
type RoomVisualizerButtonProps = {
  productCode?: string | null;
};

export function RoomVisualizerButton({ productCode }: RoomVisualizerButtonProps) {
  const code = productCode?.trim();
  if (!code) return null;

  return (
    <div
      key={code}
      data-idealhouse-button-container
      data-product-code={code}
    />
  );
}

Übergeben Sie den ausgewählten Varianten-SKU, nicht den Produkttitel, den Routen-Slug, die Datenbank-ID oder das Optionslabel. Wenn die Auswahl unvollständig ist, rendern Sie null.

Loader für den Next.js App Router#

Platzieren Sie die SDK einmalig im engsten gemeinsamen Layout, das Produktseiten abdeckt. Next.js dokumentiert afterInteractive für Skripte, die nach einer teilweisen Hydration geladen werden:

tsx
import Script from 'next/script';

export function IdealhouseSdk() {
  return (
    <Script
      id="idealhouse-room-visualizer-sdk"
      src="https://sdk.ideal.house/sdk.js"
      strategy="afterInteractive"
      data-shop-id={process.env.NEXT_PUBLIC_IDEALHOUSE_SHOP_ID}
      data-publishable-key={process.env.NEXT_PUBLIC_IDEALHOUSE_PUBLISHABLE_KEY}
    />
  );
}

Rendern Sie IdealhouseSdk einmalig aus einem Layout und rendern Sie dann RoomVisualizerButton innerhalb einer Client-Komponente, die die Variantenwahl steuert. Werte mit dem Präfix NEXT_PUBLIC_ werden an den Browser gesendet; verwenden Sie diese nur für Shop ID und Publishable Key.

Für den Pages Router oder reines React, erstellen Sie das Skript einmalig in der HTML-Hülle oder verwenden Sie einen einzelnen Top-Level-Effekt:

tsx
useEffect(() => {
  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);
}, []);

React Strict Mode führt während der Entwicklung absichtlich einen zusätzlichen Einrichtungszyklus aus. Daher ist die Prüfung auf Duplikate erforderlich. Entfernen Sie das gemeinsam verwendete SDK-Tag nicht, wenn eine einzelne Produktkomponente ausgehängt wird.

Clientseitige Routenänderungen laden das Layout-Skript nicht neu. Vergeben Sie für jede Produktsteuerung einen Schlüssel aus stabiler Routenidentität plus SKU, falls derselbe SKU in mehreren gleichzeitig eingebundenen Ansichten erscheinen kann. Für Raster benötigt jede Karte ihren eigenen SKU. Wenn unendliches Scrollen Karten hinzufügt, bindet React automatisch neue, saubere Container ein.

Leiten Sie für die Variantenauswahl selectedVariant.sku aus Ihrem Commerce-Zustand ab und übergeben Sie den Wert als productCode. Rufen Sie keine undokumentierte SDK-Aktualisierungsmethode auf. Beim Schließen von Schnellansichten und bei Routenwechseln sollte die vorherige Komponente ausgehängt werden, damit bereits verarbeitetes DOM nicht für das nächste Produkt weiterverwendet wird.

Wenn die React-Hydration eine Abweichung meldet, stellen Sie sicher, dass Server und erste Client-Renderung übereinstimmen. Es ist gültig, keinen Container zu rendern, bis der Client-Commerce-Zustand den SKU aufgelöst hat.

Produktdaten importieren#

Mappen Sie den kanonischen Varianten-SKU des Commerce-Backends auf ideal.house sku. Verwenden Sie Produktimport und konsultieren Sie anschließend Produkte importieren, Auftragsstatus, Produkte auflisten, Produkte aktualisieren, Produkt löschen und Fehler und Wiederholungsversuche.

Jede Backend-Katalogabfrage, Webhook, geplante Synchronisation oder Launch-Token-Dienst bleibt Anwendungscode; die Browser-SDK stellt diese nicht bereit.

Überprüfung und Entfernen#

Testen Sie Server-Render/Hydration, einen harten Ladevorgang, Client-Navigation, Browser-Zurück/Weiter, Variantenänderungen, null/unkannte SKUs, wiederholte Karten, Quick-View, Suspense/Ladezustände, Mobile, Zustimmungskontrollen und einen Produktions-Build. Bestätigen Sie eine einzige SDK-Anfrage und die exakte Gleichheit von DOM Produktcode/SKU. Prüfen Sie die gebauten Client-Bundles auf versehentlich enthaltene Geheimnisse.

Zur Entfernung löschen Sie die gemeinsame SDK-Komponente/das Tag und alle RoomVisualizerButton-Verwendungen, entfernen Sie die zwei öffentlichen Umgebungsvariablen, bauen Sie erneut und stellen Sie sicher, dass keine SDK URL oder data-idealhouse-*-Markierung mehr vorhanden ist.

Offizielle Framework-Referenzen#