WooCommerce 연동#

WooCommerce 상품 페이지에 Room Visualizer 버튼을 추가하고 ideal.house 상품 코드를 선택한 상품 옵션의 SKU와 동기화하세요.

검증 상태: 2026년 9월 7일에 문서 및 WooCommerce의 공개 동작을 검토했습니다. 이 구현은 고객 스토어에서 검증을 받지 않았습니다. 클래식 템플릿, 블록 테마, 상품 옵션 확장 및 빠른 보기 플러그인은 서로 다른 DOM을 렌더링할 수 있으므로 실제 구성과 동일한 스테이징 환경에서 테스트하세요.

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

적용 범위 및 사전 준비#

이 가이드는 WordPress에서 실행되는 WooCommerce를 대상으로 합니다. 소규모 사이트 전용 플러그인 또는 자식 테마, 표준 WordPress 자산 로더 및 WooCommerce 상품 훅을 사용합니다. 설치 가능한 ideal.house WordPress 플러그인은 아닙니다.

관리자 및 파일 접근 권한, Shop ID, Publishable Key와 시각화할 각 SKU의 ideal.house 레코드를 준비하세요. WooCommerce에서 모든 단순 상품과 지원하는 각 상품 옵션에 비어 있지 않은 고유 SKU를 지정하세요.

최소 SDK 마크업#

이 연동에서 사용하는 공개 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>

생성되는 컨테이너의 코드는 가져온 카탈로그 sku와 일치해야 합니다. 해당 ID를 카탈로그 SKU로 의도적으로 사용한 경우가 아니라면 data-product-code에 WooCommerce 데이터베이스 ID를 넣지 마세요.

SDK를 한 번만 불러오기#

자식 테마의 functions.php 또는 사이트 전용 플러그인에 이 코드를 추가하세요. 자리표시자를 교체하세요.

add_action('wp_enqueue_scripts', function () {
    if (!is_product() && !is_shop() && !is_product_category()) {
        return;
    }

    wp_enqueue_script(
        'idealhouse-room-visualizer',
        'https://sdk.ideal.house/sdk.js',
        array(),
        null,
        array('strategy' => 'async', 'in_footer' => true)
    );
});

add_filter('script_loader_tag', function ($tag, $handle) {
    if ($handle !== 'idealhouse-room-visualizer') return $tag;

    return str_replace(
        '<script ',
        '<script data-shop-id="<SHOP_ID>" data-publishable-key="<PUBLISHABLE_KEY>" ',
        $tag
    );
}, 10, 2);

WordPress 6.3 이전 버전에서 실행되는 WooCommerce를 지원한다면 마지막 스크립트 등록 인수로 true를 전달하고 필터에서 async를 추가하세요.

상품 페이지 마운트 요소 렌더링#

다음 훅은 장바구니 추가 양식 뒤에 마운트 요소를 배치합니다. 단순 상품에는 SKU가 즉시 설정됩니다. 옵션 상품은 비어 있는 상태로 시작하며, 완전한 상품 옵션이 선택되면 브라우저 어댑터가 내용을 채웁니다.

add_action('woocommerce_after_add_to_cart_form', function () {
    global $product;
    if (!$product instanceof WC_Product) return;

    $sku = $product->is_type('variable') ? '' : $product->get_sku();
    printf(
        '<div class="idealhouse-host" data-initial-sku="%1$s">%2$s</div>',
        esc_attr($sku),
        $sku ? '<div data-idealhouse-button-container data-product-code="' . esc_attr($sku) . '"></div>' : ''
    );
});

상품 템플릿에 해당 훅이 있는지 확인하세요. WooCommerce 템플릿 또는 상품 컬렉션 블록을 대체하는 테마는 블록 연동이나 다른 문서화된 WooCommerce 훅이 필요할 수 있습니다.

선택한 상품 옵션 동기화#

WooCommerce에 포함된 상품 옵션 양식은 jQuery 옵션 생명주기 이벤트를 발생시킵니다. assets/js/idealhouse-woocommerce.js와 같은 로컬 파일을 추가하고 jquery 및 wc-add-to-cart-variation 의존성을 지정하여 등록한 다음 아래 코드를 사용하세요.

