BigCommerce 연동#

SDK를 한 번만 불러오고 현재 상품 또는 상품 옵션의 SKU를 자동 버튼 생성용 컨테이너에 렌더링하여 BigCommerce Stencil 스토어에 Room Visualizer를 추가하세요.

검증 상태: 2026년 9월 7일에 BigCommerce 개발자 문서를 검토했습니다. 테스트 스토어는 사용할 수 없었습니다. Stencil과 Catalyst는 렌더링 및 탐색 방식이 다릅니다. 이 가이드는 실행 가능한 Stencil 연동 방식을 제공하며 Catalyst 스토어에는 프레임워크 어댑터 사용을 안내합니다.

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

스토어 연동 방식 선택#

Stencil: 스크립트 관리자 또는 스크립트 API로 로더를 설치한 다음 사용자 정의 테마 템플릿에 컨테이너를 추가하세요.
Catalyst: Catalyst React/Next.js 앱에 스크립트와 컴포넌트를 추가하세요. React / Next.js를 따르세요.
기존 Blueprint: 지원되는 스토어로 이전하거나 BigCommerce 개발자에게 안전한 삽입 지점을 확인하도록 요청하세요. 현재 스크립트 API 문서는 Blueprint를 별도로 다룹니다.

테마 편집 권한, 스테이징 테마/채널, ideal.house Shop ID 및 Publishable Key, ideal.house에 가져온 BigCommerce SKU 하나 이상이 필요합니다.

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

컨테이너의 상품 코드는 가져온 카탈로그 sku와 정확히 일치해야 합니다. 이 가이드는 ideal.house BigCommerce 앱이 있다고 가정하지 않습니다.

Stencil에 설치#

스토어 → 스크립트 관리자에서 해당 스토어/채널 및 상품 페이지용 푸터 스크립트를 만드세요. 브라우저에 노출해도 되는 인증 정보를 사용하여 예제의 SDK 스크립트 태그만 붙여 넣으세요. 스크립트 관리자는 채널을 구분하는 스크립트 API에 대응하는 제어판 기능입니다.

재사용 가능한 앱에는 BigCommerce의 스크립트 API를 대신 사용하세요. 해당 API 작업과 앱 OAuth 흐름은 연동 서비스에서 관리해야 하며, 접근 토큰을 스토어 코드에 노출하지 마세요.

SDK 태그가 하나만 있는지 확인하세요. templates/layout/base.html에도 중복으로 포함하지 마세요.

초기 상품 렌더링#

사용자 정의 Stencil 테마에서 해당 테마가 사용하는 상품 보기 부분 템플릿의 상품 양식 근처에 컨테이너를 추가하세요.

handlebars

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

정확한 부분 템플릿은 테마마다 다릅니다. Stencil CLI로 수정한 테마를 미리 확인하고, 생성된 스토어 HTML을 편집하는 대신 버전 관리되는 테마에 변경 사항을 보관하세요.

카드는 컨텍스트에서 가져온 상품의 정확한 SKU를 제공할 때만 컨테이너를 렌더링하세요. 옵션이 있는 상품은 카테고리 페이지에서 최종 상품 옵션의 SKU가 확정되지 않을 수 있습니다. 고객이 완전한 상품 옵션을 선택하지 않았다면 상품 페이지로 연결하세요.

상품 옵션 동기화#

Stencil 테마 JavaScript는 테마별 상품 상세 코드를 통해 상품 옵션 변경을 받습니다. 현재 테마가 최종 상품 옵션 응답을 확정하는 지점에 고객 측 어댑터를 추가하세요.

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

테마 콜백에서 확정된 상품 옵션의 SKU를 전달하세요. BigCommerce 테마는 기본 상품 상세 구현을 수정하거나 대체할 수 있으므로 이 가이드는 임의의 전역 옵션 변경 이벤트를 정의하지 않습니다. 새 컨테이너를 삽입하기 전에 이전 컨테이너를 제거하세요.

빠른 보기 및 동적 페이지#

빠른 보기, 패싯 검색, 페이지 나누기 및 클라이언트 측 탐색은 상품 DOM을 교체할 수 있습니다. 렌더링되는 각 템플릿에 새 컨테이너를 추가하고 테마의 문서화된 렌더링 콜백 후에 동일한 연결 함수를 호출하세요. SDK가 이미 내용을 채운 컨테이너를 복제하지 마세요.

Catalyst는 클라이언트 측 React 렌더링을 사용하며 Stencil Handlebars 컨텍스트가 없습니다. 앱 셸에서 SDK를 한 번만 불러오고 React/Next.js 가이드에 나온 대로 선택한 상품 옵션의 SKU를 시각화 컴포넌트의 키로 사용하세요.

상품 데이터 가져오기 및 매핑#

BigCommerce sku 값을 ideal.house sku에 매핑하세요. 상품 옵션에는 부모 상품 ID 대신 각 옵션의 SKU를 사용하세요. 브라우저 SDK는 BigCommerce 카탈로그 데이터를 동기화하지 않습니다.

공개된 가져오기 규약은 상품 업로드를 사용하고, 이어서 상품 가져오기, 작업 상태, 상품 목록 조회, 상품 수정, 상품 삭제 및 오류와 재시도를 확인하세요. BigCommerce API 내보내기, 웹훅 또는 예약 동기화는 고객이 운영하는 어댑터입니다.

검증 및 제거#

출시 전에 단순 상품, 모든 옵션 조합, SKU가 없는 상품 및 ideal.house에 없는 SKU를 테스트하세요. 상품 페이지, 카테고리 카드, 빠른 보기, 패싯 탐색, 브라우저 뒤로 가기/앞으로 가기, 모바일 레이아웃, 동의 동작 및 활성화된 각 스토어 채널을 확인하세요. 개발자 도구에서 SDK 요청이 한 번 성공하고 상품 코드/SKU가 정확히 일치하는지 검증하세요.

연동을 제거하려면 스크립트 관리자 항목 또는 스크립트 API 레코드를 삭제하고 모든 테마 컨테이너 마크업 및 어댑터 코드를 제거한 다음 정리된 테마를 배포하고 스토어/CDN 캐시를 비우세요. 모든 채널에서 SDK 요청이 없는지 확인하세요.