Ideal House
Naar inhoud gaan

Integratie met React / Next.js#

Gebruik de browser-SDK van ideal.house rechtstreeks in React of Next.js. Deze handleiding bevat geen afzonderlijk ideal.house-React-npm-pakket.

Verificatiestatus: De SDK-markering is gecontroleerd aan de hand van het huidige dashboardsjabloon; de officiële levenscyclus- en scriptdocumentatie van React en Next.js is bekeken op 7 september 2026. Er was geen klanttoepassing of productietoegang beschikbaar, dus valideer de gebouwde toepassing van begin tot eind.

Voordat je de SDK laadt: Open Dashboard → Instellingen, voeg de oorsprong van je webshop toe aan Allowed Origins (CORS) en klik op Opslaan. Neem de gepubliceerde hostnaam en alle gebruikte oorsprongen van voorbeeld- of testomgevingen op; scheid meerdere oorsprongen met komma's. Zie de configuratiestappen.

Vereisten en grenzen#

Zorg voor Shop ID, Publishable Key, een geïmporteerde catalogus-SKU en een op de client weergegeven product-/variantwaarde. De Publishable Key mag in browsermarkering staan. Houd Client Secrets, AI API-sleutels en alle privétoegangsgegevens voor productimport op de server.

De SDK ontdekt DOM-containers. React bepaalt wanneer die knooppunten worden geplaatst; je integratie bepaalt de huidige variant en vervangt de container wanneer de SKU verandert.

Minimaal SDK-contract#

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 moet exact gelijk zijn aan de sku uit de ideal.house-catalogus.

Component voor React#

Plaats een nieuwe container wanneer de productcode verandert. Een key dwingt React om het DOM-knooppunt te vervangen in plaats van een container te hergebruiken die de SDK mogelijk al heeft gevuld:

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}
    />
  );
}

Geef de SKU van de geselecteerde variant door, niet een producttitel, routeslug, database-ID of optielabel. Geef bij een onvolledige selectie null weer.

Loader voor de App Router van Next.js#

Plaats de SDK eenmaal in de kleinste gedeelde lay-out die de productpagina's omvat. Next.js documenteert afterInteractive voor scripts die laden nadat een deel van de hydratatie is uitgevoerd:

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}
    />
  );
}

Geef IdealhouseSdk eenmaal weer vanuit een lay-out en geef vervolgens RoomVisualizerButton weer in een clientcomponent dat de variantselectie beheert. Waarden met het voorvoegsel NEXT_PUBLIC_ worden naar de browser verzonden; gebruik ze alleen voor Shop ID en Publishable Key.

Maak voor de Pages Router of gewone React het script eenmaal aan in de HTML-toepassingsstructuur of gebruik één effect op het hoogste niveau:

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);
}, []);

De strikte modus van React voert tijdens ontwikkeling bewust een extra initialisatiecyclus uit, dus de duplicaatcontrole is vereist. Verwijder de gedeelde SDK-tag niet wanneer een afzonderlijk productcomponent uit de weergave wordt verwijderd.

Clientroutewijzigingen laden het lay-outscript niet opnieuw. Geef elke productknop een sleutel op basis van stabiele route-identiteit plus SKU als dezelfde SKU in meerdere gelijktijdig geplaatste weergaven kan voorkomen. Bij rasters heeft elke kaart een eigen SKU nodig. Wanneer oneindig scrollen kaarten toevoegt, plaatst React vanzelf nieuwe schone containers.

Leid voor variantselectie selectedVariant.sku af uit je webshoptoestand en geef deze door als productCode. Roep geen ongedocumenteerde vernieuwingsmethode van SDK aan. Snelweergavepanelen en routeovergangen moeten hun vorige component verwijderen, zodat verwerkte DOM niet naar het volgende product doorsijpelt.

Als de hydratatie van React een verschil meldt, zorg dan dat de serverweergave en de eerste clientweergave overeenkomen. Het is geldig om geen container weer te geven totdat de webshoptoestand op de client de SKU heeft bepaald.

Productgegevens importeren#

Koppel de canonieke variant-SKU van de webshopbackend aan ideal.house sku. Gebruik Producten uploaden en raadpleeg daarna producten importeren, taakstatus, producten weergeven, producten bijwerken, product verwijderen en fouten en nieuwe pogingen.

Elke backendcatalogusquery, webhook, geplande synchronisatie of dienst voor starttokens blijft toepassingscode; de browser-SDK biedt deze niet.

Controleren en verwijderen#

Test serverweergave en hydratatie, volledig laden, clientnavigatie, de terug- en vooruitknoppen van de browser, variantwijzigingen, null-/onbekende SKUs, herhaalde kaarten, snelweergaven, Suspense-/laadtoestanden, mobiel, toestemmingsinstellingen en een productiebuild. Controleer één SDK-verzoek en exacte gelijkheid tussen de DOM-productcode en SKU. Inspecteer gebouwde clientbundels op onbedoeld opgenomen geheimen.

Verwijder het gedeelde SDK-component of de tag en alle toepassingen van RoomVisualizerButton, verwijder de twee openbare omgevingsvariabelen, bouw opnieuw en controleer dat er geen SDK-URL of data-idealhouse-*-markering overblijft.

Officiële frameworkreferenties#