Integracja OpenCart#
Dodaj Room Visualizer za pomocą rozszerzenia OpenCart 4 lub niestandardowego motywu i zmapuj stabilny kod produktu witryny sklepu do katalogu ideal.house.
Status weryfikacji: Dokumentacja rozszerzenia OpenCart 4 sprawdzona 7 września 2026. Brak dostępnego sklepu testowego. OpenCart 3 i motywy stron trzecich używają różnych ścieżek i konwencji zdarzeń; dostosuj ten przewodnik do zainstalowanej wersji głównej.
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 wybór kodu#
Przygotuj sklep testowy, dostęp do rozwoju rozszerzenia/motywu, Shop ID, Publishable Key oraz zaimportowane rekordy testowe. Rdzeń OpenCart często udostępnia model w szablonach produktów, podczas gdy SKU może wymagać pracy nad kontrolerem/rozszerzeniem w zależności od wersji i motywu. Wybierz jedną wartość i używaj jej spójnie jako ideal.house sku.
Nie edytuj bezpośrednio plików katalogu rdzenia. Pakuj zmiany jako rozszerzenie OpenCart 4 lub trzymaj je w niestandardowym motywie kontrolowanym przez system wersji.
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>
Kod produktu musi być równy zaimportowanemu ideal.house sku znak po znaku.
Wyrenderuj kontener produktu#
Rozszerz aktywny szablon produktu za pomocą swojego rozszerzenia. Jeśli celowo mapujesz pole OpenCart model do ideal.house sku, umieść to w pobliżu akcji produktu:
{% if model %}
<div class="idealhouse-host">
<div
data-idealhouse-button-container
data-product-code="{{ model }}">
</div>
</div>
{% endif %}
Automatyczne ucieczki w Twig zależą od konfiguracji środowiska; upewnij się, że wybrana wartość jest ucieczką atrybutu HTML. Jeśli wybierzesz rzeczywiste pole SKU, dodaj tę zdezynfekowaną wartość do danych szablonu kontrolera w swoim rozszerzeniu i wyrenderuj ją zamiast model.
Załaduj SDK tylko raz#
Dodaj zasób JavaScript witryny sklepu za pomocą mechanizmu rozszerzenia/motywu. Powinien on utworzyć jeden skrypt z wymaganymi atrybutami:
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);
}
Przechowuj dwie publiczne wartości w konfiguracji rozszerzenia i renderuj je bezpiecznie. Nigdy nie umieszczaj ideal.house Client Secret w JavaScript, Twig, logach rozszerzenia lub zbuforowanym HTML.
Opcje, warianty i renderowanie dynamiczne#
Opcje OpenCart nie zawsze odpowiadają pojedynczym wariantom z własnym SKU. Jeśli sklep korzysta z rozszerzenia opcji lub wariantów, użyj jego udokumentowanego wywołania zwrotnego ustalającego wybrany wariant i jego modelu danych. Zastąp kontener zewnętrzny dopiero wtedy, gdy otrzymasz dokładny kod wybranego wariantu:
function renderIdealhouseCode(host, productCode) {
host.replaceChildren();
const code = String(productCode || '').trim();
if (!code) return;
const container = document.createElement('div');
container.dataset.idealhouseButtonContainer = '';
container.dataset.productCode = code;
host.append(container);
}
To jest kod adaptera klienta; w tym przewodniku nie ma uniwersalnego zdarzenia wariantu OpenCart. Dla wyszukiwania AJAX, filtrów kategorii, okien popup i podglądu szybkiego renderuj czyste kontenery w szablonach rozszerzenia lub wywołaj most z jego udokumentowanego wywołania zwrotnego zakończenia. Nigdy nie kopiuj elementów potomnych wytworzonych przez SDK.
Import produktów#
Eksportuj wybrany OpenCart model/SKU dla każdego wizualizowalnego przedmiotu i zmapuj go do ideal.house sku. Użyj Przesyłanie produktów, a następnie postępuj zgodnie z import produktów, status zadania, lista produktów, aktualizacja produktów, usuwanie produktu oraz błędy i ponowienia.
Wywołania Admin API OpenCart, zaplanowane eksporty, nasłuchiwacze zdarzeń i webhooks to praca integracyjna klienta.
Weryfikacja i usunięcie#
Przetestuj proste produkty, każdą wspieraną kombinację opcji, brakujące i zduplikowane kody, nieznane SKUs ideal.house, strony kategorii/wyszukiwania, podgląd szybki, nawigację wstecz/do przodu w przeglądarce, układ mobilny, wiele sklepów, języki/waluty, zgodę i cache/minifikację produkcyjną. Potwierdź dokładnie jedno żądanie SDK i dokładne dopasowanie kodu.
Aby usunąć, dezaktywuj/odinstaluj rozszerzenie lub usuń nadpisanie i zasób niestandardowego motywu, odśwież modyfikacje/zdarzenia OpenCart, wyczyść cache motywu/CDN i zweryfikuj, że żądanie SDK i kontenery są nieobecne.