WordPress 연동#

공개 브라우저 스크립트 하나를 불러오고 상품 코드가 가져온 카탈로그 SKU와 일치하는 컨테이너를 렌더링하여 WordPress 사이트에 ideal.house Room Visualizer를 추가하세요.

검증 상태: 2026년 9월 7일에 문서를 검토했습니다. 이 가이드는 고객의 WordPress 테마에서 전체 과정에 대한 검증을 받지 않았습니다. 배포 전에 실제 사용 중인 테마 및 페이지 빌더 버전의 스테이징 복사본에서 검증하세요.

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

적용 범위 및 사전 준비#

이 가이드는 WordPress 콘텐츠 사이트, 클래식 테마, 블록 테마 및 HTML을 추가할 수 있는 페이지 빌더를 다룹니다. 사이트에서 WooCommerce 상품 데이터를 사용한다면 상품 옵션 선택은 WooCommerce 가이드를 따르세요.

준비 사항:

• 관리자 권한과, 지속적으로 유지할 방식의 경우 자식 테마 또는 소규모 사이트 전용 플러그인;
• ideal.house 대시보드의 Shop ID 및 Publishable Key;
• ideal.house에 이미 가져왔으며 sku를 알고 있는 상품 하나;
• 테스트 중 캐시 및 압축을 비활성화할 수 있는 스테이징 페이지.

Publishable Key는 브라우저 마크업용입니다. Client Secret 또는 AI API 키를 WordPress HTML에 넣지 마세요.

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>

data-product-code는 대소문자와 문장 부호를 포함하여 카탈로그 sku와 같아야 합니다. 컨테이너 내부 콘텐츠는 SDK가 관리합니다. 이 가이드에서는 WordPress용 ideal.house 플러그인을 제공하지 않습니다.

사이트 전체에 스크립트 설치#

WordPress는 프런트엔드 스크립트를 wp_enqueue_script()로 불러오는 방식을 권장합니다. 다음 코드를 자식 테마의 functions.php 또는 사이트 전용 플러그인에 추가하세요. 이 필터는 WordPress가 생성하는 태그에 필수 데이터 속성 두 개를 추가합니다.

add_action('wp_enqueue_scripts', function () {
    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 이전 버전에서는 wp_enqueue_script()의 마지막 인수에 배열을 사용할 수 없습니다. 대신 true를 전달하고 script_loader_tag 필터로 async도 추가하세요.

코드 블록이나 태그 관리자에서 SDK를 다시 설치하지 마세요. 개발자 도구에서 document.querySelectorAll('script[src="https://sdk.ideal.house/sdk.js"]').length는 1을 반환해야 합니다.

버튼 배치#

블록 편집기에서 버튼을 표시할 위치에 사용자 정의 HTML 블록을 추가하세요.

<div data-idealhouse-button-container data-product-code="CHAIR-OAK-01"></div>

반복되는 카드는 테마 템플릿에서 동일한 마크업을 렌더링하고 코드를 HTML 속성에 맞게 이스케이프하세요.

<div
  data-idealhouse-button-container
  data-product-code="<?php echo esc_attr($idealhouse_product_code); ?>"
></div>

테마 또는 플러그인에서 $idealhouse_product_code를 제공해야 합니다. 가져온 ideal.house sku와 정확히 같은 값을 사용한 경우가 아니라면 게시물 ID, 슬러그 또는 제목을 사용하지 마세요.

상품 및 상품 옵션 매핑#

출시 전에 명시적인 매핑 표를 작성하세요.

페이지에서 상품 옵션을 전환한다면 고객 측 어댑터가 새 data-product-code를 설정해야 합니다. 이전 뷰어 상태가 재사용되지 않도록 새 컨테이너를 삽입하기 전에 이전 컨테이너를 비우세요.

function renderIdealhouseButton(host, sku) {
  host.replaceChildren();
  if (!sku) return;

  const container = document.createElement('div');
  container.dataset.idealhouseButtonContainer = '';
  container.dataset.productCode = sku.trim();
  host.append(container);
}

이는 고객이 구현하는 어댑터 코드입니다. 문서화되지 않은 ideal.house 메서드를 호출하거나 임의의 WordPress 이벤트를 만들지 않습니다. 테마 또는 페이지 빌더가 제공하는 문서화된 콜백에서 호출하세요.

동적 탐색 및 캐시#

AJAX 필터, 무한 스크롤, 모달 상품 카드 또는 페이지 빌더 전환에서는 새 상품 노드가 DOM에 들어간 후 새 컨테이너를 삽입하세요. SDK가 이미 내용을 채운 컨테이너를 복제하지 마세요. 도구에서 안정적인 렌더링 콜백을 제공하지 않으면 항목 템플릿에 컨테이너를 추가하여 매번 렌더링할 때 새로운 마크업이 생성되도록 하세요.

테마 수정 후 WordPress, CDN 및 최적화 플러그인의 캐시를 비우세요. 성능 플러그인이 스크립트 데이터 속성을 제거하거나 사용자 상호작용 이후로 실행을 미룬다면 https://sdk.ideal.house/sdk.js를 지연 로딩 및 실행 지연 재작성 대상에서 제외하세요.

카탈로그 데이터 가져오기#

WordPress 콘텐츠는 자동으로 동기화되지 않습니다. 선택한 사용자 정의 필드를 sku로 내보내고 상품 업로드를 통해 일치하는 레코드를 가져오세요. 이어서 상품 가져오기, 작업 상태, 상품 목록 조회, 상품 수정, 상품 삭제 및 오류와 재시도를 참고하세요.

배포 전 검증#

1. WordPress 편집기 미리보기가 아닌 비공개 브라우저 창에서 스테이징 사이트를 여세요.
2. SDK 요청이 한 번만 실행되고 정상적으로 응답하는지 확인하세요.
3. 컨테이너를 검사하고 data-product-code를 가져온 sku와 한 글자씩 비교하세요.
4. 가져온 SKU에는 사용 가능한 시각화 컨트롤이 표시되고, 알 수 없는 SKU에는 동작하지 않는 컨트롤이 표시되지 않는지 확인하세요.
5. 페이지 빌더 탐색, 필터, 브라우저 뒤로 가기/앞으로 가기, 모바일 레이아웃 및 동의 설정을 테스트하세요.
6. 지원하는 모든 상품 옵션을 선택하고 각 SKU로 컨테이너가 다시 생성되는지 확인하세요.
7. 브라우저 콘솔을 확인하고 캐시 및 압축을 다시 활성화한 상태로 테스트하세요.

연동 제거#

스크립트 등록 함수와 script_loader_tag 필터를 제거한 다음 모든 data-idealhouse-button-container 블록 또는 템플릿 조각을 삭제하세요. 모든 캐시를 비우고 페이지 소스와 네트워크 패널에 SDK URL이 없는지 확인하세요.

공식 플랫폼 참고 문서#

• WordPress 테마 핸드북: 자산 포함
• WordPress wp_enqueue_script() 참조
• WordPress 자식 테마