Intégration WooCommerce#

Ajoutez des boutons Room Visualizer aux pages produits WooCommerce et maintenez le code produit ideal.house synchronisé avec le SKU de la variante sélectionnée.

État de vérification : Documentation et comportement public de WooCommerce examinés le 7 septembre 2026. Cette implémentation n’a pas été certifiée dans une boutique client. Les modèles classiques, les thèmes par blocs, les extensions de variation et les plugins de vue rapide peuvent générer des DOM différents ; testez la pile exacte en préproduction.

Avant de charger le SDK : ouvrez Dashboard → Settings, ajoutez l’origine de votre boutique en ligne à Allowed Origins (CORS) et cliquez sur Save. Incluez l’hôte publié ainsi que toutes les origines d’aperçu ou de préproduction que vous utilisez ; séparez plusieurs origines par des virgules. Consultez étapes de configuration.

Champ d’application et prérequis#

Ce guide cible WooCommerce sur WordPress. Il utilise un petit plugin spécifique au site ou un thème enfant, le chargeur de ressources standard WordPress et les accroches produit WooCommerce. Il ne s’agit pas d’un plugin WordPress ideal.house installable.

Préparez l’accès administrateur et fichier, Shop ID, Publishable Key et les enregistrements ideal.house importés pour chaque SKU visualisable. Attribuez à chaque produit simple et à chaque variante prise en charge un SKU non vide et unique dans WooCommerce.

Balise minimale SDK#

Voici le contrat SDK public utilisé par l’intégration :

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>

Le code du conteneur généré doit correspondre au sku de catalogue importé. N’insérez pas les identifiants de base de données WooCommerce dans data-product-code à moins que vous n’ayez explicitement utilisé ces identifiants comme SKUs de catalogue.

Chargez le SDK une seule fois#

Ajoutez ce code au fichier functions.php d’un thème enfant ou à un plugin spécifique au site. Remplacez les espaces réservés.

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

Si vous prenez en charge les versions WooCommerce sur WordPress antérieures à 6.3, passez true comme dernier argument d’enregistrement et ajoutez async dans le filtre.

Rendu de l’hôte de page produit#

L’accroche suivante place un hôte après le formulaire d’ajout au panier. Les produits simples reçoivent leur SKU immédiatement. Les produits variables démarrent vides ; l’adaptateur navigateur les remplit lorsqu’une variation complète est sélectionnée.

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>' : ''
    );
});

Confirmez que l’accroche existe dans votre modèle de produit. Un thème qui remplace le modèle WooCommerce ou le bloc Product Collection peut nécessiter une intégration par blocs ou une autre accroche WooCommerce documentée.

Synchronisation d’une variation sélectionnée#

Le formulaire de variation intégré à WooCommerce déclenche des événements cycle de vie jQuery pour les variations. Ajoutez un fichier local, par exemple assets/js/idealhouse-woocommerce.js, enregistrez-le avec les dépendances jquery et wc-add-to-cart-variation, puis utilisez :

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

Ce fichier est un adaptateur WooCommerce appartenant au client. Si un plugin de variation remplace le script de formulaire standard, utilisez la fonction de rappel de sélection documentée par ce plugin au lieu de supposer que ces événements se produisent toujours. Ne mettez pas à jour uniquement l’attribut d’un conteneur déjà traité par le SDK ; remplacez-le par un conteneur propre.

Pour les cartes de catalogue, utilisez une accroche de boucle produit telle que woocommerce_after_shop_loop_item et affichez le SKU du produit simple. Les produits variables dans une grille n’ont généralement pas de variation résolue ; liez vers la page produit ou concevez un adaptateur explicite de sélecteur de variation.

Les plugins de vue rapide et les blocs WooCommerce peuvent injecter des produits après le chargement initial de la page. Placez l’hôte dans le modèle qu’ils rendent et exécutez votre pont render() depuis la fonction de rappel de complétion documentée par cet outil. S’il n’existe pas de fonction de rappel stable, un MutationObserver ciblé peut détecter les nouveaux nœuds .idealhouse-host, mais le client en assume les performances et le cycle de vie.

Mappage et importation de catalogue#

Mappez WC_Product::get_sku() et chaque WC_Product_Variation::get_sku() à ideal.house sku. Les produits parents et enfants ne doivent pas partager un code s’ils représentent des ressources visuelles différents.

WooCommerce ne pousse pas automatiquement les modifications du catalogue vers ideal.house. Utilisez Téléversement de produits et ses guides pour l'importation, le statut des tâches, la liste des produits, les mises à jour, la suppression et le traitement des nouvelles tentatives. Tout export planifié ou pont webhook relève de l'implémentation du client.

Vérifiez avant le lancement#

Testez un produit simple, un produit variable, un SKU manquant et un SKU absent de ideal.house.
Confirmez que le SDK est demandé une seule fois et que sa balise script conserve les deux attributs d’identifiant.
Sélectionnez chaque variation et vérifiez que data-product-code est égal au SKU de la variation.
Réinitialisez le formulaire de variation ; l’ancien conteneur doit disparaître.
Testez une grille de produits, une vue rapide, les filtres AJAX, les fragments de panier, le bouton d’ajout au panier fixe sur mobile et la navigation Avant/Arrière du navigateur lorsque cela s’applique.
Testez en mode déconnecté, avec les contrôles de consentement et la mise en cache de production activés.
Vérifiez qu’aucun Client Secret n’apparaît dans le HTML, le JavaScript, les journaux ou les fichiers de correspondance du code source.

Supprimer l’intégration#

Supprimez les accroches/filtres PHP et l’enregistrement de l’adaptateur de variation local. Supprimez les hôtes des modèles ou blocs substitués, effacez les transients WooCommerce et les caches page/CDN, puis confirmez qu’aucune requête SDK ou élément data-idealhouse-* ne subsiste.