Ideal House
Zum Hauptinhalt springen

Adobe Commerce / Magento Open Source Integration#

Installieren Sie Room Visualizer über ein Magento-Modul oder ein benutzerdefiniertes Theme und ordnen Sie die angezeigte SKU des einfachen Produkts dem ideal.house-Katalog zu.

Überprüfungsstatus: Die Adobe Commerce-Frontend-Dokumentation wurde am 7. September 2026 geprüft. Es stand keine Händlerinstallation zur Verfügung. Luma/Blank-Themes, Hyvä und PWA Studio verwenden unterschiedliche JavaScript-Umgebungen; das folgende konkrete Beispiel richtet sich an den standardmäßigen RequireJS-Onlineshop.

Vor dem Laden des SDK: Öffnen Sie Dashboard → Einstellungen, fügen Sie den Origin Ihres Onlineshops zu Allowed Origins (CORS) hinzu und klicken Sie auf Speichern. Berücksichtigen Sie den veröffentlichten Hostnamen sowie alle verwendeten Vorschau- oder Staging-Origins; trennen Sie mehrere Origins durch Kommas. Siehe Konfigurationsschritte.

Voraussetzungen und Umfang#

Bereiten Sie eine Entwicklungsumgebung, ein benutzerdefiniertes Modul oder Child-Theme, Bereitstellungszugriff, Shop ID, Publishable Key sowie importierte Test-SKUs vor. Ändern Sie niemals Dateien unter vendor/ oder in einem Base-Theme. Hyvä und PWA Studio benötigen jeweils eigene Alpine/React-Adapter und dürfen nicht blind RequireJS-Code kopieren.

Minimale SDK-Schnittstelle#

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>

Der Product Code entspricht dem exakt importierten sku, nicht der numerischen Entitäts-ID von Magento.

Produktseitenblock hinzufügen#

Erstellen Sie ein kleines Modul oder ein Theme-Layout-Update für catalog_product_view. Verweisen Sie einen Block auf eine .phtml-Vorlage, die in der Nähe der Produktaktionen positioniert ist. Die Vorlage kann das initiale Produkt-SKU sicher rendern:

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>

Bei einem konfigurierbaren Produkt ist die anfängliche SKU der Seite üblicherweise die SKU des übergeordneten Produkts. Wenn die ideal.house-Assets zu untergeordneten einfachen Produkten gehören, lassen Sie das Hostelement zunächst leer und befüllen Sie es erst, nachdem das ausgewählte einfache Produkt ermittelt wurde.

Das SDK einmal laden#

Fügen Sie Ihrem Modul oder Theme einen lokalen RequireJS-Initialisierer hinzu. Dieser erstellt das externe Skript und setzt vor dem Einfügen alle erforderlichen Datenattribute:

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

Initialisieren Sie es deklarativ aus der Vorlage gemäß dem von Adobe empfohlenen text/x-magento-init-Mechanismus:

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

Dies erzeugt dasselbe SDK-Element wie die minimale Schnittstelle, ohne Zugangsdaten in einer RequireJS-URL zu platzieren. Verwenden Sie im Onlineshop-Code ausschließlich den Publishable Key.

Ausgewähltes konfigurierbares SKU#

Das Standard-Widget für konfigurierbare Produkte stellt den Auswahlzustand über die eigene Komponente von Magento bereit; Theme-Anpassungen können jedoch dessen Struktur ändern. Implementieren Sie in Ihrem Modul ein RequireJS-Mixin oder einen Listener an der Stelle, an der das Theme die ID eines einfachen Produkts ermittelt. Ordnen Sie diese ID anhand der vom Server bereitgestellten JSON-Daten ihrer SKU zu und ersetzen Sie das Hostelement:

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

Dieses Mixin und die Zuordnungsdaten von ID zu SKU müssen als kundenseitiger Adapter implementiert werden. Leiten Sie die SKU des untergeordneten Produkts nicht aus Optionsbeschriftungen ab. Dokumentieren Sie keine ideal.house-Ereignisse oder -Methoden, die nicht zur öffentlichen SDK-Schnittstelle gehören.

Dynamische Inhalte und Caches#

Erstellen Sie den Container neu, nachdem eine Änderung der Farbmuster, per AJAX geladene Empfehlungen, eine Schnellansicht oder kundenspezifische Inhalte sein Hostelement ersetzen. Das Magento-Ereignis contentUpdated initialisiert Magento-Komponenten in eingefügten Inhalten, liefert aber nicht selbst die ausgewählte SKU. Ihr Adapter muss daher weiterhin den richtigen Code ermitteln und rendern.

Führen Sie nach Codeänderungen die deploymentspezifischen Schritte aus, leeren Sie Layout-/Full-Page-/Block-Caches und stellen Sie statische Inhalte erneut bereit. Testen Sie mit Produktions-Bundling/Minimierung sowie aktiviertem Varnish/CDN.

Produktdaten importieren#

Ordnen Sie einfache und Child-Product-SKUs den ideal.house sku-Werten zu. Nutzen Sie Produkt-Upload, einschließlich Import, Auftragsstatus, Auflistung, Aktualisierungen, Löschung und Empfehlungen zu Wiederholungsversuchen. Magento-Exporte, Admin-API-Aufrufe, Cron-Jobs und Webhooks sind Kundenadapter.

Überprüfen und entfernen#

Testen Sie einfache, konfigurierbare, fehlende-SKU-, deaktivierte-Kind- und unbekannte-SKU-Fälle. Bestätigen Sie eine einzelne SDK-Anfrage, exakte SKU-Zuordnung nach jeder Swatch/Option-Änderung, sauberes Verhalten bei Quick View und Empfehlungen, mobiles Layout, Cache-Treffer, Kundengruppen-Seiten sowie Einwilligungssteuerungen. Stellen Sie sicher, dass keine geheimen Anmeldeinformationen im Quellcode oder statischen Assets erscheinen.

Zum Entfernen deaktivieren oder deinstallieren Sie das benutzerdefinierte Modul oder entfernen Sie die Layout-, Template- und RequireJS-Dateien des Child-Themes. Stellen Sie statische Inhalte erneut bereit, leeren Sie die Caches und prüfen Sie, dass die SDK-URL und die Container nicht mehr vorhanden sind.

Offizielle Plattformreferenzen#