Ideal House
Przejdź do treści

Integracja SHOPLINE#

Zintegruj Room Visualizer ze sklepem online SHOPLINE za pomocą rozszerzenia aplikacji motywu lub kontrolowanego bloku niestandardowego motywu.

Status weryfikacji: Dokumentacja motywu SHOPLINE Online Store 2.x/3.0 sprawdzona 7 września 2026. Brak dostępnego partnera aplikacji lub sklepu testowego handlowca. Składnia szablonów i wspierane typy rozszerzeń różnią się w zależności od generacji Online Store, więc zwaliduj w stosunku do dokładnej wersji sklepu.

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 powierzchnię integracji#

  • W przypadku wielokrotnie używanej publicznej aplikacji w Online Store 2.0/2.1, SHOPLINE zaleca rozszerzenie aplikacji motywu z blokiem aplikacji i opcjonalnym blokiem osadzenia aplikacji.
  • Motywy Online Store 3.0 zapewniają wielokrotnie używane bloki z opcjonalnymi zasobami JavaScript i blokami aplikacji.
  • API Script Tag/Asset są legacy lub zależne od wersji/typu aplikacji; nie wybieraj ich bez sprawdzenia tabeli kompatybilności SHOPLINE.
  • W przypadku dostosowania motywu dla jednego sklepu użyj struktury bloków/szablonów i zasobów aktywnej wersji.

Przygotuj sklep deweloperski, dostęp do rozszerzenia/motywu, Shop ID, Publishable Key oraz zaimportowane kody wariantów.

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>

Kod produktu musi odpowiadać sku katalogu ideal.house. Ta dokumentacja nie twierdzi, że istnieje instalowalna aplikacja ideal.house SHOPLINE.

Zbuduj blok motywu#

Utwórz blok aplikacji lub publiczny blok motywu, który renderuje kontener zewnętrzny na stronach szczegółów produktu. Użyj dokładnego obiektu produktu lub wariantu oraz funkcji bezpiecznego kodowania znaków opisanych dla danej generacji sklepu internetowego. Końcowy HTML witryny sklepu musi wyglądać następująco:

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

W źródle szablonu zastąp CHAIR-OAK-01 wyrażeniem bieżącego wybranego wariantu SKU/kodu. Nie wklejaj wyrażenia Shopify Liquid do szablonów Handlebars SHOPLINE 3.0; są to różne języki i kontrakty obiektów.

Dla bloku aplikacji dodaj go do sekcji produktu w edytorze motywu. Dla osadzenia aplikacji użyj go do załadowania SDK globalnie bez widocznego UI. Bloki aplikacji zwykle wymagają, aby handlowiec włączył je/umieścił je po instalacji.

Załaduj SDK tylko raz#

W zasobie JavaScript rozszerzenia/motywu utwórz skrypt z dwiema publicznymi ustawieniami przed jego dodaniem:

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

Używaj konfiguracji rozszerzenia/parametrów dynamicznych dla danych uwierzytelniających wielu handlowców. Eksponuj tylko Publishable Key; trzymaj sekrety aplikacji na swoim serwerze.

Wybrane warianty i sekcje dynamiczne#

Podłącz udokumentowane wywołanie zwrotne wyboru produktu aktywnego motywu do adaptera klienta:

js
function setIdealhouseVariant(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);
}

Motywy SHOPLINE są konfigurowalne, więc ten przewodnik nie wymyśla uniwersalnego zdarzenia wariantu witryny sklepu. Online Store 3.0 dokumentuje zdarzenia sekcji/bloków edytora motywu, ale są to zdarzenia cyklu życia edytora, a nie zdarzenia wyboru wariantu przez kupującego.

Gdy sekcje, filtry, paginacja, podgląd szybki lub podgląd edytora motywu ponownie renderują węzeł produktu, utwórz nowy kontener. Wyczyść nasłuchiwacze, gdy blok się wyładuje w edytorze motywu. Przyciski kart produktów wymagają SKU na poziomie przedmiotu; pomiń kontrolkę, gdy ostateczny wariant nie jest znany.

Import produktów#

Eksportuj dane produktów i wariantów SHOPLINE i zmapuj wybrany kod witryny sklepu do ideal.house sku. Użyj Przesyłanie produktów i zatwierdzonych przewodników dla import, status zadania, wyświetlanie listy, aktualizacje, usuwanie i obsługa ponownych prób.

Synchronizacja Admin API SHOPLINE, webhooks, OAuth aplikacji i dystrybucja w sklepie z aplikacjami to praca adaptera klienta.

Weryfikacja i usunięcie#

Przetestuj instalację i włączanie bloku przez handlowca, prosty produkt, każdy wariant, brakujące/nieznane kody, karty, podgląd szybki, filtry, nawigację w stylu SPA, mobilny, zgodę, podgląd edytora motywu i każdą wspieraną wersję Online Store. Potwierdź jedno żądanie SDK i dokładne mapowanie kodu/SKU.

Aby usunąć, dezaktywuj blok/osadzenie aplikacji i odinstaluj rozszerzenie lub usuń niestandardowy blok i zasób. Opublikuj czysty motyw, wyczyść cache i zweryfikuj, że nie pozostaje znacznik SDK URL ani data-idealhouse-*.

Oficjalne referencje platformy#