Integrazione con Ecwid#

Usa un'app personalizzata per il negozio Ecwid e il ciclo di vita documentato di Storefront JS API per aggiungere i controlli Room Visualizer alle pagine prodotto Ecwid.

Stato della verifica: documentazione Ecwid Storefront JS API esaminata il 7 settembre 2026. Non erano disponibili un'app Ecwid né un negozio di prova di un commerciante. Prima della distribuzione, conferma i campi esatti dei dati della pagina nel riferimento aggiornato di OnPageLoaded.

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 procedura supportata#

Ecwid richiede un'app personalizzata con un file JavaScript ospitato autonomamente per personalizzare il negozio in modo duraturo. Prepara un negozio/app di sviluppo Ecwid, un file adattatore ospitato tramite HTTPS, Shop ID, Publishable Key e SKUs di prodotti/varianti importati.

Se Ecwid è incorporato in un altro CMS, l'app personalizzata del negozio resta il punto affidabile per il codice, perché viene eseguita insieme al negozio Ecwid. Uno script della pagina contenitrice potrebbe non condividere lo stesso ciclo di vita o documento in ogni modalità di incorporamento.

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>

Usa lo SKU Ecwid esatto che hai importato come sku di ideal.house.

Inizializza l'app del negozio Ecwid#

Segui la guida rapida di Ecwid per i negozi personalizzati per registrare il file ospitato autonomamente. Avvialo con la funzione di richiamo documentata che segnala quando API è pronta, quindi carica SDK di ideal.house una sola volta:

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

  const 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.append(script);
});

Per un'app destinata a più negozi, ottieni i due valori pubblici ideal.house dalla configurazione pubblica sicura dell'app. Non inserire mai in questo file un segreto dell'app Ecwid, un token di accesso o un Client Secret di ideal.house.

Visualizza nelle pagine prodotto#

Ecwid documenta Ecwid.OnPageLoaded.add() e fornisce informazioni sulla pagina alla sua funzione di richiamo. Usa il riferimento API aggiornato per confermare il tipo e l'identificatore della pagina prodotto, recupera o leggi i dati del prodotto tramite l'interfaccia client supportata da Ecwid, quindi passa lo SKU determinato a:

function mountIdealhouse(host, sku) {
  host.replaceChildren();
  const code = String(sku || '').trim();
  if (!code) return;

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

Inserisci host in una posizione stabile dei dettagli prodotto dopo che Ecwid ha terminato la visualizzazione della pagina. Rimuovi il contenitore precedente quando cambia il tipo di pagina. Il selettore DOM e la ricerca del prodotto a partire dai dati della pagina sono codice adattatore del cliente, perché le disposizioni dei negozi Ecwid e le versioni dei dati possono cambiare.

Opzioni e navigazione#

Quando un acquirente sceglie le opzioni del prodotto, attendi che Ecwid determini la variante acquistabile e il suo SKU. Chiama mountIdealhouse() con tale SKU oppure svuota il contenitore se la selezione è incompleta. Non concatenare le etichette delle opzioni per inventare un codice.

Ecwid è un negozio a pagina singola. Usa il suo ciclo di vita documentato delle pagine (OnPageLoaded/funzioni di richiamo al cambio pagina) anziché ascoltare soltanto DOMContentLoaded del browser. La navigazione tra categorie/ricerche, Indietro/Avanti del browser, i widget incorporati e le finestre a comparsa dei prodotti devono rimuovere i contenitori dei prodotti precedenti e montare un nuovo contenitore dopo la visualizzazione.

Importare i prodotti#

Esporta i campi SKU dei prodotti e delle varianti Ecwid e associali a sku di ideal.house. Usa Caricamento dei prodotti, comprese importare prodotti, stato del processo, elencare prodotti, aggiornare prodotti, eliminare un prodotto ed errori e nuovi tentativi.

Qualsiasi esportazione Ecwid REST API, webhook, installazione OAuth o sincronizzazione ricorrente è a carico del cliente e deve essere implementata sul server con l'autorizzazione Ecwid appropriata.

Verificare e rimuovere#

Prova l'installazione dell'app, l'inizializzazione API, le transizioni tra prodotti/categorie/ricerca, ogni variante, SKUs mancanti e sconosciuti, Indietro/Avanti del browser, un widget Ecwid incorporato in un altro sito, disposizione sui dispositivi mobili, consenso e clienti con/senza accesso effettuato. Verifica una sola richiesta SDK nel documento che contiene il contenitore e l'uguaglianza esatta dello SKU.

Per rimuovere l'integrazione, scollega il file JavaScript ospitato autonomamente dall'app personalizzata oppure disinstalla l'app, rimuovi i contenitori/gestori degli eventi inseriti e verifica che la URL di SDK e tutti i nodi data-idealhouse-* scompaiano dopo la navigazione nel negozio e un ricaricamento completo.