(function ($) {
  function render(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);
  }

  $('.variations_form').each(function () {
    const form = $(this);
    const host = this.closest('.product')?.querySelector('.idealhouse-host');
    if (!host) return;

    form.on('found_variation', function (_event, variation) {
      render(host, variation && variation.sku);
    });
    form.on('reset_data hide_variation', function () {
      render(host, '');
    });
  });

  document.querySelectorAll('.idealhouse-host[data-initial-sku]').forEach(function (host) {
    render(host, host.dataset.initialSku);
  });
})(jQuery);

이 파일은 고객이 관리하는 WooCommerce 어댑터입니다. 상품 옵션 플러그인이 표준 양식 스크립트를 대체한다면 이 이벤트들이 계속 발생한다고 가정하지 말고 해당 플러그인에 문서화된 선택 콜백을 사용하세요. SDK가 이미 처리한 컨테이너는 속성만 갱신하지 말고 새로운 컨테이너로 교체하세요.

상품 그리드, 빠른 보기 및 AJAX 탐색#

카탈로그 카드에서는 woocommerce_after_shop_loop_item과 같은 상품 반복 훅을 사용하고 단순 상품의 SKU를 렌더링하세요. 그리드의 옵션 상품은 일반적으로 옵션이 확정되지 않은 상태이므로 상품 페이지로 연결하거나 명시적인 상품 옵션 선택기 어댑터를 구현하세요.

빠른 보기 플러그인과 WooCommerce 블록은 초기 페이지 로드 후 상품을 삽입할 수 있습니다. 해당 도구가 렌더링하는 템플릿에 마운트 요소를 넣고 문서화된 완료 콜백에서 render() 연결 함수를 실행하세요. 안정적인 콜백이 없으면 범위를 제한한 MutationObserver로 새 .idealhouse-host 노드를 감지할 수 있지만, 성능과 생명주기는 고객이 관리해야 합니다.

카탈로그 매핑 및 가져오기#

WC_Product::get_sku() 및 각 WC_Product_Variation::get_sku()를 ideal.house sku에 매핑하세요. 부모 상품과 하위 상품이 서로 다른 시각화 자산을 나타낸다면 코드를 공유해서는 안 됩니다.

WooCommerce는 카탈로그 변경 사항을 ideal.house로 자동 전송하지 않습니다. 상품 업로드와 가져오기, 작업 상태, 목록 조회, 수정, 삭제, 재시도 처리 가이드를 사용하세요. 예약 내보내기나 웹훅 연결은 고객이 구현해야 합니다.

출시 전 검증#

1. 단순 상품 하나, 옵션 상품 하나, SKU가 없는 상품 하나, ideal.house에 없는 SKU 하나를 테스트하세요.
2. SDK가 한 번만 요청되고 스크립트 태그에 두 인증 정보 속성이 유지되는지 확인하세요.
3. 각 상품 옵션을 선택하고 data-product-code가 해당 옵션의 SKU와 같은지 검증하세요.
4. 상품 옵션 양식을 초기화하세요. 이전 컨테이너가 사라져야 합니다.
5. 해당되는 경우 상품 그리드, 빠른 보기, AJAX 필터, 장바구니 조각, 모바일 고정 장바구니 추가 기능 및 브라우저 뒤로 가기/앞으로 가기를 테스트하세요.
6. 로그아웃 상태에서 동의 제어 및 운영 캐시를 활성화하고 테스트하세요.
7. HTML, JavaScript, 로그 또는 소스 맵에 Client Secret이 나타나지 않는지 확인하세요.

연동 제거#

PHP 훅/필터와 로컬 상품 옵션 어댑터 등록을 제거하세요. 재정의된 템플릿 또는 블록에서 마운트 요소를 삭제하고 WooCommerce 임시 데이터 및 페이지/CDN 캐시를 비운 다음 SDK 요청이나 data-idealhouse-* 요소가 남아 있지 않은지 확인하세요.

공식 플랫폼 참고 문서#

• WordPress 테마 핸드북: 자산 포함
• WooCommerce 확장 개발 모범 사례
• WooCommerce 템플릿 구조
• 핵심 상품 옵션 양식의 WooCommerce 옵션 상품 데이터