Ideal House
Passa al contenuto

Integrazione Shopify per sviluppatori#

Aggiungi il pulsante ideal.house a un tema Shopify e associalo allo SKU della variante selezionata.

<!-- DASHBOARD_READINESS -->

Prima di caricare SDK: apri Pannello di controllo → Impostazioni, aggiungi l'origine del negozio a Allowed Origins (CORS) e fai clic su Salva. Includi il nome host pubblicato e le eventuali origini di anteprima o di prova che usi; separa più origini con virgole. Consulta i passaggi di configurazione.

1. Conferma i prerequisiti#

  • Puoi modificare il codice del tema pubblicato oppure una copia sicura del tema.
  • Almeno un prodotto di prova è importato e attivo nel catalogo.
  • Lo SKU della variante selezionata è lo stesso productCode memorizzato in modo persistente e usato dal catalogo per questo negozio.

2. Crea il frammento del pulsante#

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>

Mantieni nascosto il pulsante finché SDK non conferma l'idoneità del prodotto.

3. Visualizza il pulsante nei punti previsti dal tema#

Schede delle collezioni e dei risultati di ricerca#

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

I file più comuni includono snippets/card-product.liquid, snippets/product-card.liquid o snippets/product-grid-item.liquid. Adatta card_product alla variabile prodotto usata dal tema.

Pagina di dettaglio del prodotto#

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'
-%}

I file più comuni includono sections/main-product.liquid o snippets/product.liquid. Inserisci visualizzazioni separate per computer e dispositivi mobili soltanto quando il tema prevede disposizioni separate.

4. Carica SDK e sincronizza le varianti#

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 non definisce un evento universale per le varianti dei temi. Collega il piccolo adattatore seguente all'evento o alla funzione di richiamo esposta dal tema attivo.

Esempio di adattatore per gli eventi del tema#

Sostituisci l'evento di esempio con API del tema attivo. Alcuni temi pubblicano tramite window.subscribe; altri inviano un evento DOM oppure aggiornano 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. Aggiungi gli stili 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;
}

Il tema può sovrascrivere questi stili visivi.

6. Includi le risorse in theme.liquid#

Includi il foglio di stile e lo script del visualizzatore in layout/theme.liquid per applicare gli stili e attivare il caricatore SDK.

Includi il foglio di stile (all'interno di <head>)#

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

Inseriscilo nel tag <head> di layout/theme.liquid affinché gli stili vengano caricati correttamente.

Includi lo script (prima di </body>)#

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

Usa defer e inseriscilo immediatamente prima del tag di chiusura </body> in layout/theme.liquid per evitare di bloccare la visualizzazione della pagina.

Il pulsante 'Visualizza nella mia stanza' rimane nascosto finché questo script di caricamento non viene incluso in theme.liquid.

7. Verifica nel negozio pubblicato#

  1. Il pannello Rete mostra sdk.js caricato con HTTP 200.
  2. Il data-product-code del pulsante creato manualmente corrisponde esattamente al productCode del catalogo.
  3. I prodotti idonei mostrano un pulsante; quelli non idonei lo mantengono nascosto.
  4. Il cambio di variante aggiorna data-product-code e verifica nuovamente il pulsante.
  5. I posizionamenti in collezione/ricerca, nella pagina prodotto per computer e nella pagina prodotto per dispositivi mobili funzionano dove presenti.
  6. Facendo clic sul pulsante si apre Viewer di ideal.house con il prodotto selezionato.