Ideal House
Passa al contenuto

Integrazione WooCommerce#

Aggiungi pulsanti Room Visualizer alle pagine prodotto WooCommerce e mantieni il codice prodotto ideal.house sincronizzato con lo SKU della variante selezionata.

Stato della verifica: documentazione e comportamento pubblico di WooCommerce esaminati il 7 settembre 2026. Questa implementazione non è stata certificata nel negozio di un cliente. Modelli classici, temi a blocchi, estensioni per varianti e plugin di vista rapida possono generare DOM diversi; prova la configurazione esatta in preproduzione.

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.

Ambito e prerequisiti#

Questa guida riguarda WooCommerce su WordPress. Usa un piccolo plugin specifico del sito o un tema figlio, il caricatore standard di risorse WordPress e i punti di aggancio dei prodotti WooCommerce. Non è un plugin ideal.house per WordPress installabile.

Prepara accesso amministratore e ai file, Shop ID, Publishable Key e record importati in ideal.house per ogni SKU visualizzabile. Assegna a ogni prodotto semplice e a ogni variante supportata uno SKU non vuoto e univoco in WooCommerce.

Codice minimo di SDK#

Questo è il contratto pubblico di SDK usato dall’integrazione:

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>

Il codice del contenitore generato deve corrispondere allo sku importato nel catalogo. Non inserire gli ID del database WooCommerce in data-product-code, a meno che tu li abbia usati deliberatamente come SKUs del catalogo.

Caricare SDK una sola volta#

Aggiungi questo codice a functions.php di un tema figlio o a un plugin specifico del sito. Sostituisci i segnaposto.

php
add_action('wp_enqueue_scripts', function () {
    if (!is_product() && !is_shop() && !is_product_category()) {
        return;
    }

    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);

Se supporti versioni di WooCommerce su WordPress precedente alla 6.3, passa true come ultimo argomento di accodamento e aggiungi async nel filtro.

Visualizzare il contenitore della pagina prodotto#

Il seguente punto di aggancio inserisce un contenitore dopo il modulo Aggiungi al carrello. I prodotti semplici ricevono subito il proprio SKU. Quelli variabili iniziano con un contenitore vuoto; l’adattatore del browser lo popola quando viene selezionata una variante completa.

php
add_action('woocommerce_after_add_to_cart_form', function () {
    global $product;
    if (!$product instanceof WC_Product) return;

    $sku = $product->is_type('variable') ? '' : $product->get_sku();
    printf(
        '<div class="idealhouse-host" data-initial-sku="%1$s">%2$s</div>',
        esc_attr($sku),
        $sku ? '<div data-idealhouse-button-container data-product-code="' . esc_attr($sku) . '"></div>' : ''
    );
});

Verifica che il punto di aggancio esista nel modello del prodotto. Un tema che sostituisce il modello WooCommerce o il blocco Raccolta prodotti può richiedere un’integrazione a blocchi o un altro punto di aggancio WooCommerce documentato.

Sincronizzare una variante selezionata#

Il modulo delle varianti incluso in WooCommerce genera eventi jQuery del ciclo di vita delle varianti. Aggiungi un file locale, ad esempio assets/js/idealhouse-woocommerce.js, accodalo con le dipendenze jquery e wc-add-to-cart-variation e usa:

js
(function ($) {
  function render(host, sku) {
    host.replaceChildren();
    const code = typeof sku === 'string' ? sku.trim() : '';
    if (!code) return;

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

  $('.variations_form').each(function () {
    const form = $(this);
    const host = this.closest('.product')?.querySelector('.idealhouse-host');
    if (!host) return;

    form.on('found_variation', function (_event, variation) {
      render(host, variation && variation.sku);
    });
    form.on('reset_data hide_variation', function () {
      render(host, '');
    });
  });

  document.querySelectorAll('.idealhouse-host[data-initial-sku]').forEach(function (host) {
    render(host, host.dataset.initialSku);
  });
})(jQuery);

Questo file è un adattatore WooCommerce gestito dal cliente. Se un plugin per varianti sostituisce lo script standard del modulo, usa la funzione di richiamo documentata di quel plugin per la selezione, senza presumere che questi eventi vengano ancora generati. Non aggiornare soltanto l’attributo di un contenitore già elaborato da SDK; sostituiscilo con un contenitore pulito.

Griglie di prodotti, vista rapida e navigazione AJAX#

Per le schede del catalogo, usa un punto di aggancio del ciclo prodotti come woocommerce_after_shop_loop_item e visualizza lo SKU del prodotto semplice. I prodotti variabili in una griglia di solito non hanno una variante già determinata; collega la pagina prodotto oppure crea un adattatore esplicito per la selezione della variante.

I plugin di vista rapida e i blocchi WooCommerce possono inserire prodotti dopo il caricamento iniziale della pagina. Inserisci il contenitore nel modello che generano ed esegui la funzione di collegamento render() dalla funzione di richiamo documentata al completamento di quello strumento. Se manca una funzione di richiamo stabile, un MutationObserver con ambito limitato può rilevare nuovi nodi .idealhouse-host, ma prestazioni e ciclo di vita restano responsabilità del cliente.

Associa WC_Product::get_sku() e ogni WC_Product_Variation::get_sku() allo sku di ideal.house. Prodotti padre e figli non devono condividere un codice se rappresentano risorse visive diverse.

WooCommerce non invia automaticamente a ideal.house le modifiche al catalogo. Usa Caricamento dei prodotti e le guide per importazione, stato del processo, elenco, aggiornamenti, eliminazione e gestione dei nuovi tentativi. Eventuali esportazioni pianificate o collegamenti tramite notifiche web devono essere implementati dal cliente.

Verificare prima del lancio#

  1. Prova un prodotto semplice, un prodotto variabile, un prodotto senza SKU e uno SKU assente da ideal.house.
  2. Verifica che SDK venga richiesto una sola volta e che il suo tag script mantenga entrambi gli attributi delle credenziali.
  3. Seleziona ogni variante e verifica che data-product-code corrisponda al suo SKU.
  4. Reimposta il modulo delle varianti; il vecchio contenitore deve scomparire.
  5. Prova, dove presenti, griglia prodotti, vista rapida, filtri AJAX, frammenti del carrello, pulsante fisso Aggiungi al carrello su dispositivi mobili e pulsanti Indietro/Avanti del browser.
  6. Prova senza effettuare l’accesso, con controlli del consenso e cache di produzione attivi.
  7. Verifica che Client Secret non compaia in HTML, JavaScript, registri o mappe dei sorgenti.

Rimuovere l’integrazione#

Rimuovi i punti di aggancio e il filtro PHP, oltre all’accodamento dell’adattatore locale delle varianti. Elimina i contenitori dai modelli o blocchi sovrascritti, cancella i dati temporanei WooCommerce e le cache delle pagine e della CDN, quindi verifica che non rimangano richieste SDK o elementi data-idealhouse-*.

Riferimenti ufficiali della piattaforma#