Integración de Shoplazza#
Agrega Room Visualizer a Shoplazza con una Theme App Extension o un tema personalizado de Liquid y renderiza el SKU de variante seleccionada como el Product Code de ideal.house.
Estado de verificación: La documentación de tema, extensión, producto y variante de Shoplazza fue revisada el 7 de septiembre de 2026. No había una app de partner o tienda de prueba de merchant disponible, por lo que la instalación y el cambio de variantes deben validarse en una tienda de desarrollo.
Antes de cargar el SDK: Abre Panel de control → Configuración, agrega tu origen de storefront a Allowed Origins (CORS) y haz clic en Save. Incluye el nombre de host publicado y cualquier origen de vista previa o staging que utilices; separa múltiples orígenes con comas. Consulta Pasos de configuración.
Requisitos previos#
Prepara una tienda de desarrollo/merchant de Shoplazza, acceso al código de extensión de tema o app, Shop ID, Publishable Key, y registros importados para SKUs de variantes soportados. Duplica el tema del merchant antes de personalizar.
Una Theme App Extension es el camino reutilizable y mantenible. Un App Block inyecta UI visible y debe ser agregado por el merchant a una sección de producto compatible; un App Embed puede cargar comportamiento global.
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>
Shoplazza documenta variant.sku; usa esa cadena exacta como ideal.house sku.
Agregar un App Block#
Crea un App Block de extensión de tema para la sección de producto. Los bloques de Liquid de Shoplazza en un contexto de producto pueden acceder a product. Comienza con un host vacío, luego usa el estado del formulario de producto del tema activo para suministrar la variante seleccionada:
<div class="idealhouse-host"></div>
{% schema %}
{
"name": { "en-US": "Room Visualizer", "zh-CN": "房间可视化" },
"target": "section",
"javascript": ["idealhouse.js"],
"settings": []
}
{% endschema %}
Para un producto de una sola variante, el bloque de JavaScript puede leer la única entrada documentada en product.variants de los datos serializados de forma segura por el tema. Para múltiples variantes, mantén el host vacío hasta que el formulario de producto existente del tema resuelva una selección. Esto evita depender de una propiedad de variante seleccionada de Liquid no documentada.
Cargar el SDK#
En idealhouse.js, carga el SDK una sola vez. Para una app reutilizable, proporciona Shop ID y Publishable Key a través de la configuración pública del bloque/embed saneada en lugar de codificar un merchant en duro:
if (!document.querySelector('script[src="https://sdk.ideal.house/sdk.js"]')) {
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);
}
Nunca expongas el secreto de la app ni el ideal.house Client Secret.
Mantener sincronizada la variante seleccionada#
Conecta el callback del formulario de producto documentado del tema a este adaptador:
function renderIdealhouseVariant(host, variant) {
host.replaceChildren();
const code = String(variant && variant.sku || '').trim();
if (!code) return;
const container = document.createElement('div');
container.dataset.idealhouseButtonContainer = '';
container.dataset.productCode = code;
host.append(container);
}
El objeto de variante de Shoplazza documenta sku, pero los temas pueden implementar la selección de manera diferente. La conexión del callback es trabajo del adaptador del cliente. Reconstruye el contenedor después de una nueva selección; no modifiques únicamente el marcado poblado por el SDK.
Para tarjetas de colección, vista rápida, filtros de búsqueda y secciones renderizadas por el cliente, agrega un host a nivel de elemento y ejecuta el puente después del callback de renderizado documentado del tema. Si no se conoce una variante final en una tarjeta, omite el botón o, como alternativa, proporciona un enlace a la página del producto.
Importar productos#
Exporta cada variant.sku soportado e impórtalo como ideal.house sku a través de Carga de productos. Consulta Importar productos, Estado del trabajo, Listar productos, Actualizar productos, Eliminar producto y Errores y reintentos.
Las exportaciones de API de Admin, webhooks, sincronización programada, OAuth y distribución de extensiones son implementación del cliente.
Verificar y eliminar#
Prueba colocación del App Block, habilitación del Embed, un producto de una sola variante, todas las elecciones multi-variante, SKUs en blanco/duplicados/desconocidos, tarjetas de colección, vista rápida, filtros, historial del navegador, móvil, localización/moneda, consentimiento y modos de preview/live del tema. Confirma una solicitud de SDK y una asignación exacta de variante SKU.
Para eliminar, deshabilita y desinstala la Theme App Extension o elimina el código Liquid/JavaScript personalizado, publica el tema limpio, limpia las cachés del storefront y verifica que el SDK y todos los nodos de data-idealhouse-* estén ausentes.