Ideal House
Przejdź do treści

Integracja Adobe Commerce / Magento Open Source#

Zainstaluj Room Visualizer za pomocą modułu Magento lub niestandardowego motywu i zmapuj wyświetlany SKU prostego produktu do katalogu ideal.house.

Status weryfikacji: Dokumentacja frontendowa Adobe Commerce sprawdzona w dniu 7 września 2026. Brak dostępnego instalacji handlowca. Motywy Luma/Blank, Hyvä i PWA Studio używają różnych stosów JavaScript; poniższy konkretny przykład dotyczy standardowej witryny sklepu RequireJS.

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.

Wymagania wstępne i zakres#

Przygotuj instancję deweloperską, niestandardowy moduł lub motyw podrzędny, dostęp do wdrożenia, Shop ID, Publishable Key oraz zaimportowane testowe SKUs. Nigdy nie modyfikuj plików pod vendor/ ani motywu bazowego. Hyvä i PWA Studio wymagają własnego adaptera Alpine/React i nie mogą ślepo kopiować kodu RequireJS.

Minimalny kontrakt SDK#

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>

Product Code to dokładny zaimportowany sku, a nie numeryczny ID encji od Magento.

Dodanie bloku strony produktu#

Utwórz mały moduł lub aktualizację układu motywu dla catalog_product_view. Wskaż blok do szablonu .phtml umieszczonego w pobliżu akcji produktu. Szablon może bezpiecznie renderować początkowy produkt SKU:

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>

W przypadku produktu konfigurowalnego początkowy SKU strony to zwykle SKU produktu nadrzędnego. Jeśli zasoby ideal.house należą do prostych produktów podrzędnych, początkowo pozostaw kontener zewnętrzny pusty i wypełnij go dopiero po ustaleniu wybranego produktu prostego.

Załaduj SDK tylko raz#

Dodaj lokalny inicjator RequireJS w swoim module lub motywie. Inicjator tworzy zewnętrzny skrypt i stosuje wszystkie wymagane atrybuty danych przed jego dołączeniem:

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

Zainicjuj go deklaratywnie z szablonu, zgodnie z zalecanym przez Adobe mechanizmem text/x-magento-init:

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

Daje to ten sam element SDK co w minimalnym kontrakcie, bez umieszczania danych uwierzytelniających w URL RequireJS. Używaj w kodzie witryny sklepu tylko Publishable Key.

Wybrany konfigurowalny SKU#

Standardowy widget produktu konfigurowalnego ujawnia stan wyboru przez własny komponent Magento, ale nadpisanie motywu zmienia jego kształt. Zaimplementuj miksin RequireJS lub nasłuchiwacza wewnątrz swojego modułu w punkcie, w którym motyw rozwiązuje ID prostego produktu, zmapuj to ID na jego SKU z dostarczonego przez serwer JSON i zastąp hosta:

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

Ten mixin oraz mapowanie ID na SKU klient musi zaimplementować w swoim adapterze. Nie wyprowadzaj SKU produktu podrzędnego z etykiet opcji ani nie opisuj zdarzeń lub metod ideal.house, których nie obejmuje publiczna specyfikacja SDK.

Treść dynamiczna i cache#

Utwórz kontener ponownie po zmianie próbki, załadowaniu rekomendacji przez AJAX, otwarciu szybkiego podglądu lub zastąpieniu kontenera zewnętrznego treścią dostosowaną do klienta. Zdarzenie contentUpdated w Magento inicjalizuje komponenty Magento we wstawionej treści, ale samo nie dostarcza wybranego SKU. Adapter nadal musi ustalić i wyrenderować właściwy kod.

Po zmianach kodu wykonaj kroki wdrożeniowe odpowiednie dla środowiska, wyczyść cache układu/całej strony/bloku i ponownie wdroż statyczną treść. Testuj z produkcyjnym pakowaniem/minifikacją i włączonym Varnish/CDN.

Import danych produktu#

Zmapuj SKUs prostych i podrzędnych produktów do sku od ideal.house. Użyj Przesyłanie produktów, w tym import, status zadania, wyświetlanie listy, aktualizacje, usuwanie oraz wytyczne ponownych prób. Eksporty Magento, wywołania API Admina, zadania cron i webhooks to adaptery klienta.

Weryfikacja i usuwanie#

Przetestuj przypadki: prosty, konfigurowalny, brakujący-SKU, nieaktywny-podrzędny i nieznany-SKU. Potwierdź pojedyncze żądanie SDK, dokładne mapowanie SKU po każdej zmianie próbki/opcji, czyste zachowanie w szybkim podglądzie i rekomendacjach, układ mobilny, trafienia cache, strony grup klientów i kontrolki zgody. Zweryfikuj, że żadne poufne dane uwierzytelniające nie pojawiają się w źródle ani w zasobach statycznych.

Aby usunąć, dezaktywuj/odinstaluj niestandardowy moduł lub usuń pliki układu/szablonu/RequireJS motywu podrzędnego, ponownie wdroż statyczną treść, wyczyść cache i zweryfikuj, że URL SDK i kontenery są nieobecne.

Oficjalne odniesienia platformy#