Integración de BigCommerce#
Añade Room Visualizer a una tienda Stencil de BigCommerce cargando el SDK una sola vez y renderizando la SKU del producto o variante actual en un contenedor para un botón generado por el SDK.
Estado de verificación: documentación de desarrolladores de BigCommerce revisada el 7 de septiembre de 2026. No había ninguna tienda de prueba disponible. Stencil y Catalyst tienen modelos de renderizado y navegación diferentes; esta guía ofrece un camino práctico para Stencil y dirige las tiendas Catalyst a un adaptador de framework.
Antes de cargar el SDK: Abre Panel de control → Configuración, añade el origen de tu tienda a Allowed Origins (CORS) y haz clic en Guardar. Incluye el hostname publicado y cualquier origen de vista previa o staging que uses; separa múltiples orígenes con comas. Consulta pasos de configuración.
Elige una ruta de tienda#
- Stencil: instala el cargador con Script Manager o la API de Scripts y, luego, agrega el contenedor en una plantilla personalizada del tema.
- Catalyst: agrega el script y el componente en la app de Catalyst React/Next.js; sigue la guía de React / Next.js.
- Blueprint heredado: migra a una tienda compatible o solicita que un desarrollador de BigCommerce identifique un punto de inserción seguro. La documentación actual de la API de Scripts trata Blueprint por separado.
Necesitas acceso de edición de tema, un tema/canal de staging, ideal.house Shop ID y Publishable Key, y al menos un BigCommerce SKU importado en ideal.house.
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 código de producto del contenedor debe coincidir exactamente con la sku importada en el catálogo. Esta guía no asume una app de ideal.house BigCommerce.
Instalación en Stencil#
En Storefront → Script Manager, crea un script de pie de página para las páginas de productos/canal o tienda correspondientes. Pega únicamente la etiqueta de script del SDK del ejemplo, con tus credenciales seguras para el navegador. Script Manager es la contraparte del panel de control de la API de Scripts, sensible al canal.
Para una app reutilizable, utiliza la API de Scripts de BigCommerce. Esa operación de la API y el flujo OAuth de la app son responsabilidad del servicio de integración; no expongas su token de acceso en el código de la tienda.
Confirma que solo exista una etiqueta del SDK. No la incluyas también en templates/layout/base.html.
Renderizar el producto inicial#
En un tema Stencil personalizado, agrega el contenedor cerca del formulario del producto en el parcial de vista de producto que use tu tema:
{{#if product.sku}}
<div
data-idealhouse-button-container
data-product-code="{{product.sku}}"
></div>
{{/if}}
El parcial exacto varía según el tema. Usa Stencil CLI para previsualizar el tema personalizado y conserva el cambio en un tema controlado por versión, en lugar de editar el HTML de la tienda generada.
Para tarjetas, renderiza el contenedor solo cuando el contexto de la tarjeta exponga exactamente la SKU que importaste. Un producto con opciones puede no tener una SKU de variante final en una página de categoría; enlaza a la página del producto, salvo que el comprador haya seleccionado una variante completa.
Sincronizar las opciones del producto#
El JavaScript del tema Stencil recibe los cambios en las opciones del producto a través del código específico del tema para detalles del producto. Agrega un adaptador de cliente en el punto donde el tema actual haya resuelto la respuesta de la variante final:
export function replaceIdealhouseContainer(host, sku) {
host.replaceChildren();
const code = typeof sku === 'string' ? sku.trim() : '';
if (!code) return;
const container = document.createElement('div');
container.dataset.idealhouseButtonContainer = '';
container.dataset.productCode = code;
host.append(container);
}
Pasa la SKU de la variante resuelta desde tu devolución de llamada del tema. Los temas de BigCommerce pueden personalizar o reemplazar la implementación predeterminada de detalles del producto, por lo que esta guía no inventa un evento global de cambio de opción. Elimina el contenedor anterior antes de insertar el nuevo.
Vista rápida y páginas dinámicas#
La Vista rápida, la búsqueda facetada, la paginación y la navegación del lado del cliente pueden reemplazar el DOM del producto. Agrega un contenedor limpio en cada plantilla renderizada e invoca el mismo puente después de la devolución de llamada documentada de renderizado del tema. No clones un contenedor ya poblado por el SDK.
Catalyst usa renderizado React del lado del cliente y no tiene contexto Handlebars de Stencil. Carga el SDK una vez en el shell de la app y usa el SKU de la variante seleccionada como clave del componente del visualizador, como se muestra en la guía de React/Next.js.
Importar y mapear datos del producto#
Mapea los valores de sku de BigCommerce a sku de ideal.house; para variantes, usa cada SKU de variante en lugar del ID de producto padre. Los datos del catálogo de BigCommerce no se sincronizan mediante el SDK del navegador.
Usa Carga de productos para el contrato de importación aprobado, luego consulta importar productos, estado del trabajo, listar productos, actualizar productos, eliminar producto y errores y reintentos. Cualquier exportación, webhook o sincronización programada de la API de BigCommerce es un adaptador operado por el cliente.
Verificar y eliminar#
Antes del lanzamiento, prueba un producto simple, cada combinación de opciones, un producto sin SKU y una SKU faltante en ideal.house. Verifica la página del producto, las tarjetas de categoría, la Vista rápida, la navegación facetada, atrás/adelante del navegador, el diseño móvil, el comportamiento del consentimiento y cada canal de tienda activo. En DevTools, confirma una solicitud SDK exitosa y una coincidencia exacta entre el Código del producto y la SKU.
Para eliminar la integración, elimina la entrada de Script Manager o el registro de la API de Scripts, retira todo el marcado del contenedor y el código del adaptador en los temas, publica el tema limpio y, luego, vacía las caches de la tienda/CDN. Confirma que la solicitud del SDK esté ausente en cada canal.