Integración de WordPress#

Agregue el Room Visualizer de ideal.house a un sitio de WordPress cargando un único script público para navegador y renderizando un contenedor cuyo código de producto coincida con un SKU de catálogo importado.

Estado de verificación: Documentación revisada el 7 de septiembre de 2026. Esta guía no ha sido certificada de extremo a extremo contra un tema de WordPress de cliente. Valídela en una copia de staging de su tema exacto y versiones del constructor de páginas antes de publicar.

Antes de cargar la SDK: Abra Panel de control → Configuración, agregue su origen de tienda a Allowed Origins (CORS) y haga clic en Guardar. Incluya el nombre de host publicado y cualquier origen de vista previa o staging que utilice; separe múltiples orígenes con comas. Consulte pasos de configuración.

Alcance y requisitos previos#

Esta guía cubre sitios de contenido de WordPress, temas clásicos, temas de bloques y constructores de páginas que permiten agregar HTML. Si el sitio utiliza datos de productos de WooCommerce, use la guía de WooCommerce para la selección de variantes.

Preparar:

acceso de administrador y, para el método duradero, un tema hijo o un pequeño plugin específico del sitio;
el Shop ID y el Publishable Key del Panel de control de ideal.house;
un producto ya importado en ideal.house con un sku conocido;
una página de staging donde puedan desactivarse la caché y la minificación mientras se prueba.

El Publishable Key está destinado a marcado del navegador. Nunca coloque una clave Client Secret o AI API en WordPress HTML.

Confirmar el contrato de la SDK#

La instalación más pequeña compatible consta exactamente de un script SDK y un contenedor de botón generado:

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 debe ser igual al sku del catálogo, incluyendo mayúsculas, minúsculas y puntuación. La SDK es propietaria del contenido del contenedor. WordPress no proporciona un plugin de ideal.house en esta guía.

Instalar el script en todo el sitio#

WordPress recomienda cargar scripts de front-end a través de wp_enqueue_script(). Agregue lo siguiente a un archivo functions.php de tema hijo o a un plugin específico del sitio. El filtro agrega los dos atributos de datos requeridos a la etiqueta que WordPress produce.

php

add_action('wp_enqueue_scripts', function () {
    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);

Reemplace ambos marcadores de posición. Las versiones de WordPress anteriores a 6.3 no aceptan la forma de matriz del último argumento de wp_enqueue_script(); pase true en su lugar y use el filtro script_loader_tag para agregar async también.

No instale la SDK nuevamente en un bloque de código o en un gestor de etiquetas. En DevTools, document.querySelectorAll('script[src="https://sdk.ideal.house/sdk.js"]').length debe devolver 1.

Colocar un botón#

En el editor de bloques, agregue un bloque Personalizado de HTML donde deba aparecer el botón:

html

<div data-idealhouse-button-container data-product-code="CHAIR-OAK-01"></div>

Para tarjetas repetidas, renderice el mismo marcado desde la plantilla del tema y escapelo como un atributo de HTML:

php

<div
  data-idealhouse-button-container
  data-product-code="<?php echo esc_attr($idealhouse_product_code); ?>"
></div>

Su tema o plugin debe proporcionar $idealhouse_product_code. No use un ID de publicación, slug o título, a menos que ese valor exacto también sea el sku de ideal.house importado.

Mapeo de producto y variante#

Cree una tabla de mapeo explícita antes del lanzamiento:

valor de WordPress	valor de ideal.house	Regla
campo personalizado como `idealhouse_sku`	`sku`	coincidencia exacta de cadena
una página sin variantes	un producto importado	un contenedor
elemento de colección del constructor de páginas	campo SKU a nivel de elemento	nunca reutilice un código para toda la colección

Si la página cambia entre variantes, el adaptador del cliente debe establecer el nuevo data-product-code. Limpie el contenedor anterior antes de insertar el nuevo para que el estado del visor obsoleto no pueda reutilizarse:

function renderIdealhouseButton(host, sku) {
  host.replaceChildren();
  if (!sku) return;

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

Este es código del adaptador del cliente. No llama a un método de ideal.house no documentado ni inventa un evento de WordPress; llámelo desde la devolución de llamada documentada suministrada por su tema o constructor de páginas.

Navegación dinámica y cachés#

Para filtros AJAX, desplazamiento infinito, tarjetas de producto modales o transiciones del constructor de páginas, inserte un contenedor nuevo después de que el nuevo nodo de producto esté en el DOM. No clone un contenedor que la SDK ya haya poblado. Si su herramienta no expone una devolución de llamada de render estable, agregue el contenedor en su plantilla de elemento para que cada render cree un marcado limpio.

Después de una edición del tema, purgue las cachés de WordPress, CDN y plugins de optimización. Excluya https://sdk.ideal.house/sdk.js de reescrituras de demora/deferencia si un plugin de rendimiento elimina sus atributos de datos o lo pospone hasta después de la interacción.

Importar datos de catálogo#

El contenido de WordPress no se sincroniza automáticamente. Exporte el campo personalizado elegido como sku e importe los registros coincidentes a través de Carga de producto. Continúe con importar productos, estado del trabajo, listar productos, actualizar productos, eliminar producto y errores y reintentos.

Verificar antes de publicar#

Abra staging en una ventana privada del navegador, no en la vista previa del editor de WordPress.
Confirme que la solicitud de SDK se retorna exitosamente y solo una vez.
Inspeccione el contenedor y compare data-product-code carácter por carácter con el sku importado.
Confirme que un SKU importado produce un control de visualizador útil y que un SKU desconocido no expone un control defectuoso.
Pruebe la navegación del constructor de páginas, filtros, Retroceder/Avanzar del navegador, diseño móvil y configuraciones de consentimiento.
Seleccione cada variante compatible y confirme que el contenedor se recrea con su SKU.
Verifique la consola del navegador y pruebe nuevamente con la caché/minificación habilitada.

Eliminar la integración#

Elimine la función de registro y carga del script y el filtro script_loader_tag, luego elimine cada bloque o fragmento de plantilla data-idealhouse-button-container. Purgue todas las cachés y verifique que la URL de SDK esté ausente en el código fuente de la página y en el panel de Red.