WooCommerce-Integration#

Fügen Sie WooCommerce-Produktseiten Room Visualizer-Schaltflächen hinzu und halten Sie den ideal.house-Produktcode mit der SKU der ausgewählten Variante synchron.

Überprüfungsstatus: Dokumentation und öffentliches WooCommerce-Verhalten am 7. September 2026 geprüft. Diese Implementierung wurde in einem Kunden-Shop nicht zertifiziert. Classic-Templates, Block-Themes, Variationserweiterungen und Quick-View-Plugins können unterschiedliche DOM rendern; testen Sie den genauen Stack auf einer Staging-Umgebung.

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.

Umfang und Voraussetzungen#

Diese Anleitung zielt auf WooCommerce unter WordPress ab. Sie verwendet ein kleines site-spezifisches Plugin oder Child-Theme, den standard WordPress-Asset-Lader und WooCommerce-Produkt-Hooks. Sie ist kein installierbares ideal.house-WordPress-Plugin.

Bereiten Sie Administrator- und Datei-Zugriff vor, Shop ID, Publishable Key sowie importierte ideal.house-Datensätze für jedes visualisierbare SKU. Weisen Sie jedem einfachen Produkt und jeder unterstützten Variante einen nicht-leeren, eindeutigen SKU in WooCommerce zu.

Minimales SDK-Markup#

Dies ist die öffentliche SDK-Schnittstelle, die diese Integration verwendet:

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 generierte Container-Code muss dem importierten Katalog-sku entsprechen. Geben Sie keine WooCommerce-Datenbank-IDs in data-product-code ein, es sei denn, Sie haben diese IDs bewusst als Katalog-SKUs verwendet.

Laden Sie das SDK einmalig#

Fügen Sie diesen Code in ein Child-Theme-functions.php oder ein site-spezifisches Plugin ein. Ersetzen Sie die Platzhalter.

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

Wenn Sie WooCommerce-Versionen auf WordPress vor 6.3 unterstützen, übergeben Sie true als letztes Enqueue-Argument und fügen Sie async im Filter hinzu.

Hostelement auf der Produktseite rendern#

Der folgende Hook platziert ein Hostelement nach dem Warenkorbformular. Einfache Produkte erhalten sofort ihre SKU. Bei variablen Produkten bleibt das Element zunächst leer; der Browser-Adapter befüllt es, sobald eine vollständige Variante ausgewählt wurde.

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

Bestätigen Sie, dass der Hook in Ihrer Produktvorlage existiert. Ein Theme, das die WooCommerce-Vorlage oder den Produkt-Sammlung-Block ersetzt, erfordert möglicherweise eine Block-Integration oder einen anderen dokumentierten WooCommerce-Hook.

Ausgewählte Variante synchronisieren#

Das mit WooCommerce gelieferte Variantenformular löst jQuery-Ereignisse für den Variantenlebenszyklus aus. Fügen Sie eine lokale Datei hinzu, beispielsweise assets/js/idealhouse-woocommerce.js, und laden Sie sie mit den Abhängigkeiten jquery und wc-add-to-cart-variation. Verwenden Sie folgenden Code:

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

Diese Datei ist ein vom Kunden zu pflegender WooCommerce-Adapter. Wenn ein Varianten-Plugin das standardmäßige Formularskript ersetzt, verwenden Sie den dokumentierten Auswahl-Callback dieses Plugins, statt anzunehmen, dass diese Ereignisse weiterhin ausgelöst werden. Aktualisieren Sie nicht nur das Attribut eines bereits vom SDK verarbeiteten Containers, sondern ersetzen Sie ihn durch einen neuen, leeren Container.

Verwenden Sie für Katalog-Karten einen Produkt-Loop-Hook wie woocommerce_after_shop_loop_item und rendern Sie das einfache Produkt-SKU. Variable Produkte in einem Raster haben normalerweise keine aufgelöste Variante; verlinken Sie zur Produktseite oder erstellen Sie einen expliziten Variant-Picker-Adapter.

Quick-View-Plugins und WooCommerce-Blöcke können Produkte nach dem ersten Laden der Seite einfügen. Platzieren Sie das Hostelement in der von ihnen gerenderten Vorlage und rufen Sie Ihre render()-Anbindung im dokumentierten Abschluss-Callback des jeweiligen Werkzeugs auf. Gibt es keinen stabilen Callback, kann ein auf den relevanten Bereich begrenzter MutationObserver neue .idealhouse-host-Knoten erkennen. Leistung und Lebenszyklus müssen jedoch vom Kunden verantwortet werden.

Katalogzuordnung und Import#

Ordnen Sie WC_Product::get_sku() und jede einzelne WC_Product_Variation::get_sku() ideal.house-sku zu. Eltern- und Kind-Produkte dürfen keinen identischen Code teilen, wenn sie unterschiedliche visuelle Assets repräsentieren.

WooCommerce verschiebt Katalogänderungen nicht automatisch an ideal.house. Verwenden Sie Produktimport und seine Anleitungen zu Import, Auftragsstatus, Auflisten, Aktualisierungen, Löschen und Behandlung von Wiederholungsversuchen. Jeder geplante Export oder Webhook-Bridge ist Implementierungsleistung des Kunden.

Vor dem Launch überprüfen#

Testen Sie ein einfaches Produkt, ein variables Produkt, ein fehlendes SKU und ein SKU, das in ideal.house fehlt.
Bestätigen Sie, dass die SDK-Anfrage einmalig erfolgt und ihr Script-Tag beide Anmeldeinformationsattribute behält.
Wählen Sie jede Variation aus und verifizieren Sie, dass data-product-code gleich der Variation-SKU ist.
Setzen Sie das Variationsformular zurück; der alte Container sollte verschwinden.
Testen Sie ein Produktgrid, Quick View, AJAX-Filter, Cart-Fragmente, mobile sticky Add-to-Cart-Funktion und Browser-Zurück/Vorwärts, soweit zutreffend.
Testen Sie im abgemeldeten Zustand mit aktivierten Einwilligungssteuerungen und dem Caching der Produktionsumgebung.
Stellen Sie sicher, dass kein Client Secret in HTML, JavaScript, Logs oder Source Maps erscheint.

Integration entfernen#

Entfernen Sie die PHP-Hooks und den Filter sowie das Einbinden des lokalen Variantenadapters. Löschen Sie Hostelemente aus überschriebenen Vorlagen oder Blöcken, leeren Sie WooCommerce-Transients und Seiten-/CDN-Caches und prüfen Sie anschließend, dass weder SDK-Anfragen noch data-idealhouse-*-Elemente verbleiben.