Ideal House
Saltar al contenido

Integración de WooCommerce#

Añade botones de Room Visualizer a las páginas de producto de WooCommerce y mantén el código de producto ideal.house sincronizado con el SKU de la variación seleccionada.

Estado de verificación: Documentación y comportamiento público de WooCommerce revisados el 7 de septiembre de 2026. Esta implementación no ha sido certificada en una tienda de cliente. Las plantillas clásicas, los temas de bloques, las extensiones de variación y los complementos de vista rápida pueden generar DOM diferentes; prueba el conjunto exacto en un entorno de staging.

Antes de cargar el SDK: Abre Panel de control → Configuración, añade el origen de tu storefront a Allowed Origins (CORS) y haz clic en Save. Incluye el nombre de host publicado y cualquier origen de previsualización o staging que utilices; separa múltiples orígenes con comas. Consulta los pasos de configuración.

Alcance y requisitos previos#

Esta guía apunta a WooCommerce en WordPress. Utiliza un pequeño plugin específico del sitio o un tema hijo, el cargador de activos estándar de WordPress y los hooks de producto de WooCommerce. No es un plugin de WordPress instalable de ideal.house.

Prepara acceso de administrador y de archivos, Shop ID, Publishable Key y registros importados de ideal.house para cada SKU visualizable. Asigna a cada producto simple y a cada variación compatible un SKU no vacío y único en WooCommerce.

Marcado mínimo del SDK#

Este es el contrato público del SDK que utiliza la integración:

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>

El código del contenedor generado debe coincidir con el sku del catálogo importado. No coloques identificadores de base de datos de WooCommerce en data-product-code a menos que hayas utilizado deliberadamente esos identificadores como SKUs del catálogo.

Carga el SDK una sola vez#

Añade este código a un functions.php de tema hijo o a un plugin específico del sitio. Reemplaza los marcadores de posición.

php
add_action('wp_enqueue_scripts', function () {
    if (!is_product() && !is_shop() && !is_product_category()) {
        return;
    }

    wp_enqueue_script(
        'idealhouse-room-visualizer',
        'https://sdk.ideal.house/sdk.js',
        array(),
        null,
        array('strategy' => 'async', 'in_footer' => true)
    );
});

add_filter('script_loader_tag', function ($tag, $handle) {
    if ($handle !== 'idealhouse-room-visualizer') return $tag;

    return str_replace(
        '<script ',
        '<script data-shop-id="<SHOP_ID>" data-publishable-key="<PUBLISHABLE_KEY>" ',
        $tag
    );
}, 10, 2);

Si admites versiones de WooCommerce en WordPress anteriores a 6.3, pasa true como último argumento de enqueue y añade async en el filtro.

Renderizar el host en la página de producto#

El siguiente hook coloca un host después del formulario add-to-cart. Los productos simples reciben su SKU inmediatamente. Los productos variables comienzan vacíos; el adaptador del navegador los rellena cuando se selecciona una variación completa.

php
add_action('woocommerce_after_add_to_cart_form', function () {
    global $product;
    if (!$product instanceof WC_Product) return;

    $sku = $product->is_type('variable') ? '' : $product->get_sku();
    printf(
        '<div class="idealhouse-host" data-initial-sku="%1$s">%2$s</div>',
        esc_attr($sku),
        $sku ? '<div data-idealhouse-button-container data-product-code="' . esc_attr($sku) . '"></div>' : ''
    );
});

Confirma que el hook existe en tu plantilla de producto. Un tema que reemplace la plantilla de WooCommerce o el bloque Product Collection puede requerir una integración de bloques u otro hook de WooCommerce documentado.

Sincronizar una variación seleccionada#

El formulario de variación integrado de WooCommerce desencadena eventos del ciclo de vida jQuery de variación. Añade un archivo local, por ejemplo assets/js/idealhouse-woocommerce.js, regístralo para su carga con dependencias jquery y wc-add-to-cart-variation y utiliza:

js
(function ($) {
  function render(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);
  }

  $('.variations_form').each(function () {
    const form = $(this);
    const host = this.closest('.product')?.querySelector('.idealhouse-host');
    if (!host) return;

    form.on('found_variation', function (_event, variation) {
      render(host, variation && variation.sku);
    });
    form.on('reset_data hide_variation', function () {
      render(host, '');
    });
  });

  document.querySelectorAll('.idealhouse-host[data-initial-sku]').forEach(function (host) {
    render(host, host.dataset.initialSku);
  });
})(jQuery);

Este archivo es un adaptador de WooCommerce de propiedad del cliente. Si un plugin de variación reemplaza el script de formulario estándar, utiliza la callback de selección documentada de ese plugin en lugar de suponer que estos eventos aún se disparan. No actualices solo el atributo de un contenedor ya procesado por el SDK; reemplázalo con un contenedor limpio.

Grids de producto, vista rápida y navegación AJAX#

Para las tarjetas de catálogo, utiliza un hook de producto-loop como woocommerce_after_shop_loop_item y renderiza el SKU del producto simple. Los productos variables en un grid suelen no tener una variación resuelta; enlaza a la página del producto o construye un adaptador explicito de selector de variaciones.

Los plugins de vista rápida y los bloques de WooCommerce pueden inyectar productos después de la carga inicial de la página. Coloca el host en la plantilla que rendericen y ejecuta tu puente render() desde la callback de finalización documentada de esa herramienta. Si no hay una callback estable, un MutationObserver con ámbito puede detectar nuevos nodos .idealhouse-host, pero el cliente es dueño de su rendimiento y ciclo de vida.

Mapea WC_Product::get_sku() y cada WC_Product_Variation::get_sku() a sku de ideal.house. Los productos padre e hijo no deben compartir un código si representan activos visuales diferentes.

WooCommerce no empuja automáticamente los cambios de catálogo a ideal.house. Utiliza Carga de productos y sus guías de Importación, Estado del trabajo, Listado, Actualizaciones, Eliminación y Gestión de reintentos. Cualquier exportación programada o puente de webhook es implementación del cliente.

Verificar antes del lanzamiento#

  1. Prueba un producto simple, un producto variable, un SKU faltante y un SKU ausente de ideal.house.
  2. Confirma que el SDK se solicita una sola vez y que su etiqueta de script conserva ambos atributos de credencial.
  3. Selecciona cada variación y verifica que data-product-code sea igual al SKU de variación.
  4. Reinicia el formulario de variación; el contenedor antiguo debería desaparecer.
  5. Prueba un grid de producto, vista rápida, filtros AJAX, fragmentos de carrito, add-to-cart fijo en móvil y Back/Forward del navegador cuando corresponda.
  6. Prueba mientras estás desconectado, con controles de consentimiento y caching de producción habilitado.
  7. Comprueba que ningún Client Secret aparezca en HTML, JavaScript, logs o source maps.

Eliminar la integración#

Elimina los hooks/filtros PHP y el enqueue del adaptador de variación local. Elimina los hosts de las plantillas o bloques sobrescritos, limpia los transients de WooCommerce y los caches de página/CDN, luego confirma que no quede ninguna petición de SDK ni elemento data-idealhouse-*.

Referencias oficiales de la plataforma#