Ideal House
Saltar al contenido

integración para desarrolladores de Shopify#

Agregue el botón ideal.house a un tema Shopify y asócielo a la variante SKU seleccionada.

<!-- DASHBOARD_READINESS -->

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

1. Confirmar requisitos previos#

  • Puede editar el código del tema en vivo o una copia segura del tema.
  • Al menos un producto de prueba está importado y activo en el Catálogo.
  • La variante SKU seleccionada es el mismo productCode persistente utilizado por el Catálogo para esta tienda.

2. Crear el fragmento del botón#

snippets/idealhouse-view-button.liquid#

liquid
{%- comment -%}
  Renders an ideal.house authored visualizer button.

  Accepts:
  - product_code: {String} Variant SKU used by the ideal.house Catalog mapping.
  - placement: {String} "card", "pdp-desktop", or "pdp-mobile".
{%- endcomment -%}

{%- liquid
  assign button_code = product_code | strip
  assign button_placement = placement | default: 'card'
-%}

<button
  type="button"
  class="idealhouse-view-button idealhouse-view-button--{{ button_placement | escape }}"
  data-idealhouse-authored-button
  data-active="false"
  {% if button_code != blank %}
    data-product-code="{{ button_code | escape }}"
  {% else %}
    disabled
  {% endif %}
  style="visibility: hidden;"
>
  <span>View in my room</span>
</button>

Mantenga el botón oculto hasta que el SDK confirme la elegibilidad del producto.

3. Renderizar el botón en las superficies del tema#

Tarjetas de colección y búsqueda#

liquid
{%- render 'idealhouse-view-button',
  product_code: card_product.selected_or_first_available_variant.sku,
  placement: 'card'
-%}

Los archivos comunes incluyen snippets/card-product.liquid, snippets/product-card.liquid o snippets/product-grid-item.liquid. Ajuste card_product a la variable product utilizada por el tema.

Página de detalle del producto#

liquid
{%- render 'idealhouse-view-button',
  product_code: product.selected_or_first_available_variant.sku,
  placement: 'pdp-desktop'
-%}

{%- render 'idealhouse-view-button',
  product_code: product.selected_or_first_available_variant.sku,
  placement: 'pdp-mobile'
-%}

Los archivos comunes incluyen sections/main-product.liquid o snippets/product.liquid. Coloque representaciones separadas para escritorio y móvil únicamente cuando el tema tenga diseños diferenciados.

4. Cargar el SDK y sincronizar variantes#

assets/idealhouse-room-visualizer.js#

js
(function () {
  'use strict';

  var buttonSelector = '[data-idealhouse-authored-button]';
  var sdkRequested = false;
  var buttonObserver = null;

  function resetButton(button) {
    button.dataset.active = 'false';
    button.style.visibility = 'hidden';
    delete button.dataset.rvProductCode;
    delete button.dataset.rvProductType;
    delete button.dataset.rvProductId;
    delete button.dataset.rvProductIds;
  }

  function syncButton(button, productCode) {
    if (!button) return false;
    var code = typeof productCode === 'string' ? productCode.trim() : '';
    resetButton(button);
    delete button.dataset.productCode;

    if (!code) {
      button.disabled = true;
      return false;
    }

    button.disabled = false;
    button.dataset.productCode = code;
    return true;
  }

  function syncButtons(container, productCode) {
    (container || document).querySelectorAll(buttonSelector).forEach(function (button) {
      syncButton(button, productCode);
    });
  }

  function loadSdk() {
    if (sdkRequested || !document.querySelector(buttonSelector)) return false;
    sdkRequested = true;
    if (buttonObserver) buttonObserver.disconnect();

    var 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>';
    script.dataset.authoredButtonSelector = buttonSelector;
    document.head.appendChild(script);
    return true;
  }

  function startSdkLoader() {
    if (loadSdk() || typeof MutationObserver === 'undefined') return;
    buttonObserver = new MutationObserver(loadSdk);
    buttonObserver.observe(document.documentElement, { childList: true, subtree: true });
  }

  // Dispatch this event from your theme's variant-change callback.
  document.addEventListener('idealhouse:variant-change', function (event) {
    var detail = event.detail || {};
    syncButtons(detail.container || document, event.detail && event.detail.sku);
  });

  window.IdealhouseShopify = {
    syncButton: syncButton,
    syncButtons: syncButtons
  };

  if (document.readyState === 'loading') {
    document.addEventListener('DOMContentLoaded', startSdkLoader);
  } else {
    startSdkLoader();
  }
}());

Shopify no define un único evento universal de variante del tema. Conecte el pequeño adaptador a continuación al evento o la devolución de llamada expuesta por el tema activo.

Ejemplo de adaptador de eventos del tema#

Reemplace el evento de ejemplo con la API del tema activo. Algunos temas publican a través de window.subscribe; otros emiten un evento DOM o actualizan product-info.

js
// Example only: replace "variant:change" with your theme's event.
document.addEventListener('variant:change', function (event) {
  var variant = event.detail && event.detail.variant;
  var productContainer = event.target.closest('product-info') || document;

  document.dispatchEvent(new CustomEvent('idealhouse:variant-change', {
    detail: {
      container: productContainer,
      sku: variant && variant.sku
    }
  }));
});

5. Agregar estilos del tema#

assets/idealhouse-room-visualizer.css#

css
.idealhouse-view-button {
  align-items: center;
  justify-content: center;
  width: 100%;
  min-height: 44px;
  padding: 0.75rem 1rem;
  border: 1px solid currentColor;
  border-radius: 6px;
  background: transparent;
  color: inherit;
  cursor: pointer;
  font: inherit;
}

.idealhouse-view-button[data-active="true"] {
  display: inline-flex;
  visibility: visible;
}

.idealhouse-view-button:disabled {
  cursor: not-allowed;
  opacity: 0.5;
}

El tema puede sobrescribir estos estilos visuales.

6. Incluir activos en theme.liquid#

Incluya la hoja de estilos y el script del visualizador en layout/theme.liquid para aplicar los estilos y activar el cargador del SDK.

Incluir hoja de estilos (dentro de <head>)#

liquid
{{ 'idealhouse-room-visualizer.css' | asset_url | stylesheet_tag }}

Colóquela dentro de la etiqueta <head> de layout/theme.liquid para que los estilos se carguen de manera limpia.

Incluir script (antes de </body>)#

liquid
<script src="{{ 'idealhouse-room-visualizer.js' | asset_url }}" defer="defer"></script>

Utilice defer y colóquelo justo antes de la etiqueta de cierre </body> en layout/theme.liquid para evitar bloquear el renderizado de la página.

El botón 'View in my room' permanece oculto hasta que este script de carga esté incluido en theme.liquid.

7. Verificar en la tienda en vivo#

  1. El panel Network muestra sdk.js cargado con HTTP 200.
  2. El atributo data-product-code del botón creado por el desarrollador coincide exactamente con el productCode del Catálogo.
  3. Los productos elegibles muestran un botón; los productos no elegibles lo mantienen oculto.
  4. Cambiar de variante actualiza data-product-code y revalida el botón.
  5. Las ubicaciones en colecciones/búsquedas, PDP escritorio y PDP móvil funcionan donde estén presentes.
  6. Al hacer clic en el botón, se abre el Viewer de ideal.house con el producto seleccionado.