Ideal House
Przejdź do treści

Integracja WordPress#

Dodaj ideal.house Room Visualizer do witryny WordPress, ładując jeden publiczny skrypt przeglądarki i renderując kontener, którego kod produktu odpowiada zaimportowanemu SKU z katalogu.

Status weryfikacji: Dokumentacja sprawdzona 7 września 2026. Ten przewodnik nie został zweryfikowany end-to-end w motywie klienta WordPress. Zweryfikuj go na kopii stagingowej swojej dokładnej wersji motywu i edytora stron przed publikacją.

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 obejmuje witryny treści WordPress, klasyczne motywy, motywy blokowe i edytory stron, które pozwalają dodać HTML. Jeśli witryna używa danych produktów WooCommerce, użyj przewodnika WooCommerce dla wyboru wariantów.

Przygotuj:

  • dostęp administratora oraz, dla trwałej metody, motyw potomny lub mały plugin specyficzny dla witryny;
  • Shop ID i Publishable Key z panelu ideal.house;
  • jeden produkt już zaimportowany do ideal.house z znanym sku;
  • stronę stagingową, na której można wyłączyć cache/minifikację podczas testów.

Publishable Key jest przeznaczony do znaczników przeglądarki. Nigdy nie umieszczaj klucza Client Secret ani AI API w WordPress HTML.

Potwierdź kontrakt SDK#

Najmniejsza obsługiwana instalacja to dokładnie jeden skrypt SDK i jeden kontener przycisku generowanego:

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 musi być równy sku z katalogu, włącznie z wielkością liter i interpunkcją. SDK jest właścicielem zawartości kontenera. WordPress nie dostarcza w tym przewodniku wtyczki ideal.house.

Zainstaluj skrypt w całej witrynie#

WordPress zaleca ładowanie skryptów front-end przez wp_enqueue_script(). Dodaj poniższy kod do functions.php motywu potomnego lub pluginu specyficznego dla witryny. Filtr dodaje dwa wymagane atrybuty danych do znacznika generowanego przez WordPress.

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

Zamień oba placeholdery. Wersje WordPress przed 6.3 nie akceptują formy tablicowej ostatniego argumentu wp_enqueue_script(); przekaż zamiast tego true i użyj filtra script_loader_tag, aby dodać również async.

Nie instaluj SDK ponownie w bloku kodu ani menedżerze tagów. W DevTools document.querySelectorAll('script[src="https://sdk.ideal.house/sdk.js"]').length powinno zwracać 1.

Umieść przycisk#

W edytorze bloków dodaj blok Własny HTML w miejscu, gdzie ma pojawić się przycisk:

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

Dla powtarzanych kart renderuj ten sam znacznik z szablonu motywu i uciekaj kod jako atrybut HTML:

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

Twój motyw lub plugin musi dostarczać $idealhouse_product_code. Nie używaj ID wpisu, sluga ani tytułu, chyba że ta dokładna wartość jest również zaimportowanym ideal.house sku.

Mapowanie produktów i wariantów#

Utwórz jawną tabelę mapowania przed wdrożeniem:

Wartość WordPressWartość ideal.houseZasada
pole niestandardowe, np. idealhouse_skuskudokładne dopasowanie ciągu
jedna strona bez wariantówjeden zaimportowany produktjeden kontener
element kolekcji edytora stronpole SKU poziomu elementunigdy nie używaj ponownie kodu całej kolekcji

Jeśli strona zmienia się między wariantami, adapter klienta musi ustawić nowe data-product-code. Wyczyść stary kontener przed wstawieniem nowego, aby przestarzały stan widoku nie mógł zostać ponownie użyty:

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

To kod adaptera klienta. Nie wywołuje nieudokumentowanej metody ideal.house ani nie wprowadza fikcyjnego zdarzenia WordPress; wywołuj go z udokumentowanego wywołania zwrotnego motywu lub edytora stron.

Dynamiczna nawigacja i cache#

Dla filtrów AJAX, nieskończonego przewijania, modalnych kart produktów lub przejść edytora stron, wstaw nowy kontener po tym, jak nowy węzeł produktu znajdzie się w DOM. Nie klonuj kontenera, który SDK już wypełnił. Jeśli Twoje narzędzie nie udostępnia stabilnego wywołania zwrotnego renderowania, dodaj kontener w jego szablonie elementu, aby każdy render tworzył czysty znacznik.

Po edycji motywu wyczyść cache WordPress, CDN i pluginów optymalizacji. Wyklucz https://sdk.ideal.house/sdk.js z opóźniania/odkładania, jeśli plugin wydajności usuwa jego atrybuty danych lub opóźnia go do czasu po interakcji.

Import danych katalogu#

Treści WordPress nie są synchronizowane automatycznie. Eksportuj wybrane pole niestandardowe jako sku i importuj pasujące rekordy przez Przesyłanie produktów. Kontynuuj z import produktów, status zadania, lista produktów, aktualizacja produktów, usuwanie produktu i błędy i ponowienia.

Zweryfikuj przed publikacją#

  1. Otwórz staging w prywatnym oknie przeglądarki, a nie w podglądzie edytora WordPress.
  2. Potwierdź, że żądanie SDK zwraca się pomyślnie i tylko raz.
  3. Zbadaj kontener i porównaj data-product-code znak po znaku z zaimportowanym sku.
  4. Potwierdź, że zaimportowany SKU wyświetla działający element sterowania wizualizatorem, a nieznany SKU nie powoduje wyświetlenia niedziałającej kontrolki.
  5. Przetestuj nawigację edytora stron, filtry, cofanie/awansowanie w przeglądarce, układ mobilny i ustawienia zgody.
  6. Wybierz każdy obsługiwany wariant i potwierdź, że kontener jest odtworzony z jego SKU.
  7. Sprawdź konsolę przeglądarki i przetestuj ponownie z włączonym cache/minifikacją.

Usuń integrację#

Usuń funkcję enqueue i filtr script_loader_tag, a następnie usuń każdy blok data-idealhouse-button-container lub fragment szablonu. Wyczyść wszystkie cache i zweryfikuj, że SDK URL nie istnieje w źródle strony ani w panelu Network.

Oficjalne referencje platformy#