Intégration Adobe Commerce / Magento Open Source#

Installez Room Visualizer via un module ou un thème personnalisé Magento et mappez le code produit SKU du produit simple affiché vers le catalogue ideal.house.

État de vérification : documentation front-end Adobe Commerce consultée le 7 septembre 2026. Aucune installation marchand n'était disponible. Les thèmes Luma/Blank, Hyvä et PWA Studio utilisent des piles JavaScript différentes ; l'exemple concret ci-dessous cible la boutique en ligne RequireJS standard.

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.

Prérequis et périmètre#

Préparez une instance de développement, un module personnalisé ou un thème enfant, un accès au déploiement, un Shop ID, une Publishable Key et des SKU de test importés. Ne modifiez jamais les fichiers sous vendor/ ou un thème de base. Hyvä et PWA Studio nécessitent leur propre adaptateur Alpine/React et ne doivent pas copier aveuglément le code RequireJS.

Contrat minimal du 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>

Le code produit est le code produit sku importé exact, et non l'identifiant d'entité numérique de Magento.

Ajouter un bloc de page produit#

Créez un petit module ou une mise à jour de mise en page de thème pour catalog_product_view. Pointez un bloc vers un modèle .phtml positionné près des actions produit. Le modèle peut afficher en toute sécurité le SKU initial du produit :

php

<?php
/** @var \Magento\Catalog\Block\Product\View $block */
$product = $block->getProduct();
$sku = $product ? trim((string) $product->getSku()) : '';
?>

<div class="idealhouse-host">
  <?php if ($sku !== ''): ?>
    <div
      data-idealhouse-button-container
      data-product-code="<?= $block->escapeHtmlAttr($sku) ?>"
    ></div>
  <?php endif; ?>
</div>

Pour un produit configurable, le code produit initial SKU de la page est généralement le code produit parent SKU. Si les ressources ideal.house appartiennent à des produits simples enfants, laissez le conteneur vide au départ et remplissez-le uniquement après la résolution du produit simple sélectionné.

Charger le SDK une seule fois#

Ajoutez un initialiseur local RequireJS dans votre module ou votre thème. L'initialiseur crée le script externe et applique tous les attributs de données requis avant de l'ajouter :

define([], function () {
  'use strict';

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

    var 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.appendChild(script);
  };
});

Initialisez-le de manière déclarative depuis le modèle, en suivant le mécanisme text/x-magento-init recommandé par Adobe :

html

<script type="text/x-magento-init">
{
  "*": {
    "Vendor_Module/js/idealhouse-loader": {}
  }
}
</script>

Cela produit le même élément SDK que le contrat minimal sans placer d'identifiants dans une URL RequireJS. Utilisez uniquement la Publishable Key dans le code de la boutique en ligne.

SKU configurable sélectionné#

Le widget standard de produit configurable expose l'état de sélection via le propre composant de Magento, mais les substitutions de thème en modifient la forme. Implémentez un mixin ou un écouteur RequireJS dans votre module au point où le thème résout un identifiant de produit simple, mappez cet identifiant vers son code produit SKU à partir du JSON fourni par le serveur, et remplacez le conteneur :

function renderIdealhouseSku(host, sku) {
  host.replaceChildren();
  if (!sku || !sku.trim()) return;

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

Ce mixin et les données d'identifiant vers code produit SKU relèvent du travail de l'adaptateur client. N'inférez pas le code produit enfant SKU à partir des libellés d'options, et ne documentez pas un événement ou une méthode ideal.house qui ne fait pas partie du contrat public du SDK.

Contenu dynamique et caches#

Recréez le conteneur après les modifications de nuancier, les recommandations chargées en AJAX, l'aperçu rapide ou lorsque le contenu spécifique au client remplace son conteneur. L'événement contentUpdated de Magento initialise les composants Magento dans le contenu injecté ; il ne fournit pas à lui seul un code produit sélectionné SKU, votre adaptateur doit donc toujours résoudre et afficher le bon code.

Après des modifications de code, exécutez les étapes de déploiement appropriées à l'environnement, videz les caches de mise en page/page complète/bloc et redéployez le contenu statique. Testez avec le regroupement/minification de production et Varnish/CDN activés.

Importer les données produit#

Mappez les SKU des produits simples et enfants vers le code produit sku de ideal.house. Utilisez Téléversement de produits, y compris Importer, État de la tâche, Liste, Mises à jour, Suppression et Conseils de nouvelle tentative. Les exports Magento, les appels de Admin API, les tâches cron et les webhooks sont des adaptateurs client.

Vérifier et supprimer#

Testez les cas simple, configurable, code produit manquant SKU, enfant désactivé et code produit inconnu SKU. Vérifiez une seule requête SDK, un mappage exact du code produit SKU après chaque modification de nuancier/option, un comportement propre dans l'aperçu rapide et les recommandations, la mise en page mobile, les accès servis depuis le cache, les pages de groupe de clients et les contrôles de consentement. Vérifiez qu'aucun identifiant secret n'apparaît dans le code source ou les ressources statiques.

Pour supprimer, désactivez/désinstallez le module personnalisé ou supprimez les fichiers de mise en page/modèle/RequireJS du thème enfant, redéployez le contenu statique, videz les caches et vérifiez que l'URL du SDK et les conteneurs sont absents.