Integracja BigCommerce#

Dodaj Room Visualizer do witryny sklepu Stencil w BigCommerce, ładując SDK tylko raz i renderując bieżący produkt lub wariant SKU do kontenera wygenerowanego przycisku.

Status weryfikacji: Dokumentacja developerska BigCommerce sprawdzona w dniu 7 września 2026. Brak dostępnego sklepu testowego. Stencil i Catalyst mają różne modele renderowania i nawigacji; ten przewodnik przedstawia praktyczną ścieżkę dla Stencil i kieruje witryny Catalyst do adaptera frameworka.

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.

Wybierz ścieżkę witryny sklepu#

Stencil: zainstaluj loader za pomocą Script Manager lub API Scripts, a następnie dodaj kontener w szablonie niestandardowego motywu.
Catalyst: dodaj skrypt i komponent w aplikacji React/Next.js Catalyst; postępuj zgodnie z instrukcją React / Next.js.
Legacy Blueprint: przenieś do wspieranej witryny sklepu lub poproś developera BigCommerce o wskazanie bezpiecznego punktu wstawienia. Bieżąca dokumentacja API Scripts traktuje Blueprint osobno.

Wymagany jest dostęp do edycji motywu, motyw/kanał staging, ideal.house Shop ID i Publishable Key oraz co najmniej jeden BigCommerce SKU zaimportowany do ideal.house.

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 kontenera musi dokładnie odpowiadać zaimportowanemu katalogowemu sku. Ten przewodnik nie zakłada aplikacji ideal.house BigCommerce.

Instalacja w Stencil#

W Witryna sklepu → Menedżer skryptów utwórz skrypt stopki dla właściwej witryny lub kanału i stron produktów. Wklej wyłącznie znacznik skryptu SDK z przykładu wraz z danymi bezpiecznymi do użycia w przeglądarce. Menedżer skryptów jest odpowiednikiem API skryptów obsługującego kanały, dostępnym w panelu administracyjnym.

W przypadku aplikacji wielokrotnego użytku użyj zamiast tego API Scripts od BigCommerce. Operacja API i przepływ OAuth aplikacji są odpowiedzialnością Twojej usługi integracyjnej; nie ujawniaj jej tokena dostępu w kodzie witryny sklepu.

Upewnij się, że istnieje tylko jeden znacznik SDK. Nie włączaj go również w templates/layout/base.html.

Renderowanie początkowego produktu#

W niestandardowym motywie Stencil dodaj kontener w pobliżu formularza produktu w części widoku produktu używanej przez Twój motyw:

handlebars

{{#if product.sku}}
  <div
    data-idealhouse-button-container
    data-product-code="{{product.sku}}"
  ></div>
{{/if}}

Dokładna część różni się w zależności od motywu. Użyj Stencil CLI, aby podglądać zmodyfikowany motyw i utrzymuj zmiany w motywie kontrolowanym przez system wersji, zamiast edytować generowany HTML witryny sklepu.

Dla kart renderuj kontener tylko wtedy, gdy kontekst karty ujawnia dokładny SKU, który zaimportowano. Produkt z opcjami może nie mieć końcowego wariantu SKU na stronie kategorii; linkuj do strony produktu, chyba że kupujący wybrał kompletny wariant.

Synchronizacja opcji produktu#

Kod JavaScript motywu Stencil otrzymuje zmiany opcji produktu przez specyficzny dla motywu kod product-details. Dodaj adapter klienta w miejscu, w którym bieżący motyw rozwiązał odpowiedź końcowej wariantu:

export function replaceIdealhouseContainer(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);
}

Przekaż SKU ustalonego wariantu z wywołania zwrotnego motywu. Motywy BigCommerce mogą dostosowywać lub zastępować domyślną implementację szczegółów produktu, dlatego ten przewodnik nie wymyśla globalnego zdarzenia zmiany opcji. Usuń stary kontener przed wstawieniem nowego.

Szybki podgląd i strony dynamiczne#

Szybki podgląd, wyszukiwanie fasetowe, paginacja i nawigacja po stronie klienta mogą zastąpić DOM produktu. Dodaj czysty kontener w każdym renderowanym szablonie i wywołaj ten sam mostek po udokumentowanym wywołaniu zwrotnym renderowania motywu. Nie klonuj kontenera już wypełnionego przez SDK.

Catalyst używa renderowania po stronie klienta w React i nie ma kontekstu Handlebars Stencil. Załaduj SDK raz w skorupie aplikacji i kluczuj komponent wizualizatora według wybranego wariantu SKU, jak pokazano w przewodniku React/Next.js.

Import i mapowanie danych produktu#

Zmapuj wartości sku od BigCommerce do sku od ideal.house; dla wariantów użyj każdego wariantu SKU, a nie ID produktu nadrzędnego. Dane katalogu BigCommerce nie są synchronizowane przez SDK przeglądarki.

Użyj Przesyłanie produktów dla zatwierdzonego kontraktu importu, a następnie sprawdź import produktów, status zadania, lista produktów, aktualizacja produktów, usuwanie produktu oraz błędy i ponowienia. Każdy eksport API od BigCommerce, webhook lub zaplanowana synchronizacja to adapter obsługiwany przez klienta.

Weryfikacja i usuwanie#

Przed uruchomieniem przetestuj prosty produkt, każdą kombinację opcji, produkt bez SKU oraz SKU brakujący w ideal.house. Sprawdź stronę produktu, karty kategorii, Szybki podgląd, nawigację fasetową, przyciski Wstecz/Dalej w przeglądarce, układ mobilny, zachowanie zgody oraz każdy aktywny kanał witryny sklepu. W DevTools zweryfikuj jedno pomyślne żądanie SDK i dokładne dopasowanie Product Code/SKU.

Aby usunąć integrację, usuń wpis w Script Manager lub rekord API Scripts, usuń wszystkie znaczniki kontenera motywu i kod adaptera, opublikuj czysty motyw, a następnie wyczyść cache witryny sklepu/CDN. Potwierdź, że żądanie SDK jest nieobecne we wszystkich kanałach.