OpenCart 연동#

OpenCart 4 확장 또는 사용자 정의 테마로 Room Visualizer를 추가하고 안정적인 스토어 상품 코드를 ideal.house 카탈로그에 매핑하세요.

검증 상태: 2026년 9월 7일에 OpenCart 4 확장 문서를 검토했습니다. 테스트 스토어는 사용할 수 없었습니다. OpenCart 3 및 타사 테마는 경로와 이벤트 규칙이 다르므로 설치된 주 버전에 맞게 이 가이드를 조정하세요.

SDK를 불러오기 전에: Dashboard → Settings를 열고 **Allowed Origins (CORS)**에 스토어 출처를 추가한 다음 저장을 클릭하세요. 배포된 호스트 이름과 사용 중인 미리보기 또는 스테이징 출처를 포함하고, 여러 출처는 쉼표로 구분하세요. 설정 절차를 참고하세요.

사전 준비 및 코드 선택#

스테이징 스토어, 확장/테마 개발 권한, Shop ID, Publishable Key 및 가져온 테스트 레코드를 준비하세요. OpenCart 핵심 기능은 보통 상품 템플릿에 model을 제공하지만 SKU는 버전과 테마에 따라 컨트롤러/확장 작업이 필요할 수 있습니다. 값 하나를 선택하여 ideal.house sku로 일관되게 사용하세요.

핵심 카탈로그 파일을 직접 편집하지 마세요. 변경 사항을 OpenCart 4 확장으로 패키징하거나 버전 관리되는 사용자 정의 테마에 보관하세요.

최소 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>

상품 코드는 가져온 ideal.house sku와 한 글자도 다르지 않아야 합니다.

상품 컨테이너 렌더링#

확장을 통해 활성 상품 템플릿을 확장하세요. OpenCart model 필드를 ideal.house sku에 의도적으로 매핑했다면 상품 작업 영역 근처에 다음을 배치하세요.

twig

{% if model %}
  <div class="idealhouse-host">
    <div
      data-idealhouse-button-container
      data-product-code="{{ model }}">
    </div>
  </div>
{% endif %}

Twig 자동 이스케이프는 환경 설정에 따라 달라집니다. 선택한 값이 HTML 속성에 맞게 이스케이프되었는지 확인하세요. 실제 SKU 필드를 선택했다면 확장에서 검증된 값을 컨트롤러의 템플릿 데이터에 추가하고 model 대신 렌더링하세요.

SDK를 한 번만 불러오기#

확장/테마 메커니즘을 통해 스토어 JavaScript 자산을 추가하세요. 필수 속성이 있는 스크립트 하나를 생성해야 합니다.

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

두 공개 값을 확장 설정에 보관하고 안전하게 렌더링하세요. ideal.house Client Secret을 JavaScript, Twig, 확장 로그 또는 캐시된 HTML에 넣지 마세요.

선택 옵션, 상품 옵션 및 동적 렌더링#

OpenCart의 선택 옵션이 항상 SKU를 가진 상품 옵션과 일대일로 매핑되는 것은 아닙니다. 스토어가 선택 옵션/상품 옵션 확장을 사용한다면 해당 확장의 문서화된 옵션 확정 콜백 및 데이터 모델과 연동하세요. 정확한 선택 코드가 제공될 때만 마운트 요소를 교체하세요.

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

이는 고객 측 어댑터 코드입니다. 이 가이드에 모든 OpenCart 스토어에 공통으로 적용되는 상품 옵션 이벤트는 없습니다. AJAX 검색, 카테고리 필터, 팝업 및 빠른 보기에서는 확장 템플릿에 새 컨테이너를 렌더링하거나 문서화된 완료 콜백에서 연결 함수를 호출하세요. SDK가 생성한 하위 요소를 복사하지 마세요.

상품 가져오기#

시각화할 각 항목에서 선택한 OpenCart model/SKU를 내보내고 ideal.house sku에 매핑하세요. 상품 업로드를 사용한 다음 상품 가져오기, 작업 상태, 상품 목록 조회, 상품 수정, 상품 삭제 및 오류와 재시도를 따르세요.

OpenCart 관리 API 호출, 예약 내보내기, 이벤트 리스너 및 웹훅은 고객이 관리하는 연동 작업입니다.

검증 및 제거#

단순 상품, 지원하는 모든 옵션 조합, 누락 및 중복 코드, 알 수 없는 ideal.house SKU, 카테고리/검색 페이지, 빠른 보기, 브라우저 뒤로 가기/앞으로 가기, 모바일 레이아웃, 다중 스토어, 언어/통화, 동의 및 운영 캐시/압축을 테스트하세요. SDK 요청이 정확히 한 번 실행되고 코드가 정확히 일치하는지 확인하세요.

제거하려면 확장을 비활성화/삭제하거나 사용자 정의 테마 재정의 및 자산을 제거하고 OpenCart 수정 사항/이벤트를 갱신한 다음 테마/CDN 캐시를 비우세요. SDK 요청과 컨테이너가 없는지 검증하세요.