Ecwid 연동#
Ecwid 사용자 정의 스토어 앱과 문서화된 스토어 JS API 생명주기를 사용하여 Ecwid 상품 페이지에 Room Visualizer 컨트롤을 추가하세요.
검증 상태: 2026년 9월 7일에 Ecwid 스토어 JS API 문서를 검토했습니다. Ecwid 앱 또는 판매자 테스트 스토어는 사용할 수 없었습니다. 배포 전에 현재
OnPageLoaded참조 문서에서 정확한 페이지 데이터 필드를 확인해야 합니다.
SDK를 불러오기 전에: Dashboard → Settings를 열고 **Allowed Origins (CORS)**에 스토어 출처를 추가한 다음 저장을 클릭하세요. 배포된 호스트 이름과 사용 중인 미리보기 또는 스테이징 출처를 포함하고, 여러 출처는 쉼표로 구분하세요. 설정 절차를 참고하세요.
사전 준비 및 지원 방식#
Ecwid 스토어 사용자 정의를 지속적으로 유지하려면 자체 호스팅 JavaScript 파일이 있는 사용자 정의 앱이 필요합니다. Ecwid 개발 스토어/앱, HTTPS로 호스팅되는 어댑터 파일, Shop ID, Publishable Key 및 가져온 상품/상품 옵션 SKU를 준비하세요.
Ecwid가 다른 CMS에 삽입되어 있어도 사용자 정의 스토어 앱은 Ecwid 스토어와 함께 실행되므로 코드를 넣기에 안정적인 위치입니다. 부모 페이지 스크립트가 모든 삽입 모드에서 동일한 생명주기나 문서를 공유하는 것은 아닙니다.
최소 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>
ideal.house sku로 가져온 Ecwid SKU를 정확히 사용하세요.
Ecwid 스토어 앱 초기화#
Ecwid의 사용자 정의 스토어 빠른 시작에 따라 자체 호스팅 파일을 등록하세요. 문서화된 API 준비 콜백으로 시작한 다음 ideal.house SDK를 한 번만 불러오세요.
Ecwid.OnAPILoaded.add(function () {
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);
});
다중 스토어 앱에서는 앱의 안전한 공개 설정으로부터 두 ideal.house 공개 값을 가져오세요. 이 파일에 Ecwid 앱 비밀 정보, 접근 토큰 또는 ideal.house Client Secret을 넣지 마세요.
상품 페이지에서 렌더링#
Ecwid는 Ecwid.OnPageLoaded.add()를 문서화하고 콜백에 페이지 정보를 제공합니다. 현재 API 참조 문서에서 상품 페이지 유형과 식별자를 확인하고 Ecwid가 지원하는 클라이언트 인터페이스로 상품 데이터를 가져오거나 읽은 다음 확정된 SKU를 다음 함수에 전달하세요.
function mountIdealhouse(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);
}
Ecwid가 페이지 렌더링을 완료한 후 안정적인 상품 상세 위치에 host를 삽입하세요. 페이지 유형이 바뀌면 이전 마운트 요소를 제거하세요. Ecwid 스토어 레이아웃과 데이터 형식 버전은 변경될 수 있으므로 DOM 선택자 및 페이지 데이터에서 상품을 조회하는 로직은 고객 측 어댑터 코드입니다.
상품 옵션 및 탐색#
고객이 상품 옵션을 선택하면 Ecwid가 구매 가능한 옵션과 해당 SKU를 확정할 때까지 기다리세요. 그 SKU로 mountIdealhouse()를 호출하거나 선택이 불완전하면 마운트 요소를 비우세요. 옵션 라벨을 이어 붙여 코드를 만들지 마세요.
Ecwid는 단일 페이지 스토어입니다. 브라우저 DOMContentLoaded만 수신하지 말고 문서화된 페이지 생명주기(OnPageLoaded/페이지 전환 콜백)를 사용하세요. 카테고리/검색 탐색, 브라우저 뒤로 가기/앞으로 가기, 삽입 위젯 및 상품 팝업은 이전 상품 마운트 요소를 제거하고 렌더링 후 새 컨테이너를 마운트해야 합니다.
상품 가져오기#
Ecwid 상품 및 상품 옵션 SKU 필드를 내보내고 ideal.house sku에 매핑하세요. 상품 업로드와 상품 가져오기, 작업 상태, 상품 목록 조회, 상품 수정, 상품 삭제, 오류와 재시도를 사용하세요.
Ecwid REST API 내보내기, 웹훅, OAuth 설치 또는 반복 동기화는 고객이 관리해야 하며 적절한 Ecwid 권한으로 서버 측에서 구현해야 합니다.
검증 및 제거#
앱 설치, API 초기화, 상품/카테고리/검색 전환, 모든 상품 옵션, 누락 및 알 수 없는 SKU, 브라우저 뒤로 가기/앞으로 가기, 다른 사이트에 삽입된 Ecwid 위젯, 모바일 레이아웃, 동의 및 로그인/로그아웃 고객을 테스트하세요. 마운트 요소가 있는 문서에서 SDK 요청이 한 번만 실행되고 SKU가 정확히 같은지 확인하세요.
제거하려면 사용자 정의 앱에서 자체 호스팅 JavaScript 파일을 분리하거나 앱을 삭제하고 삽입된 마운트 요소/리스너를 제거하세요. 스토어 탐색 및 강력 새로고침 후 SDK URL과 모든 data-idealhouse-* 노드가 사라지는지 확인하세요.