Ideal House
Passa al contenuto

Integrazione con React / Next.js#

Usa direttamente SDK di ideal.house per browser in React o Next.js. Questa guida non prevede un pacchetto npm ideal.house separato per React.

Stato della verifica: il codice SDK è stato controllato rispetto al modello attuale del pannello di controllo; la documentazione ufficiale di React e Next.js su ciclo di vita/script è stata esaminata il 7 settembre 2026. Non erano disponibili un'applicazione cliente né credenziali di produzione, quindi verifica l'applicazione compilata dall'inizio alla fine.

Prima di caricare SDK: apri Pannello di controllo → Impostazioni, aggiungi l’origine del negozio a Allowed Origins (CORS) e fai clic su Salva. Includi il nome host pubblicato e le origini di anteprima o preproduzione utilizzate; separa più origini con virgole. Consulta i passaggi di configurazione.

Prerequisiti e limiti#

Prepara Shop ID, Publishable Key, uno SKU importato nel catalogo e un valore prodotto/variante generato sul client. La Publishable Key può essere presente nel codice del browser. Conserva Client Secrets, chiavi AI API ed eventuali credenziali private per l'importazione dei prodotti sul server.

SDK individua i contenitori DOM. React controlla quando questi nodi vengono montati; l'integrazione è responsabile di determinare la variante corrente e sostituire il contenitore quando cambia il suo SKU.

Contratto minimo di 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 deve essere esattamente uguale allo sku nel catalogo ideal.house.

Componente React#

Monta un nuovo contenitore ogni volta che cambia il codice prodotto. Una key obbliga React a sostituire il nodo DOM anziché riutilizzare un contenitore che SDK potrebbe aver già popolato:

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

Passa lo SKU della variante selezionata, non un titolo prodotto, uno slug del percorso, un identificatore di database o un'etichetta di opzione. Se la selezione è incompleta, visualizza null.

Caricatore per App Router di Next.js#

Inserisci SDK una sola volta nel layout condiviso più circoscritto che comprende le pagine prodotto. Next.js documenta afterInteractive per gli script caricati dopo una parte dell'idratazione:

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

Visualizza IdealhouseSdk una sola volta da un layout, quindi visualizza RoomVisualizerButton all'interno di un componente client che gestisce la selezione della variante. I valori con prefisso NEXT_PUBLIC_ vengono inviati al browser; usali soltanto per Shop ID e Publishable Key.

Per Pages Router o React senza altri framework, crea lo script una sola volta nella struttura HTML oppure usa un unico effetto al livello principale:

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

La modalità rigorosa di React esegue intenzionalmente un ciclo di configurazione aggiuntivo durante lo sviluppo, quindi il controllo dei duplicati è obbligatorio. Non rimuovere il tag SDK condiviso quando viene smontato un singolo componente prodotto.

I cambi di percorso sul client non ricaricano lo script del layout. Assegna a ogni controllo prodotto una chiave formata dall'identità stabile del percorso e dallo SKU se lo stesso SKU può comparire in più viste montate contemporaneamente. Nelle griglie, ogni scheda richiede un proprio SKU. Quando lo scorrimento infinito aggiunge schede, React monta naturalmente nuovi contenitori puliti.

Per la selezione delle varianti, ricava selectedVariant.sku dallo stato del tuo sistema commerciale e passalo come productCode. Non chiamare un metodo di aggiornamento SDK non documentato. I pannelli di anteprima rapida e le transizioni tra percorsi devono smontare il componente precedente, in modo che il DOM già elaborato non venga trasferito al prodotto successivo.

Se l'idratazione di React segnala una mancata corrispondenza, assicurati che la visualizzazione del server e la prima visualizzazione sul client coincidano. È corretto non visualizzare alcun contenitore finché lo stato commerciale sul client non ha determinato lo SKU.

Importare i dati dei prodotti#

Associa lo SKU canonico della variante nel sistema commerciale di backend a sku di ideal.house. Usa Caricamento dei prodotti, quindi consulta importare prodotti, stato del processo, elencare prodotti, aggiornare prodotti, eliminare un prodotto ed errori e nuovi tentativi.

Qualsiasi interrogazione del catalogo sul backend, webhook, sincronizzazione pianificata o servizio di token di avvio rimane codice dell'applicazione; SDK per browser non fornisce queste funzionalità.

Verificare e rimuovere#

Prova visualizzazione sul server/idratazione, caricamento completo, navigazione sul client, Indietro/Avanti del browser, cambi di variante, SKUs nulli/sconosciuti, schede ripetute, anteprima rapida, Suspense/stati di caricamento, dispositivi mobili, controlli del consenso e una compilazione di produzione. Verifica una sola richiesta SDK e l'uguaglianza esatta Product Code/SKU nel DOM. Esamina i pacchetti client compilati per individuare eventuali segreti inclusi per errore.

Per rimuovere l'integrazione, elimina il componente/tag SDK condiviso e tutti gli usi di RoomVisualizerButton, rimuovi le due variabili di ambiente pubbliche, compila nuovamente e verifica che non rimangano la URL di SDK né il codice data-idealhouse-*.

Riferimenti ufficiali dei framework#