Integrazione WordPress#

Aggiungi Room Visualizer di ideal.house a un sito WordPress caricando un solo script pubblico per il browser e visualizzando un contenitore il cui codice prodotto corrisponde a uno SKU importato nel catalogo.

Stato della verifica: documentazione esaminata il 7 settembre 2026. Questa guida non è stata certificata dall’inizio alla fine su un tema WordPress di un cliente. Prima di pubblicare, convalidala su una copia in preproduzione con le esatte versioni del tema e del generatore di pagine utilizzati.

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 siti di contenuti WordPress, temi classici, temi a blocchi e generatori di pagine che consentono di aggiungere HTML. Se il sito usa dati prodotto WooCommerce, segui la guida WooCommerce per la selezione delle varianti.

Prepara:

• accesso amministratore e, per il metodo duraturo, un tema figlio o un piccolo plugin specifico del sito;
• Shop ID e Publishable Key dal pannello di controllo ideal.house;
• un prodotto già importato in ideal.house con uno sku noto;
• una pagina in preproduzione dove disabilitare cache e minificazione durante le prove.

Publishable Key è destinata al codice del browser. Non inserire mai Client Secret o una chiave AI API nel codice HTML di WordPress.

Verificare il contratto di SDK#

L’installazione minima supportata comprende esattamente uno script SDK e un contenitore per il pulsante generato:

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

data-product-code deve corrispondere allo sku del catalogo, comprese maiuscole, minuscole e punteggiatura. SDK gestisce il contenuto del contenitore. Questa guida non fornisce un plugin ideal.house per WordPress.

Installare lo script su tutto il sito#

WordPress consiglia di caricare gli script dell’interfaccia tramite wp_enqueue_script(). Aggiungi quanto segue a functions.php di un tema figlio o a un plugin specifico del sito. Il filtro aggiunge i due attributi di dati obbligatori al tag prodotto da WordPress.

add_action('wp_enqueue_scripts', function () {
    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);

Sostituisci entrambi i segnaposto. Le versioni di WordPress precedenti alla 6.3 non accettano l’array come ultimo argomento di wp_enqueue_script(); passa invece true e usa il filtro script_loader_tag per aggiungere anche async.

Non installare nuovamente SDK in un blocco Codice o in un gestore di tag. Negli strumenti per sviluppatori, document.querySelectorAll('script[src="https://sdk.ideal.house/sdk.js"]').length deve restituire 1.

Posizionare un pulsante#

Nell’editor a blocchi, aggiungi un blocco HTML personalizzato nel punto in cui deve comparire il pulsante:

<div data-idealhouse-button-container data-product-code="CHAIR-OAK-01"></div>

Per le schede ripetute, genera lo stesso codice dal modello del tema e applica al codice prodotto l’escape appropriato per un attributo HTML:

<div
  data-idealhouse-button-container
  data-product-code="<?php echo esc_attr($idealhouse_product_code); ?>"
></div>

Il tema o il plugin deve fornire $idealhouse_product_code. Non usare ID, slug o titolo di un articolo, a meno che quel valore esatto sia anche lo sku importato in ideal.house.

Associazione di prodotti e varianti#

Crea una tabella di associazione esplicita prima della pubblicazione:

Se la pagina cambia variante, l’adattatore del cliente deve impostare il nuovo data-product-code. Svuota il vecchio contenitore prima di inserire quello nuovo per impedire il riutilizzo di uno stato obsoleto del visualizzatore:

function renderIdealhouseButton(host, sku) {
  host.replaceChildren();
  if (!sku) return;

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

Questo è codice dell’adattatore implementato dal cliente. Non richiama metodi ideal.house non documentati né inventa eventi WordPress; richiamalo dalla funzione di richiamo documentata del tema o del generatore di pagine.

Navigazione dinamica e cache#

Per filtri AJAX, scorrimento infinito, schede prodotto in finestre modali o transizioni del generatore di pagine, inserisci un nuovo contenitore dopo che il nodo del nuovo prodotto è entrato nel DOM. Non clonare un contenitore già popolato da SDK. Se lo strumento non espone una funzione di richiamo stabile dopo la visualizzazione, aggiungi il contenitore nel modello dell’elemento, in modo che ogni visualizzazione generi codice pulito.

Dopo una modifica al tema, svuota le cache di WordPress, CDN e plugin di ottimizzazione. Escludi https://sdk.ideal.house/sdk.js dalle riscritture che ne ritardano l’esecuzione se un plugin di prestazioni rimuove i suoi attributi di dati o ne rimanda il caricamento fino a dopo un’interazione.

Importare i dati del catalogo#

I contenuti WordPress non vengono sincronizzati automaticamente. Esporta il campo personalizzato scelto come sku e importa i record corrispondenti tramite Caricamento dei prodotti. Prosegui con importare prodotti, stato del processo, elencare prodotti, aggiornare prodotti, eliminare un prodotto ed errori e nuovi tentativi.

Verificare prima di pubblicare#

1. Apri l’ambiente di preproduzione in una finestra privata del browser, non nell’anteprima dell’editor WordPress.
2. Verifica che la richiesta SDK riesca e venga effettuata una sola volta.
3. Ispeziona il contenitore e confronta data-product-code carattere per carattere con lo sku importato.
4. Verifica che uno SKU importato produca un controllo di visualizzazione utilizzabile e che uno SKU sconosciuto non mostri un controllo non funzionante.
5. Prova navigazione del generatore di pagine, filtri, pulsanti Indietro/Avanti del browser, disposizione su dispositivi mobili e impostazioni del consenso.
6. Seleziona ogni variante supportata e verifica che il contenitore venga ricreato con il suo SKU.
7. Controlla la console del browser e ripeti le prove dopo aver riattivato cache e minificazione.

Rimuovere l’integrazione#

Rimuovi la funzione di accodamento dello script e il filtro script_loader_tag, poi elimina ogni blocco o frammento di modello data-idealhouse-button-container. Svuota tutte le cache e verifica che l’URL di SDK sia assente dal sorgente della pagina e dal pannello di rete.

Riferimenti ufficiali della piattaforma#

• Manuale dei temi WordPress: includere risorse
• Riferimento di WordPress per wp_enqueue_script()
• Temi figli di WordPress