Integracja WooCommerce#

Dodaj przyciski Room Visualizer do stron produktów WooCommerce i utrzymuj kod produktu ideal.house zsynchronizowany z wybranym wariantem SKU.

Status weryfikacji: Dokumentacja i publiczne zachowanie WooCommerce sprawdzona 7 września 2026. Ta implementacja nie została zweryfikowana w sklepie klienta. Klasyczne szablony, motywy blokowe, rozszerzenia wariantów i pluginy szybkiego podglądu mogą renderować różne DOM; przetestuj dokładny stos na stagingu.

Przed załadowaniem SDK: Otwórz Panel → Ustawienia, dodaj adres źródłowy witryny sklepu do Allowed Origins (CORS) i kliknij Zapisz. Uwzględnij rzeczywistą nazwę hosta opublikowanego sklepu oraz używane adresy podglądu i środowisk testowych; wiele adresów oddzielaj przecinkami. Zobacz instrukcję konfiguracji.

Zakres i wymagania wstępne#

Ten przewodnik dotyczy WooCommerce na WordPress. Używa małego pluginu specyficznego dla witryny lub motywu potomnego, standardowego ładowacza zasobów WordPress i hooków produktów WooCommerce. Nie jest to instalowalny plugin ideal.house WordPress.

Przygotuj dostęp administratora i do plików, Shop ID, Publishable Key oraz zaimportowane rekordy ideal.house dla każdego wizualizowalnego SKU. Nadaj każdemu produktowi prostemu i każdemu obsługiwanemu wariantowi niepuste, unikalne SKU w WooCommerce.

Minimalny znacznik SDK#

To jest publiczny kontrakt SDK używany przez integrację:

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>

Kod wygenerowanego kontenera musi odpowiadać zaimportowanemu sku z katalogu. Nie umieszczaj ID bazy danych WooCommerce w data-product-code, chyba że celowo użyłeś tych ID jako SKU katalogu.

Załaduj SDK raz#

Dodaj ten kod do functions.php motywu potomnego lub pluginu specyficznego dla witryny. Zamień placeholdery.

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

Jeśli obsługujesz wersje WooCommerce na WordPress przed 6.3, przekaż true jako ostatni argument enqueue i dodaj async w filtrze.

Wyrenderuj host strony produktu#

Poniższy hook umieszcza host po formularzu dodawania do koszyka. Produkty proste otrzymują swój SKU natychmiast. Produkty zmienne zaczynają puste; adapter przeglądarki wypełnia je, gdy wybrany zostanie kompletny wariant.

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

Potwierdź, że hook istnieje w Twoim szablonie produktu. Motyw, który zastępuje szablon WooCommerce lub blok kolekcji produktów, może wymagać integracji blokowej lub innego udokumentowanego hooka WooCommerce.

Synchronizuj wybrany wariant#

Dołączony formularz wariantów WooCommerce wywołuje zdarzenia cyklu życia wariantów jQuery. Dodaj lokalny plik, np. assets/js/idealhouse-woocommerce.js, załaduj go z zależnościami jquery i wc-add-to-cart-variation i użyj:

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

Ten plik to adapter WooCommerce należący do klienta. Jeśli plugin wariantów zastępuje standardowy skrypt formularza, użyj udokumentowanego wywołania zwrotnego wyboru tego pluginu, zamiast zakładać, że te zdarzenia nadal się wywołują. Nie aktualizuj tylko atrybutu kontenera już przetworzonego przez SDK; zamień go na czysty kontener.

Siatki produktów, szybki podgląd i nawigacja AJAX#

Dla kart katalogu użyj hooka pętli produktów, np. woocommerce_after_shop_loop_item i wyrenderuj SKU produktu prostego. Produkty zmienne w siatce zwykle nie mają rozstrzygniętego wariantu; linkuj do strony produktu lub zbuduj jawny adapter wybory wariantów.

Pluginy szybkiego podglądu i bloki WooCommerce mogą wstrzykiwać produkty po początkowym załadowaniu strony. Umieść host w szablonie, który renderują, i uruchom swój most render() z udokumentowanego wywołania zwrotnego zakończenia tego narzędzia. Jeśli nie ma stabilnego wywołania zwrotnego, zakresowy MutationObserver może wykrywać nowe węzły .idealhouse-host, ale klient ponosi odpowiedzialność za jego wydajność i cykl życia.

Mapowanie i import katalogu#

Zmapuj WC_Product::get_sku() i każdy WC_Product_Variation::get_sku() do ideal.house sku. Produkty nadrzędne i podrzędne nie powinny współdzielić kodu, jeśli reprezentują różne zasoby wizualne.

WooCommerce nie automatycznie wysyła zmian katalogu do ideal.house. Użyj Przesyłanie produktów i jego przewodników dla import, status zadania, wyświetlanie listy, aktualizacje, usuwanie i obsługa ponownych prób. Każdy zaplanowany eksport lub most webhook to implementacja klienta.

Zweryfikuj przed wdrożeniem#

Przetestuj jeden produkt prosty, jeden produkt zmienny, jeden brakujący SKU i jeden SKU nieobecny w ideal.house.
Potwierdź, że SDK jest żądany raz, a jego znacznik skryptu zachowuje oba atrybuty danych uwierzytelniających.
Wybierz każdy wariant i zweryfikuj, że data-product-code jest równy SKU wariantu.
Zresetuj formularz wariantów; stary kontener powinien zniknąć.
Przetestuj siatkę produktów, szybki podgląd, filtry AJAX, fragmenty koszyka, mobilny przyklejony dodawanie do koszyka oraz cofanie/awansowanie w przeglądarce, gdzie to dotyczy.
Przetestuj podczas bycia zalogowanym, z kontrolami zgody i włączonym cache produkcyjnym.
Sprawdź, że Client Secret nie pojawia się w HTML, JavaScript, logach ani mapach źródeł.

Usuń integrację#

Usuń hooki/filtry PHP i lokalny adapter wariantów. Usuń hosty z nadpisanych szablonów lub bloków, wyczyść transiente WooCommerce i cache stron/CDN, a następnie potwierdź, że nie pozostaje żadne żądanie SDK ani element data-idealhouse-*.