Intégration BigCommerce#
Ajoutez Room Visualizer à une boutique en ligne Stencil de BigCommerce en chargeant le SDK une seule fois et en affichant le code produit ou la variante SKU actuelle dans un conteneur de bouton généré.
État de vérification : documentation développeur BigCommerce consultée le 7 septembre 2026. Aucune boutique de test n'était disponible. Stencil et Catalyst ont des modèles de rendu et de navigation différents ; ce guide propose un parcours Stencil actionnable et oriente les boutiques en ligne Catalyst vers un adaptateur de framework.
Avant de charger le SDK : ouvrez Tableau de bord → Paramètres, ajoutez l'origine de votre boutique en ligne à Allowed Origins (CORS), puis cliquez sur Enregistrer. Incluez le nom d'hôte publié et toutes les origines d'aperçu ou de préproduction que vous utilisez ; séparez plusieurs origines par des virgules. Voir les étapes de configuration.
Choisir un parcours de boutique en ligne#
- Stencil : installez le chargeur avec Script Manager ou Scripts API, puis ajoutez le conteneur dans un modèle de thème personnalisé.
- Catalyst : ajoutez le script et le composant dans l'application React/Next.js Catalyst ; suivez React / Next.js.
- Blueprint (ancienne version) : migrez vers une boutique en ligne prise en charge ou faites identifier un point d'insertion sûr par un développeur BigCommerce. La documentation actuelle de Scripts API traite Blueprint séparément.
Vous avez besoin d'un accès à la modification du thème, d'un thème/canal de préproduction, d'un Shop ID et d'une Publishable Key ideal.house, ainsi que d'au moins un SKU BigCommerce importé dans ideal.house.
Contrat minimal du 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>
Le code produit du conteneur doit correspondre exactement au code produit sku du catalogue importé. Ce guide ne suppose pas l'existence d'une application BigCommerce ideal.house.
Installation sur Stencil#
Dans Boutique en ligne → Script Manager, créez un script de pied de page pour la boutique en ligne/le canal et les pages produit concernés. Collez uniquement la balise de script SDK de l'exemple, avec vos identifiants sûrs pour le navigateur. Script Manager est l'équivalent du panneau de contrôle de Scripts API prenant en compte les canaux.
Pour une application réutilisable, utilisez plutôt Scripts API de BigCommerce. Cette opération d'API et le flux OAuth de l'application sont de la responsabilité de votre service d'intégration ; n'exposez pas son jeton d'accès dans le code de la boutique en ligne.
Vérifiez qu'une seule balise SDK existe. N'incluez pas également le script dans templates/layout/base.html.
Afficher le produit initial#
Dans un thème Stencil personnalisé, ajoutez le conteneur près du formulaire produit dans le partiel de vue produit utilisé par votre thème :
{{#if product.sku}}
<div
data-idealhouse-button-container
data-product-code="{{product.sku}}"
></div>
{{/if}}
Le partiel exact varie selon le thème. Utilisez Stencil CLI pour prévisualiser le thème personnalisé et conservez la modification dans un thème sous contrôle de versions plutôt que de modifier le HTML généré de la boutique en ligne.
Pour les cartes, affichez le conteneur uniquement lorsque le contexte de la carte expose le code produit SKU exact que vous avez importé. Un produit avec des options peut ne pas avoir de code produit de variante finale SKU sur une page de catégorie ; liez vers la page produit sauf si l'acheteur a sélectionné une variante complète.
Synchroniser les options produit#
Le JavaScript du thème Stencil reçoit les modifications des options produit via le code de détails produit spécifique au thème. Ajoutez un adaptateur client au point où le thème actuel a résolu la réponse de la 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);
}
Transmettez le code produit de la variante résolue SKU depuis votre rappel de thème. Les thèmes BigCommerce peuvent personnaliser ou remplacer l'implémentation par défaut des détails produit, ce guide n'invente donc pas un événement global de modification d'option. Supprimez l'ancien conteneur avant d'insérer le nouveau.
Aperçu rapide et pages dynamiques#
L'aperçu rapide, la recherche facettée, la pagination et la navigation côté client peuvent remplacer le DOM du produit. Ajoutez un conteneur propre dans chaque modèle affiché et invoquez le même pont après le rappel de rendu documenté du thème. Ne clonez pas un conteneur déjà rempli par le SDK.
Catalyst utilise un rendu côté client React et n'a pas de contexte Handlebars Stencil. Chargez le SDK une seule fois dans la structure principale de l'application et indexez le composant visualiseur par le code produit de la variante sélectionnée SKU, comme indiqué dans le guide React/Next.js.
Importer et mapper les données produit#
Mappez les valeurs de code produit sku de BigCommerce vers le code produit sku de ideal.house ; pour les variantes, utilisez le code produit SKU de chaque variante plutôt que l'identifiant du produit parent. Les données de catalogue BigCommerce ne sont pas synchronisées par le SDK côté navigateur.
Utilisez Téléversement de produits pour le contrat d'importation approuvé, puis vérifiez Importer des produits, État de la tâche, Lister les produits, Mettre à jour les produits, Supprimer un produit et Erreurs et nouvelles tentatives. Tout export, webhook ou synchronisation planifiée de l'API de BigCommerce est un adaptateur exploité par le client.
Vérifier et supprimer#
Avant la mise en production, testez un produit simple, chaque combinaison d'options, un produit sans code produit SKU, et un code produit SKU manquant dans ideal.house. Vérifiez la page produit, les cartes de catégorie, l'aperçu rapide, la navigation facettée, les boutons Retour/Avant du navigateur, la mise en page mobile, le comportement du consentement et chaque canal de boutique en ligne actif. Dans DevTools, vérifiez une requête SDK réussie et une correspondance exacte entre le code produit et le code produit SKU.
Pour supprimer l'intégration, supprimez l'entrée Script Manager ou l'enregistrement de Scripts API, retirez toutes les balises de conteneur du thème et le code de l'adaptateur, publiez le thème propre, puis purgez les caches de la boutique en ligne/CDN. Vérifiez que la requête SDK est absente de chaque canal.