Integración de React / Next.js#
Usa el SDK del navegador de ideal.house directamente en React o Next.js. No hay paquete npm separado de React ideal.house en esta guía.
Estado de verificación: Se verificó el marcado SDK contra la plantilla actual del Panel de control; se revisó la documentación oficial de React y Next.js sobre ciclo de vida/script el 7 de septiembre de 2026. No había credenciales de aplicación de cliente ni producción disponibles, por lo que se debe validar la aplicación construida de extremo a extremo.
Antes de cargar el SDK: abre Panel de control → Configuración, añade tu origen de tienda en línea a Allowed Origins (CORS) y haz clic en Save. Incluye el hostname publicado y cualquier origen de vista previa o staging que utilices; separa varios orígenes con comas. Consulta pasos de configuración.
Requisitos previos y límites#
Prepare Shop ID, Publishable Key, un SKU importado del catálogo y un valor de producto/variante representado en el navegador. El Publishable Key puede estar presente en el marcado del navegador. Mantenga los Client Secrets, las claves AI API y cualquier credencial privada de importación de productos en el servidor.
El SDK descubre los contenedores del DOM. React decide cuándo se montan esos nodos; tu integración se encarga de resolver la variante actual y reemplazar el contenedor cuando su SKU cambia.
Contrato mínimo del SDK#
<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>
El data-product-code debe ser exactamente igual al sku del catálogo de ideal.house.
Componente de React#
Monta un contenedor nuevo cada vez que cambie el código del producto. Un key fuerza a React a reemplazar el nodo del DOM en lugar de reutilizar un contenedor que el SDK pueda haber poblado ya:
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}
/>
);
}
Pasa el SKU de la variante seleccionada, no el título del producto, el slug de ruta, el ID de base de datos o la etiqueta de opción. Si la selección está incompleta, renderiza null.
Cargador del App Router de Next.js#
Coloca el SDK una vez en el diseño compartido más estrecho que cubra las páginas de producto. Next.js documenta afterInteractive para scripts que se cargan después de cierta hidratación:
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}
/>
);
}
Renderice IdealhouseSdk una vez desde un layout, luego renderice RoomVisualizerButton dentro de un Componente de Cliente que gestione la selección de variantes. Los valores con prefijo NEXT_PUBLIC_ se envían al navegador; úselos solo para Shop ID y Publishable Key.
Para el Pages Router o React plano, crea el script una vez en la plantilla HTML, o usa un único efecto de nivel superior:
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);
}, []);
El Strict Mode de React realiza intencionalmente un ciclo adicional de configuración de desarrollo, por lo que la verificación de duplicados es requerida. No elimines la etiqueta compartida del SDK cuando un componente de producto individual se desmonte.
Navegación, listas y variantes#
Los cambios de ruta del lado del cliente no vuelven a cargar el script del diseño. Asigna clave a cada control de producto por identidad de ruta estable más SKU si el mismo SKU puede aparecer en varias vistas montadas simultáneamente. Para cuadrículas, cada tarjeta necesita su propio SKU. Cuando el scroll infinito agrega tarjetas, React monta naturalmente nuevos contenedores limpios.
Para la selección de variantes, deriva selectedVariant.sku de tu estado de comercio y pásalo como productCode. No llames a ningún método de refrescado del SDK no documentado. Los cajones de vista rápida y las transiciones de ruta deben desmontar su componente previo para que el marcado del DOM procesado no se filtre al siguiente producto.
Si la hidratación de React informa una discrepancia, asegúrate de que el servidor y el primer renderizado del cliente coincidan. Es válido no renderizar ningún contenedor hasta que el estado de comercio del cliente haya resuelto el SKU.
Importar datos del producto#
Mapea el SKU de variante canónica del backend de comercio al sku de ideal.house. Usa Carga de productos, luego consulta importar productos, estado del trabajo, listar productos, actualizar productos, eliminar producto y errores y reintentos.
Cualquier consulta de catálogo del backend, webhook, sincronización programada o servicio de token de lanzamiento permanece como código de la aplicación; el SDK del navegador no lo proporciona.
Verificar y eliminar#
Prueba el renderizado/ hidratación del servidor, una carga dura, la navegación del cliente, Atrás/Adelante del navegador, cambios de variante, SKUs nulos/desconocidos, tarjetas repetidas, vista rápida, estados de Suspense/carga, móvil, controles de consentimiento y una compilación de producción. Confirma una sola solicitud del SDK y la igualdad exacta del Product Code/SKU del DOM. Inspecciona los bundles de cliente compilados en busca de secretos accidentales.
Para eliminar, borra el componente/etiqueta compartida del SDK y todos los usos de RoomVisualizerButton, elimina las dos variables de entorno públicas, compila de nuevo y verifica que no quede ningún marcado del SDK de URL o data-idealhouse-*.