Shoplazza 연동#
테마 앱 확장 또는 사용자 정의 Liquid 테마로 Shoplazza에 Room Visualizer를 추가하고 선택한 상품 옵션의 SKU를 ideal.house 상품 코드로 렌더링하세요.
검증 상태: 2026년 9월 7일에 Shoplazza 테마, 확장, 상품 및 상품 옵션 문서를 검토했습니다. 파트너 앱 또는 판매자 테스트 스토어는 사용할 수 없었으므로 개발 스토어에서 설치 및 상품 옵션 전환을 검증해야 합니다.
SDK를 불러오기 전에: Dashboard → Settings를 열고 **Allowed Origins (CORS)**에 스토어 출처를 추가한 다음 저장을 클릭하세요. 배포된 호스트 이름과 사용 중인 미리보기 또는 스테이징 출처를 포함하고, 여러 출처는 쉼표로 구분하세요. 설정 절차를 참고하세요.
사전 준비#
Shoplazza 개발/판매자 스토어, 테마 또는 앱 확장 소스 접근 권한, Shop ID, Publishable Key 및 지원하는 상품 옵션 SKU의 가져온 레코드를 준비하세요. 사용자 정의 전에 판매자 테마를 복제하세요.
테마 앱 확장은 유지 관리 가능한 재사용 방식입니다. 앱 블록은 표시되는 UI를 삽입하며 판매자가 호환되는 상품 섹션에 추가해야 합니다. 앱 임베드는 전역 동작을 불러올 수 있습니다.
최소 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>
Shoplazza는 variant.sku를 문서화하고 있습니다. 이 문자열을 그대로 ideal.house sku로 사용하세요.
앱 블록 추가#
상품 섹션용 테마 확장 앱 블록을 만드세요. 상품 컨텍스트의 Shoplazza Liquid 블록은 product에 접근할 수 있습니다. 빈 마운트 요소로 시작한 다음 활성 테마의 상품 양식 상태로 선택한 상품 옵션을 제공하세요.
<div class="idealhouse-host"></div>
{% schema %}
{
"name": { "en-US": "Room Visualizer", "zh-CN": "房间可视化" },
"target": "section",
"javascript": ["idealhouse.js"],
"settings": []
}
{% endschema %}
옵션이 하나인 상품에서는 블록 JavaScript가 테마에서 안전하게 직렬화한 데이터의 product.variants에 있는 문서화된 유일한 항목을 읽을 수 있습니다. 옵션이 여러 개이면 테마의 기존 상품 양식이 선택을 확정할 때까지 마운트 요소를 비워 두세요. 이렇게 하면 문서화되지 않은 선택 상품 옵션 Liquid 속성에 의존하지 않을 수 있습니다.
SDK 불러오기#
idealhouse.js에서 SDK를 한 번만 불러오세요. 재사용 가능한 앱에서는 판매자 하나를 하드코딩하지 말고 검증된 공개 블록/임베드 설정으로 Shop ID와 Publishable Key를 제공하세요.
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을 노출하지 마세요.
선택한 상품 옵션 동기화 유지#
테마의 문서화된 상품 양식 콜백을 이 어댑터에 연결하세요.
function renderIdealhouseVariant(host, variant) {
host.replaceChildren();
const code = String(variant && variant.sku || '').trim();
if (!code) return;
const container = document.createElement('div');
container.dataset.idealhouseButtonContainer = '';
container.dataset.productCode = code;
host.append(container);
}
Shoplazza의 상품 옵션 객체는 sku를 문서화하지만 테마마다 선택을 다르게 구현할 수 있습니다. 콜백 연결은 고객 측 어댑터 구현에 해당합니다. 새 선택 후 컨테이너를 다시 만드세요. SDK가 내용을 채운 마크업을 수정하는 것만으로 처리하지 마세요.
컬렉션 카드, 빠른 보기, 검색 필터 및 클라이언트 렌더링 섹션에서는 항목별 마운트 요소를 추가하고 테마의 문서화된 렌더링 콜백 후 연결 함수를 실행하세요. 카드에서 최종 상품 옵션을 알 수 없다면 버튼을 생략하거나 상품 페이지로 연결하세요.
상품 가져오기#
지원하는 모든 variant.sku를 내보내고 상품 업로드를 통해 ideal.house sku로 가져오세요. 상품 가져오기, 작업 상태, 상품 목록 조회, 상품 수정, 상품 삭제 및 오류와 재시도를 참고하세요.
관리 API 내보내기, 웹훅, 예약 동기화, OAuth 및 확장 배포는 고객이 구현해야 합니다.
검증 및 제거#
앱 블록 배치, 임베드 활성화, 옵션이 하나인 상품, 여러 옵션의 모든 선택, 빈/중복/알 수 없는 SKU, 컬렉션 카드, 빠른 보기, 필터, 브라우저 이력, 모바일, 현지화/통화, 동의 및 테마 미리보기/실제 운영 모드를 테스트하세요. SDK 요청이 한 번만 실행되고 상품 옵션의 SKU가 정확히 매핑되는지 확인하세요.
제거하려면 테마 앱 확장을 비활성화하고 삭제하거나 사용자 정의 Liquid/JavaScript를 제거하세요. 정리된 테마를 배포하고 스토어 캐시를 비운 다음 SDK와 모든 data-idealhouse-* 노드가 없는지 검증하세요.