integracja React / Next.js#

Użyj przeglądarkowego SDK ideal.house bezpośrednio w React lub Next.js. W tym przewodniku nie ma osobnego pakietu npm ideal.house React.

Status weryfikacji: Znacznikowanie SDK zostało sprawdzone w odniesieniu do bieżącego szablonu Dashboard; oficjalna dokumentacja cyklu życia/skryptów React i Next.js została sprawdzona 7 września 2026. Nie było dostępnej aplikacji klienta ani danych uwierzytelniających produkcyjnych, dlatego zweryfikuj zbudowaną aplikację od początku do końca.

Przed załadowaniem SDK: Otwórz Panel → Ustawienia, dodaj adres źródłowy witryny sklepu do Allowed Origins (CORS) i kliknij Zapisz. Uwzględnij rzeczywistą nazwę hosta opublikowanego sklepu oraz używane adresy podglądu i środowisk testowych; wiele adresów oddzielaj przecinkami. Zobacz instrukcję konfiguracji.

Wymagania wstępne i granice#

Przygotuj Shop ID, Publishable Key, zaimportowany katalog SKU oraz wartość produktu/wariantu renderowaną po stronie klienta. Publishable Key może być obecny w znacznikowaniu przeglądarki. Zachowuj Client Secrets, klucze AI API i wszelkie prywatne dane uwierzytelniające importu produktów po stronie serwera.

SDK wykrywa kontenery DOM. React decyduje, kiedy te węzły są montowane; Twoja integracja decyduje o rozwiązaniu bieżącego wariantu i zastąpieniu kontenera, gdy jego SKU się zmienia.

Minimalna umowa SDK#

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 musi być dokładnie równy sku katalogu ideal.house.

komponent React#

Montuj nowy kontener za każdym razem, gdy kod produktu się zmienia. key wymusza na React zastąpienie węzła DOM zamiast ponownego użycia kontenera, który SDK mógł już wypełnić:

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

Przekaż SKU wybranego wariantu, a nie tytuł produktu, slug trasy, identyfikator bazy danych ani etykietę opcji. Jeśli wybór jest niekompletny, renderuj null.

loader App Router Next.js#

Umieść SDK raz w najwęższym współdzielonym układzie obejmującym strony produktów. Next.js dokumentuje afterInteractive dla skryptów ładujących się po częściowej hydratacji:

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

Renderuj IdealhouseSdk raz z układu, a następnie renderuj RoomVisualizerButton wewnątrz komponentu klienckiego, który zarządza wyborem wariantu. Wartości z prefiksem NEXT_PUBLIC_ są wysyłane do przeglądarki; używaj ich wyłącznie dla Shop ID i Publishable Key.

Dla Pages Router lub zwykłego React, utwórz skrypt raz w powłoce HTML lub użyj pojedynczego efektu najwyższego poziomu:

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

Strict Mode React celowo wykonuje dodatkowy cykl konfiguracji deweloperskiej, dlatego kontrola duplikatów jest wymagana. Nie usuwaj współdzielonego znacznika SDK, gdy pojedynczy komponent produktu jest odmontowywany.

Nawigacja, listy i warianty#

Zmiany tras po stronie klienta nie przeładowują skryptu układu. Kluczuj każdą kontrolkę produktu przez stabilną tożsamość trasy oraz SKU, jeśli ten sam SKU może pojawić się w kilku jednocześnie zamontowanych widokach. Dla siatek każda karta potrzebuje własnego SKU. Gdy przewijanie bezkońcowe dodaje karty, React naturalnie montuje nowe czyste kontenery.

Dla wyboru wariantu wyprowadzaj selectedVariant.sku ze swojego stanu handlowego i przekazuj go jako productCode. Nie wywołuj niedokumentowanej metody odświeżania SDK. Szuflady podglądu szybkiego i przejścia tras powinny odmontowywać swój poprzedni komponent, aby przetworzony DOM nie wyciekał do następnego produktu.

Jeśli hydratacja React zgłasza niezgodność, upewnij się, że renderowanie po stronie serwera i pierwsze renderowanie po stronie klienta są zgodne. Jest poprawne renderowanie bez kontenera, dopóki stan handlowy po stronie klienta nie rozwiąże SKU.

Import danych produktów#

Zmapuj kanoniczny SKU wariantu backendu handlowego na ideal.house sku. Użyj Przesyłanie produktów, a następnie skonsultuj import produktów, status zadania, lista produktów, aktualizacja produktów, usuwanie produktu oraz błędy i ponowienia.

Każde zapytanie katalogu backendu, webhook, zaplanowana synchronizacja lub usługa tokena startowego pozostaje kodem aplikacji; przeglądarkowy SDK tego nie zapewnia.

Weryfikacja i usuwanie#

Przetestuj renderowanie/hydratację po stronie serwera, twarde ładowanie, nawigację kliencką, przyciski Wstecz/Dalej w przeglądarce, zmiany wariantów, kody SKU null/nieznane, powtarzane karty, podgląd szybki, stany Suspense/ładowania, mobilność, kontrolki zgody oraz build produkcyjny. Potwierdź jedno żądanie SDK i dokładną równość Product Code/SKU w DOM. Przeszukaj zbudowane pakiety klienckie pod kątem przypadkowych sekretów.

Aby usunąć, usuń współdzielony komponent/etykietę SDK i wszystkie użycia RoomVisualizerButton, usuń dwie publiczne zmienne środowiskowe, zbuduj ponownie i zweryfikuj, czy nie pozostaje znacznikowanie SDK URL ani data-idealhouse-*.