Ideal House
Przejdź do treści

integracja Ecwid#

Użyj niestandardowej aplikacji witryny sklepu Ecwid i udokumentowanego cyklu życia Storefront JS API, aby dodać kontrolki Room Visualizer do stron produktów Ecwid.

Status weryfikacji: Dokumentacja API witryny sklepu w JS dla Ecwid została sprawdzona 7 września 2026. Nie było dostępnej aplikacji Ecwid ani testowego sklepu sprzedawcy. Przed wdrożeniem sprawdź dokładne pola danych zdarzenia strony w aktualnej dokumentacji OnPageLoaded.

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 obsługiwana ścieżka#

Ecwid wymaga niestandardowej aplikacji z samodzielnie hostowanym plikiem JavaScript w celu trwałej niestandardowej konfiguracji witryny sklepu. Przygotuj sklep/aplikację deweloperską Ecwid, plik adaptera hostowany przez HTTPS, Shop ID, Publishable Key oraz zaimportowane kody SKU produktów/wariantów.

Jeśli Ecwid jest osadzony w innym CMS, niestandardowa aplikacja witryny sklepu pozostaje niezawodnym miejscem na kod, ponieważ działa z witryną sklepu Ecwid. Skrypt strony nadrzędnej może nie współdzielić tego samego cyklu życia ani dokumentu w każdym trybie osadzania.

Minimalna umowa 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>

Użyj dokładnego Ecwid SKU, który zaimportowałeś jako ideal.house sku.

Inicjalizuj swoją aplikację witryny sklepu Ecwid#

Postępuj zgodnie z szybkim startem niestandardowej witryny sklepu Ecwid, aby zarejestrować samodzielnie hostowany plik. Uruchom go z udokumentowanym wywołaniem zwrotnym gotowości API, a następnie załaduj ideal.house SDK raz:

js
Ecwid.OnAPILoaded.add(function () {
  if (document.querySelector('script[src="https://sdk.ideal.house/sdk.js"]')) return;

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

W przypadku aplikacji wielosklepowej pobierz dwie publiczne wartości ideal.house z bezpiecznej publicznej konfiguracji aplikacji. Nigdy nie umieszczaj w tym pliku sekretu aplikacji Ecwid, tokenu dostępu ani ideal.house Client Secret.

Renderowanie na stronach produktów#

Ecwid dokumentuje Ecwid.OnPageLoaded.add() i dostarcza informacje o stronie do jego wywołania zwrotnego. Użyj bieżącego odwołania API, aby potwierdzić typ i identyfikator strony produktu, pobierz lub odczytaj dane produktu przez obsługiwany interfejs kliencki Ecwid, a następnie przekaż rozwiązany SKU do:

js
function mountIdealhouse(host, sku) {
  host.replaceChildren();
  const code = String(sku || '').trim();
  if (!code) return;

  const container = document.createElement('div');
  container.dataset.idealhouseButtonContainer = '';
  container.dataset.productCode = code;
  host.append(container);
}

Wstaw host w stabilne miejsce szczegółów produktu po zakończeniu renderowania strony przez Ecwid. Usuń poprzedni host, gdy typ strony się zmieni. Selektor DOM i wyszukiwanie produktu z obciążenia strony to kod adaptera klienta, ponieważ układy witryny sklepu i wersje obciążenia Ecwid mogą się zmieniać.

Opcje i nawigacja#

Gdy kupujący wybiera opcje produktu, poczekaj, aż Ecwid ustali wariant dostępny do zakupu i jego SKU. Wywołaj mountIdealhouse() z tym SKU albo wyczyść kontener zewnętrzny, jeśli wybór jest niekompletny. Nie twórz kodu przez łączenie etykiet opcji.

Ecwid to witryna sklepu typu single-page. Użyj jej udokumentowanego cyklu życia strony (wywołania zwrotne OnPageLoaded/zmiany strony), zamiast nasłuchiwać wyłącznie DOMContentLoaded przeglądarki. Nawigacja kategorii/wyszukiwania, przyciski Wstecz/Dalej w przeglądarce, osadzone widgety i okna dialogowe produktów muszą usuwać przestarzałe hosty produktów i montować nowy kontener po renderowaniu.

Import produktów#

Eksportuj pola produktów i wariantów SKU Ecwid i zmapuj je na ideal.house sku. Użyj Przesyłanie produktów, w tym import produktów, status zadania, lista produktów, aktualizacja produktów, usuwanie produktu oraz błędy i ponowienia.

Każdy eksport Ecwid REST API, webhook, instalacja OAuth lub cykliczna synchronizacja należy do klienta i musi być zaimplementowana po stronie serwera z odpowiednim uprawnieniem Ecwid.

Weryfikacja i usuwanie#

Przetestuj instalację aplikacji, inicjalizację API, przejścia produkt/kategoria/wyszukiwanie, każdy wariant, brakujące i nieznane kody SKU, przyciski Wstecz/Dalej w przeglądarce, widget Ecwid osadzony na innej stronie, układ mobilny, zgodę oraz klientów zalogowanych i wylogowanych. Potwierdź jedno żądanie SDK w dokumencie zawierającym host i dokładną równość SKU.

Aby usunąć, odłącz samodzielnie hostowany plik JavaScript od niestandardowej aplikacji lub odinstaluj aplikację, usuń wstrzyknięte hosty/wywołania zwrotne i zweryfikuj, czy SDK URL oraz wszystkie węzły data-idealhouse-* znikają po nawigacji w witrynie sklepu i twardym odświeżeniu.

Oficjalne referencje platformy#