Integrazione BigCommerce#
Aggiungi Room Visualizer a un negozio BigCommerce Stencil caricando SDK una sola volta e inserendo lo SKU del prodotto o della variante corrente in un contenitore per il pulsante generato.
Stato della verifica: documentazione per sviluppatori BigCommerce esaminata il 7 settembre 2026. Non era disponibile un negozio di prova. Stencil e Catalyst hanno modelli diversi di visualizzazione e navigazione; questa guida fornisce un percorso operativo per Stencil e indirizza i negozi Catalyst a un adattatore per il framework.
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.
Scegliere un percorso per il negozio#
- Stencil: installa il caricatore con Gestione script o l’API degli script, quindi aggiungi il contenitore a un modello personalizzato del tema.
- Catalyst: aggiungi script e componente nell’app Catalyst React/Next.js; segui React / Next.js.
- Blueprint precedente: passa a un negozio supportato oppure chiedi a uno sviluppatore BigCommerce di individuare un punto di inserimento sicuro. La documentazione attuale dell’API degli script tratta Blueprint separatamente.
Servono accesso alla modifica del tema, un tema o canale in preproduzione, Shop ID e Publishable Key di ideal.house e almeno uno SKU BigCommerce importato in ideal.house.
Contratto minimo di SDK#
<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 del contenitore deve corrispondere esattamente allo sku importato nel catalogo. Questa guida non presume l’esistenza di un’app ideal.house per BigCommerce.
Installare su Stencil#
In Negozio → Gestione script, crea uno script nel piè di pagina per il negozio o canale pertinente e le pagine prodotto. Incolla soltanto il tag script SDK dell’esempio, con le credenziali utilizzabili nel browser. Gestione script è l’equivalente nel pannello di controllo dell’API degli script che tiene conto dei canali.
Per un’app riutilizzabile, usa invece l’API degli script di BigCommerce. Quell’operazione API e il flusso OAuth dell’app sono responsabilità del tuo servizio di integrazione; non esporne il token di accesso nel codice del negozio.
Verifica che esista un solo tag SDK. Non includerlo anche in templates/layout/base.html.
Visualizzare il prodotto iniziale#
In un tema Stencil personalizzato, aggiungi il contenitore vicino al modulo prodotto, nel modello parziale della vista prodotto usato dal tema:
{{#if product.sku}}
<div
data-idealhouse-button-container
data-product-code="{{product.sku}}"
></div>
{{/if}}
Il modello parziale esatto varia in base al tema. Usa Stencil CLI per visualizzare in anteprima il tema personalizzato e conserva la modifica in un tema sotto controllo di versione, invece di modificare l’HTML generato del negozio.
Per le schede, visualizza il contenitore soltanto se il loro contesto espone lo SKU esatto importato. Un prodotto con opzioni potrebbe non avere uno SKU di variante finale in una pagina categoria; collega la pagina prodotto a meno che l’acquirente abbia selezionato una variante completa.
Sincronizzare le opzioni del prodotto#
Il codice JavaScript dei temi Stencil riceve le modifiche alle opzioni tramite codice dei dettagli prodotto specifico del tema. Aggiungi un adattatore del cliente nel punto in cui il tema corrente ha determinato la risposta della variante finale:
export function replaceIdealhouseContainer(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);
}
Passa lo SKU della variante determinata dalla funzione di richiamo del tema. I temi BigCommerce possono personalizzare o sostituire l’implementazione predefinita dei dettagli prodotto, quindi questa guida non inventa un evento globale di cambio opzione. Rimuovi il vecchio contenitore prima di inserire quello nuovo.
Vista rapida e pagine dinamiche#
Vista rapida, ricerca con filtri multipli, paginazione e navigazione lato client possono sostituire il DOM del prodotto. Aggiungi un contenitore pulito in ogni modello generato e richiama la stessa funzione di collegamento dopo il richiamo documentato del tema al termine della visualizzazione. Non clonare un contenitore già popolato da SDK.
Catalyst usa la visualizzazione lato client di React e non ha un contesto Stencil Handlebars. Carica SDK una sola volta nella struttura principale dell’app e assegna al componente di visualizzazione una chiave basata sullo SKU della variante selezionata, come nella guida React/Next.js.
Importare e associare i dati dei prodotti#
Associa i valori sku di BigCommerce allo sku di ideal.house; per le varianti, usa lo SKU di ciascuna invece dell’ID del prodotto padre. SDK del browser non sincronizza i dati del catalogo BigCommerce.
Usa Caricamento dei prodotti per il contratto di importazione approvato, quindi consulta importare prodotti, stato del processo, elencare prodotti, aggiornare prodotti, eliminare un prodotto ed errori e nuovi tentativi. Ogni esportazione BigCommerce API, notifica web o sincronizzazione pianificata richiede un adattatore gestito dal cliente.
Verificare e rimuovere#
Prima del lancio, prova un prodotto semplice, ogni combinazione di opzioni, un prodotto senza SKU e uno SKU assente da ideal.house. Controlla pagina prodotto, schede delle categorie, vista rapida, navigazione con filtri multipli, pulsanti Indietro/Avanti del browser, disposizione su dispositivi mobili, consenso e ciascun canale attivo del negozio. Negli strumenti per sviluppatori, verifica una sola richiesta SDK riuscita e la corrispondenza esatta tra Product Code e SKU.
Per rimuovere l’integrazione, elimina la voce di Gestione script o il record dell’API degli script, rimuovi tutto il codice dei contenitori del tema e dell’adattatore, pubblica il tema pulito, poi svuota le cache del negozio e della CDN. Verifica che la richiesta SDK sia assente da ogni canale.