Integrazione Adobe Commerce / Magento Open Source#

Installa Room Visualizer tramite un modulo Magento o un tema personalizzato e associa lo SKU del prodotto semplice visualizzato al catalogo ideal.house.

Stato della verifica: documentazione dell’interfaccia Adobe Commerce esaminata il 7 settembre 2026. Non era disponibile un’installazione di un commerciante. I temi Luma/Blank, Hyvä e PWA Studio usano configurazioni JavaScript diverse; l’esempio concreto seguente riguarda il negozio standard con RequireJS.

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 origini di anteprima o preproduzione utilizzate; separa più origini con virgole. Consulta i passaggi di configurazione.

Prerequisiti e ambito#

Prepara un’istanza di sviluppo, un modulo personalizzato o tema figlio, accesso alla distribuzione, Shop ID, Publishable Key e SKUs di prova importati. Non modificare mai file in vendor/ o in un tema di base. Hyvä e PWA Studio richiedono adattatori Alpine/React propri: non copiare ciecamente codice RequireJS.

Contratto minimo di SDK#

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>

Product Code è lo sku esatto importato, non l’ID numerico dell’entità Magento.

Aggiungere un blocco nella pagina prodotto#

Crea un piccolo modulo o aggiornamento della disposizione del tema per catalog_product_view. Collega un blocco a un modello .phtml vicino alle azioni del prodotto. Il modello può visualizzare in sicurezza lo SKU iniziale del prodotto:

php

<?php
/** @var \Magento\Catalog\Block\Product\View $block */
$product = $block->getProduct();
$sku = $product ? trim((string) $product->getSku()) : '';
?>

<div class="idealhouse-host">
  <?php if ($sku !== ''): ?>
    <div
      data-idealhouse-button-container
      data-product-code="<?= $block->escapeHtmlAttr($sku) ?>"
    ></div>
  <?php endif; ?>
</div>

Per un prodotto configurabile, lo SKU iniziale della pagina è solitamente lo SKU del prodotto padre. Se le risorse ideal.house appartengono ai prodotti semplici figli, lascia inizialmente vuoto il contenitore e popolalo solo dopo aver determinato il prodotto semplice selezionato.

Caricare SDK una sola volta#

Aggiungi un inizializzatore RequireJS locale nel modulo o nel tema. L’inizializzatore crea lo script esterno e applica tutti gli attributi di dati obbligatori prima di inserirlo:

define([], function () {
  'use strict';

  return function () {
    if (document.querySelector('script[src="https://sdk.ideal.house/sdk.js"]')) return;

    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>';
    document.head.appendChild(script);
  };
});

Inizializzalo in modo dichiarativo dal modello, seguendo il meccanismo text/x-magento-init consigliato da Adobe:

html

<script type="text/x-magento-init">
{
  "*": {
    "Vendor_Module/js/idealhouse-loader": {}
  }
}
</script>

Questo produce lo stesso elemento SDK del contratto minimo senza inserire credenziali in un URL RequireJS. Nel codice del negozio usa soltanto Publishable Key.

SKU configurabile selezionato#

Il componente standard dei prodotti configurabili espone lo stato della selezione tramite un componente Magento, ma le personalizzazioni del tema ne modificano la struttura. Implementa un mixin RequireJS o un listener nel modulo, nel punto in cui il tema determina l’ID di un prodotto semplice; associalo allo SKU tramite JSON fornito dal server e sostituisci il contenitore:

function renderIdealhouseSku(host, sku) {
  host.replaceChildren();
  if (!sku || !sku.trim()) return;

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

Il mixin e i dati di associazione tra ID e SKU fanno parte dell’adattatore del cliente. Non dedurre lo SKU figlio dalle etichette delle opzioni e non documentare eventi o metodi ideal.house estranei al contratto pubblico di SDK.

Contenuti dinamici e cache#

Ricrea il contenitore quando cambi di campione, consigli caricati tramite AJAX, vista rapida o contenuti specifici del cliente sostituiscono l’elemento che lo ospita. L’evento contentUpdated di Magento inizializza componenti Magento nei contenuti inseriti; da solo non fornisce lo SKU selezionato, quindi l’adattatore deve comunque determinare e visualizzare il codice corretto.

Dopo modifiche al codice, esegui i passaggi di distribuzione adatti all’ambiente, svuota le cache di disposizione, pagina completa e blocchi, poi ridistribuisci i contenuti statici. Prova con raggruppamento e minificazione di produzione e Varnish/CDN attivi.

Importare i dati dei prodotti#

Associa gli SKUs dei prodotti semplici e figli allo sku di ideal.house. Usa Caricamento dei prodotti, comprese importazione, stato del processo, elenco, aggiornamenti, eliminazione e indicazioni sui nuovi tentativi. Esportazioni Magento, chiamate Admin API, attività cron e notifiche web richiedono adattatori del cliente.

Verificare e rimuovere#

Prova prodotti semplici, configurabili, senza SKU, con figli disabilitati e con SKU sconosciuti. Verifica una sola richiesta SDK, associazioni SKU esatte dopo ogni cambio di campione o opzione, comportamento corretto di vista rapida e consigli, disposizione mobile, risposte dalla cache, pagine dei gruppi clienti e controlli del consenso. Verifica che nessuna credenziale segreta compaia nel sorgente o nelle risorse statiche.

Per rimuovere, disabilita o disinstalla il modulo personalizzato oppure elimina i file di disposizione, modello e RequireJS del tema figlio; ridistribuisci i contenuti statici, svuota le cache e verifica l’assenza dell’URL di SDK e dei contenitori.