React / Next.js 연동#

React 또는 Next.js에서 ideal.house 브라우저 SDK를 직접 사용하세요. 이 가이드에는 별도의 ideal.house React npm 패키지가 없습니다.

검증 상태: 현재 대시보드 템플릿과 SDK 마크업을 비교 확인했으며 2026년 9월 7일에 React 및 Next.js 공식 생명주기/스크립트 문서를 검토했습니다. 고객 애플리케이션 또는 운영 인증 정보는 사용할 수 없었으므로 빌드한 애플리케이션의 전체 과정을 검증하세요.

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

사전 준비 및 적용 경계#

Shop ID, Publishable Key, 가져온 카탈로그 SKU 및 클라이언트에서 렌더링되는 상품/상품 옵션 값을 준비하세요. Publishable Key는 브라우저 마크업에 포함할 수 있습니다. Client Secret, AI API 키 및 비공개 상품 가져오기 인증 정보는 서버에 보관하세요.

SDK는 DOM 컨테이너를 찾아냅니다. 해당 노드의 마운트 시점은 React가 관리합니다. 현재 상품 옵션을 확정하고 SKU가 바뀔 때 컨테이너를 교체하는 것은 연동 코드에서 처리해야 합니다.

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

data-product-code는 ideal.house 카탈로그 sku와 정확히 같아야 합니다.

React 컴포넌트#

상품 코드가 바뀔 때마다 새 컨테이너를 마운트하세요. key는 SDK가 이미 내용을 채웠을 수 있는 컨테이너를 재사용하는 대신 React가 DOM 노드를 교체하도록 강제합니다.

type RoomVisualizerButtonProps = {
  productCode?: string | null;
};

export function RoomVisualizerButton({ productCode }: RoomVisualizerButtonProps) {
  const code = productCode?.trim();
  if (!code) return null;

  return (
    <div
      key={code}
      data-idealhouse-button-container
      data-product-code={code}
    />
  );
}

상품 제목, 경로 슬러그, 데이터베이스 ID 또는 옵션 라벨이 아닌 선택한 상품 옵션의 SKU를 전달하세요. 선택이 불완전하면 null을 렌더링하세요.

Next.js 앱 라우터 로더#

상품 페이지를 포함하는 가장 좁은 공유 레이아웃에 SDK를 한 번 배치하세요. Next.js는 일부 하이드레이션 이후 불러오는 스크립트에 afterInteractive를 사용하도록 문서화하고 있습니다.

import Script from 'next/script';

export function IdealhouseSdk() {
  return (
    <Script
      id="idealhouse-room-visualizer-sdk"
      src="https://sdk.ideal.house/sdk.js"
      strategy="afterInteractive"
      data-shop-id={process.env.NEXT_PUBLIC_IDEALHOUSE_SHOP_ID}
      data-publishable-key={process.env.NEXT_PUBLIC_IDEALHOUSE_PUBLISHABLE_KEY}
    />
  );
}

레이아웃에서 IdealhouseSdk를 한 번 렌더링하고 상품 옵션 선택을 관리하는 클라이언트 컴포넌트 안에서 RoomVisualizerButton을 렌더링하세요. NEXT_PUBLIC_ 접두사가 있는 값은 브라우저로 전달되므로 Shop ID와 Publishable Key에만 사용하세요.

페이지 라우터 또는 일반 React에서는 HTML 셸에 스크립트를 한 번 생성하거나 최상위 이펙트 하나를 사용하세요.

useEffect(() => {
  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);
}, []);

React 엄격 모드는 개발 중 추가 설정 주기를 의도적으로 실행하므로 중복 검사가 필요합니다. 개별 상품 컴포넌트가 언마운트될 때 공유 SDK 태그를 제거하지 마세요.

탐색, 목록 및 상품 옵션#

클라이언트 측 경로 변경은 레이아웃 스크립트를 다시 불러오지 않습니다. 동일한 SKU가 동시에 마운트된 여러 화면에 나타날 수 있다면 안정적인 경로 식별자와 SKU를 조합하여 각 상품 컨트롤의 키로 사용하세요. 그리드에서는 각 카드에 자체 SKU가 필요합니다. 무한 스크롤로 카드가 추가되면 React가 자연스럽게 새 컨테이너를 마운트합니다.

상품 옵션 선택 시 전자상거래 상태에서 selectedVariant.sku를 구해 productCode로 전달하세요. 문서화되지 않은 SDK 새로고침 메서드를 호출하지 마세요. 빠른 보기 서랍과 경로 전환에서는 이전 컴포넌트를 언마운트하여 처리된 DOM이 다음 상품에 남지 않도록 해야 합니다.

React 하이드레이션 불일치가 보고되면 서버 렌더링과 첫 클라이언트 렌더링이 일치하는지 확인하세요. 클라이언트의 전자상거래 상태가 SKU를 확정할 때까지 컨테이너를 렌더링하지 않아도 됩니다.

상품 데이터 가져오기#

전자상거래 백엔드의 기준 상품 옵션 SKU를 ideal.house sku에 매핑하세요. 상품 업로드를 사용한 다음 상품 가져오기, 작업 상태, 상품 목록 조회, 상품 수정, 상품 삭제 및 오류와 재시도를 참고하세요.

백엔드 카탈로그 조회, 웹훅, 예약 동기화 또는 실행 토큰 서비스는 애플리케이션 코드로 구현해야 하며 브라우저 SDK가 제공하지 않습니다.

검증 및 제거#

서버 렌더링/하이드레이션, 전체 로드, 클라이언트 탐색, 브라우저 뒤로 가기/앞으로 가기, 상품 옵션 변경, null/알 수 없는 SKU, 반복 카드, 빠른 보기, Suspense/로딩 상태, 모바일, 동의 제어 및 운영 빌드를 테스트하세요. SDK 요청이 한 번만 실행되고 DOM 상품 코드/SKU가 정확히 같은지 확인하세요. 빌드된 클라이언트 번들에 비밀 정보가 실수로 포함되지 않았는지 검사하세요.

제거하려면 공유 SDK 컴포넌트/태그와 모든 RoomVisualizerButton 사용을 삭제하고 두 공개 환경 변수를 제거한 다음 다시 빌드하세요. SDK URL 또는 data-idealhouse-* 마크업이 남아 있지 않은지 검증하세요.

공식 프레임워크 참고 문서#

• Next.js 스크립트 컴포넌트
• Next.js 클라이언트 컴포넌트
• React useEffect
• React 목록 키