Integracja Shoplazza#
Dodaj Room Visualizer do Shoplazza za pomocą rozszerzenia aplikacji motywu lub niestandardowego motywu Liquid i wyrenderuj wybrany wariant SKU jako kod produktu ideal.house.
Status weryfikacji: Dokumentacja motywu, rozszerzenia, produktu i wariantu Shoplazza sprawdzona 7 września 2026. Brak dostępnego partnera aplikacji lub sklepu testowego handlowca, więc instalacja i przełączanie wariantów muszą zostać zwalidowane w sklepie deweloperskim.
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#
Przygotuj sklep deweloperski/handlowy Shoplazza, dostęp do kodu źródłowego motywu lub rozszerzenia aplikacji, Shop ID, Publishable Key oraz zaimportowane rekordy dla wspieranych SKU wariantów. Zduplikuj motyw handlowca przed dostosowaniem.
Rozszerzenie aplikacji motywu to utrzymywalna, wielokrotnie używana ścieżka. Blok aplikacji wstrzykuje widoczny UI i musi zostać dodany przez handlowca do kompatybilnej sekcji produktu; osadzenie aplikacji może ładować zachowanie globalne.
Minimalna umowa SDK#
<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>
Shoplazza dokumentuje variant.sku; użyj tego dokładnego ciągu jako ideal.house sku.
Dodaj blok aplikacji#
Utwórz blok aplikacji rozszerzenia motywu dla sekcji produktu. Bloki Shoplazza Liquid w kontekście produktu mogą uzyskać dostęp do product. Zacznij od pustego hosta, a następnie użyj stanu formularza produktu aktywnego motywu, aby dostarczyć wybrany wariant:
<div class="idealhouse-host"></div>
{% schema %}
{
"name": { "en-US": "Room Visualizer", "zh-CN": "房间可视化" },
"target": "section",
"javascript": ["idealhouse.js"],
"settings": []
}
{% endschema %}
Dla produktu z pojedynczym wariantem, blok JavaScript może odczytać jedyny udokumentowany wpis w product.variants z danych bezpiecznie zserializowanych przez motyw. Dla wielu wariantów, pozostaw hosta pusty, dopóki istniejący formularz produktu motywu nie rozwiąże wyboru. Pozwala to uniknąć polegania na niedokumentowanej właściwości wybranego wariantu Liquid.
Załaduj SDK#
W idealhouse.js załaduj SDK tylko raz. Dla wielokrotnie używanej aplikacji, dostarcz Shop ID i Publishable Key przez zdezynfekowaną publiczną konfigurację bloku/osadzenia, zamiast hardkodować jednego handlowca:
if (!document.querySelector('script[src="https://sdk.ideal.house/sdk.js"]')) {
const 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.append(script);
}
Nigdy nie eksponuj sekretu aplikacji ani ideal.house Client Secret.
Utrzymuj synchronizację wybranego wariantu#
Podłącz udokumentowane wywołanie zwrotne formularza produktu motywu do tego adaptera:
function renderIdealhouseVariant(host, variant) {
host.replaceChildren();
const code = String(variant && variant.sku || '').trim();
if (!code) return;
const container = document.createElement('div');
container.dataset.idealhouseButtonContainer = '';
container.dataset.productCode = code;
host.append(container);
}
Obiekt wariantu Shoplazza dokumentuje sku, ale motywy mogą implementować wybór w różny sposób. Podłączenie wywołania zwrotnego to praca adaptera klienta. Ponownie utwórz kontener po nowym wyborze; nie modyfikuj tylko znaczników wypełnionych przez SDK.
Dla kart kolekcji, podglądu szybkiego, filtrów wyszukiwania i sekcji renderowanych po stronie klienta, dodaj hosta na poziomie przedmiotu i uruchom most po udokumentowanym wywołaniu zwrotnym renderowania motywu. Jeśli ostateczny wariant nie jest znany na karcie, pomiń przycisk lub link do strony produktu.
Import produktów#
Eksportuj każde wspierane variant.sku i importuj je jako ideal.house sku przez Przesyłanie produktów. Zobacz import produktów, status zadania, lista produktów, aktualizacja produktów, usuwanie produktu oraz błędy i ponowienia.
Eksporty Admin API, webhooks, zaplanowana synchronizacja, OAuth i dystrybucja rozszerzeń to implementacja klienta.
Weryfikacja i usunięcie#
Przetestuj umieszczenie bloku aplikacji, włączanie osadzenia, produkt z pojedynczym wariantem, wszystkie wybory wielowariantowe, puste/zduplikowane/nieznane SKUs, karty kolekcji, podgląd szybki, filtry, historię przeglądarki, mobilny, lokalizację/walutę, zgodę i tryby podglądu/live motywu. Potwierdź jedno żądanie SDK i dokładne mapowanie wariantu SKU.
Aby usunąć, dezaktywuj i odinstaluj rozszerzenie aplikacji motywu lub usuń niestandardowe Liquid/JavaScript, opublikuj czysty motyw, wyczyść cache witryny sklepu i zweryfikuj, że SDK i wszystkie węzły data-idealhouse-* są nieobecne.