Ideal House
Zum Hauptinhalt springen

WordPress-Integration#

Fügen Sie den ideal.house Room Visualizer auf einer WordPress-Site hinzu, indem Sie ein öffentliches Browser-Skript laden und einen Container rendern, dessen Produktcode mit einem importierten Katalog-SKU übereinstimmt.

Überprüfungsstatus: Dokumentation am 7. September 2026 geprüft. Dieser Leitfaden wurde nicht in allen Schritten gegen ein Kunden-WordPress-Theme zertifiziert. Validieren Sie ihn auf einer Staging-Kopie Ihrer exakten Theme- und Page-Builder-Versionen, bevor Sie ihn veröffentlichen.

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 behandelt WordPress-Content-Sites, klassische Themes, Block-Themes und Page Builder, die das Hinzufügen von HTML ermöglichen. Wenn die Site WooCommerce-Produktdaten verwendet, nutzen Sie die WooCommerce-Anleitung zur Variantenauswahl.

Vorbereiten:

  • Administrator-Zugriff und für die dauerhafte Methode ein Child-Theme oder ein kleines site-spezifisches Plugin;
  • die Shop ID und den Publishable Key vom ideal.house Dashboard;
  • ein Produkt, das bereits in ideal.house importiert wurde und über eine bekannte sku verfügt;
  • eine Staging-Seite, auf der Cache/Minimierung während der Tests deaktiviert werden kann.

Der Publishable Key ist für Browser-Markup vorgesehen. Platzieren Sie niemals einen Client Secret oder AI API-Schlüssel in WordPress-HTML.

SDK-Schnittstelle bestätigen#

Die kleinstmögliche Installation besteht genau aus einem SDK-Skript und einem generierten-Button-Container:

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>

data-product-code muss einschließlich Groß-/Kleinschreibung und Satzzeichen mit dem Katalogwert sku übereinstimmen. Das SDK verwaltet den Inhalt des Containers. Diese Anleitung stellt kein ideal.house-Plugin für WordPress bereit.

Installieren Sie das Skript site-weit#

WordPress empfiehlt, Frontend-Skripte über wp_enqueue_script() zu laden. Fügen Sie Folgendes in ein Child-Theme-functions.php oder ein site-spezifisches Plugin ein. Der Filter fügt die beiden erforderlichen Datenattribute zum Tag hinzu, das WordPress erzeugt.

php
add_action('wp_enqueue_scripts', function () {
    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);

Ersetzen Sie beide Platzhalter. WordPress-Versionen vor 6.3 akzeptieren die Array-Form des letzten wp_enqueue_script()-Arguments nicht; übergeben Sie stattdessen true und verwenden Sie den script_loader_tag-Filter, um ebenfalls async hinzuzufügen.

Installieren Sie das SDK nicht erneut in einem Code-Block oder Tag-Manager. In DevTools sollte document.querySelectorAll('script[src="https://sdk.ideal.house/sdk.js"]').length 1 zurückgeben.

Schaltfläche platzieren#

Fügen Sie im Block-Editor dort einen Block für individuelles HTML hinzu, wo die Schaltfläche erscheinen soll:

html
<div data-idealhouse-button-container data-product-code="CHAIR-OAK-01"></div>

Für wiederholte Karten rendern Sie dasselbe Markup aus der Theme-Vorlage und maskieren den Code als HTML-Attribut:

php
<div
  data-idealhouse-button-container
  data-product-code="<?php echo esc_attr($idealhouse_product_code); ?>"
></div>

Ihr Theme oder Plugin muss $idealhouse_product_code bereitstellen. Verwenden Sie keine Beitrags-ID, keinen Slug und keinen Titel, es sei denn, dieser exakte Wert ist auch der importierte ideal.house-sku.

Produkt- und Variantenzuordnung#

Erstellen Sie vor dem Launch eine explizite Zuordnungstabelle:

WordPress-Wertideal.house-WertRegel
benutzerdefiniertes Feld wie idealhouse_skuskuexakte Zeichenübereinstimmung
eine Seite ohne Variantenein importiertes Produktein Container
Page-Builder-Sammlungspositionpositionsspezifisches SKU-Feldverwenden Sie niemals einen sammlungsweiten Code

Wenn auf der Seite zwischen Varianten gewechselt wird, muss der kundenseitige Adapter den neuen data-product-code setzen. Entfernen Sie den alten Container, bevor Sie den neuen einfügen, damit kein veralteter Zustand der Anzeige wiederverwendet wird:

js
function renderIdealhouseButton(host, sku) {
  host.replaceChildren();
  if (!sku) return;

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

Dies ist Kunden-Adapter-Code. Er ruft keine undokumentierte ideal.house-Methode auf und erfindet auch kein WordPress-Event; rufen Sie ihn aus dem dokumentierten Callback auf, den Ihr Theme oder Page Builder bereitstellt.

Dynamische Navigation und Caches#

Fügen Sie bei AJAX-Filtern, endlosem Scrollen, modalen Produktkarten oder Seitenübergängen des Page Builders einen neuen Container ein, nachdem der neue Produktknoten im DOM vorhanden ist. Klonen Sie keinen Container, den das SDK bereits befüllt hat. Falls Ihr Werkzeug keinen stabilen Rendering-Callback bereitstellt, fügen Sie den Container in dessen Elementvorlage ein, sodass jedes Rendern neues Markup erzeugt.

Leeren Sie nach einer Theme-Änderung die Caches von WordPress, CDN und Optimierungs-Plugins. Schließen Sie https://sdk.ideal.house/sdk.js von Änderungen für verzögertes Laden aus, wenn ein Leistungsoptimierungs-Plugin seine Datenattribute entfernt oder das Laden bis nach einer Interaktion aufschiebt.

Katalogdaten importieren#

WordPress-Inhalte werden nicht automatisch synchronisiert. Exportieren Sie das ausgewählte benutzerdefinierte Feld als sku und importieren Sie die passenden Datensätze über Produktimport. Fahren Sie fort mit Produkte importieren, Auftragsstatus, Produkte auflisten, Produkte aktualisieren, Produkt löschen und Fehler und Wiederholungsversuche.

Vor der Veröffentlichung überprüfen#

  1. Öffnen Sie Staging in einem inkognito-Browserfenster, nicht in der WordPress-Editor-Vorschau.
  2. Bestätigen Sie, dass die SDK-Anforderung erfolgreich und nur einmal zurückkehrt.
  3. Prüfen Sie den Container und vergleichen Sie data-product-code zeichenweise mit dem importierten sku.
  4. Bestätigen Sie, dass ein importiertes SKU eine verwendbare Visualizer-Steuerung erzeugt und ein unbekanntes SKU keine kaputte Steuerung anzeigt.
  5. Testen Sie Page-Builder-Navigation, Filter, Browser-Zurück/Vorwärts, mobiles Layout und Einwilligungs-Einstellungen.
  6. Wählen Sie jede unterstützte Variante aus und bestätigen Sie, dass der Container mit seinem SKU neu erstellt wird.
  7. Überprüfen Sie die Browser-Konsole und testen Sie erneut mit aktiviertem Cache/Minimierung.

Integration entfernen#

Entfernen Sie die Enqueue-Funktion und den script_loader_tag-Filter, dann löschen Sie jeden data-idealhouse-button-container-Block oder jedes Template-Fragment. Löschen Sie alle Caches und bestätigen Sie, dass die SDK-URL im Seitenquelltext und im Netzwerkpanel nicht vorhanden ist.

Offizielle Plattformreferenzen#