integración de Ecwid#

Usa una aplicación de tienda personalizada de Ecwid y el ciclo de vida documentado de la API de JS de Storefront para agregar controles de Room Visualizer a las páginas de productos de Ecwid.

Estado de verificación: Se revisó la documentación de Ecwid Storefront JS API el 7 de septiembre de 2026. No había ninguna app Ecwid ni tienda de prueba de comerciante disponible. Los campos exactos de la carga útil de la página deben confirmarse contra la referencia actual de OnPageLoaded antes del despliegue.

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 ruta compatible#

Ecwid requiere una app personalizada con un archivo JavaScript autoalojado para una personalización duradera de la storefront. Prepare una tienda/app de desarrollo Ecwid, un archivo adaptador alojado en HTTPS, Shop ID, Publishable Key y SKUs de producto/variación importados.

Si Ecwid está incrustado en otro CMS, la aplicación de tienda personalizada sigue siendo el lugar confiable para el código porque se ejecuta con la tienda Ecwid. Un script de la página principal puede no compartir el mismo ciclo de vida o documento en todos los modos de incrustación.

Contrato mínimo del 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>

Usa el SKU exacto de Ecwid que importaste como sku de ideal.house.

Inicializa tu aplicación de tienda Ecwid#

Sigue la guía rápida de tienda personalizada de Ecwid para registrar el archivo autoalojado. Inícialo con la devolución de llamada lista para la API documentada, luego carga el SDK de ideal.house una vez:

Ecwid.OnAPILoaded.add(function () {
  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);
});

Para una aplicación de múltiples tiendas, obtén los dos valores públicos de ideal.house desde la configuración pública segura de tu aplicación. Nunca coloques un secreto de aplicación, token de acceso de Ecwid, o Client Secret de ideal.house en este archivo.

Renderizar en páginas de productos#

Ecwid documenta Ecwid.OnPageLoaded.add() y proporciona información de la página a su devolución de llamada. Usa la referencia actual de la API para confirmar el tipo e identificador de la página de producto, obtén o lee los datos del producto a través de la interfaz cliente admitida por Ecwid, luego pasa el SKU resuelto a:

function mountIdealhouse(host, sku) {
  host.replaceChildren();
  const code = String(sku || '').trim();
  if (!code) return;

  const container = document.createElement('div');
  container.dataset.idealhouseButtonContainer = '';
  container.dataset.productCode = code;
  host.append(container);
}

Inserta el host en una ubicación estable de detalles del producto después de que Ecwid termine de renderizar la página. Elimina el host anterior cuando cambie el tipo de página. El selector del DOM y la búsqueda de página a producto son código adaptador del cliente porque los diseños de la tienda Ecwid y las versiones de los payloads pueden cambiar.

Opciones y navegación#

Cuando un comprador elija opciones del producto, espera a que Ecwid resuelva la variación comprable y su SKU. Llama a mountIdealhouse() con ese SKU, o limpia el host si la selección está incompleta. No concatenes etiquetas de opciones para fabricar un código.

Ecwid es una tienda de una sola página. Usa su ciclo de vida de página documentado (devoluciones de llamada de OnPageLoaded/cambio de página) en lugar de escuchar solo el DOMContentLoaded del navegador. La navegación por categorías/búsqueda, Atrás/Adelante del navegador, widgets incrustados y popups de productos deben eliminar los hosts de producto obsoletos y montar un nuevo contenedor después de renderizar.

Importar productos#

Exporta los campos de producto y variación SKU de Ecwid y mápelos a ideal.house sku. Usa Carga de productos, incluyendo importar productos, estado del trabajo, listar productos, actualizar productos, eliminar producto y errores y reintentos.

Cualquier exportación, webhook, instalación de OAuth o sincronización recurrente de Ecwid REST API es propiedad del cliente y debe implementarse en el servidor con la autorización Ecwid correspondiente.

Verificar y eliminar#

Prueba la instalación de la aplicación, la inicialización de la API, las transiciones de producto/categoría/búsqueda, cada variación, SKUs faltantes y desconocidos, Atrás/Adelante del navegador, un widget de Ecwid incrustado en otro sitio, diseño móvil, consentimiento y clientes logueados/deslogueados. Confirma una sola solicitud del SDK en el documento que contiene el host y la igualdad exacta del SKU.

Para eliminar, desacopla el archivo JavaScript autoalojado de la aplicación personalizada o desinstala la aplicación, elimina los hosts/listeners inyectados, y verifica que las URL del SDK y todos los nodos data-idealhouse-* desaparezcan después de la navegación de la tienda y una actualización forzada.