Ideal House
콘텐츠로 이동

Adobe Commerce / Magento Open Source 연동#

Magento 모듈 또는 사용자 정의 테마로 Room Visualizer를 설치하고 표시된 단순 상품의 SKU를 ideal.house 카탈로그에 매핑하세요.

검증 상태: 2026년 9월 7일에 Adobe Commerce 프런트엔드 문서를 검토했습니다. 판매자 설치 환경은 사용할 수 없었습니다. Luma/Blank 테마, Hyvä 및 PWA Studio는 서로 다른 JavaScript 기술 구성을 사용합니다. 아래 구체적인 예제는 표준 RequireJS 스토어를 대상으로 합니다.

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

사전 준비 및 적용 범위#

개발 인스턴스, 사용자 정의 모듈 또는 자식 테마, 배포 권한, Shop ID, Publishable Key 및 가져온 테스트 SKU를 준비하세요. vendor/ 또는 기본 테마의 파일을 수정하지 마세요. Hyvä와 PWA Studio에는 각각의 Alpine/React 어댑터가 필요하며 RequireJS 코드를 그대로 복사해서는 안 됩니다.

최소 SDK 연동 규약#

html
<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>

상품 코드는 Magento의 숫자 엔터티 ID가 아닌 가져온 정확한 sku입니다.

상품 페이지 블록 추가#

catalog_product_view용 소규모 모듈 또는 테마 레이아웃 갱신을 만드세요. 상품 작업 영역 근처에 배치한 .phtml 템플릿을 블록이 가리키도록 설정하세요. 템플릿은 초기 상품 SKU를 안전하게 렌더링할 수 있습니다.

php
<?php
/** @var \Magento\Catalog\Block\Product\View $block */
$product = $block->getProduct();
$sku = $product ? trim((string) $product->getSku()) : '';
?>

<div class="idealhouse-host">
  <?php if ($sku !== ''): ?>
    <div
      data-idealhouse-button-container
      data-product-code="<?= $block->escapeHtmlAttr($sku) ?>"
    ></div>
  <?php endif; ?>
</div>

구성 가능 상품의 경우 페이지의 초기 SKU는 일반적으로 부모 SKU입니다. ideal.house 자산이 하위 단순 상품에 속한다면 마운트 요소를 처음에는 비워 두고 선택한 단순 상품이 확정된 후에만 채우세요.

SDK를 한 번만 불러오기#

모듈 또는 테마에 로컬 RequireJS 초기화 코드를 추가하세요. 초기화 코드는 외부 스크립트를 생성하고 필요한 모든 데이터 속성을 적용한 후 문서에 추가합니다.

js
define([], function () {
  'use strict';

  return function () {
    if (document.querySelector('script[src="https://sdk.ideal.house/sdk.js"]')) return;

    var 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.appendChild(script);
  };
});

Adobe가 권장하는 text/x-magento-init 방식에 따라 템플릿에서 선언적으로 초기화하세요.

html
<script type="text/x-magento-init">
{
  "*": {
    "Vendor_Module/js/idealhouse-loader": {}
  }
}
</script>

이 방식은 RequireJS URL에 인증 정보를 넣지 않고 최소 규약과 동일한 SDK 요소를 생성합니다. 스토어 코드에는 Publishable Key만 사용하세요.

선택한 구성 가능 상품의 SKU#

표준 구성 가능 상품 위젯은 Magento 자체 컴포넌트를 통해 선택 상태를 제공하지만 테마 재정의에 따라 형태가 달라집니다. 테마가 단순 상품 ID를 확정하는 지점에 모듈 내 RequireJS 믹스인 또는 리스너를 구현하고, 서버가 제공한 JSON에서 해당 ID를 SKU에 매핑한 다음 마운트 요소를 교체하세요.

js
function renderIdealhouseSku(host, sku) {
  host.replaceChildren();
  if (!sku || !sku.trim()) return;

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

믹스인과 ID-SKU 매핑 데이터는 고객 측 어댑터 구현에 해당합니다. 옵션 라벨로 하위 상품 SKU를 추론하지 마세요. 공개 SDK 규약에 포함되지 않은 ideal.house 이벤트나 메서드를 문서화하지 마세요.

동적 콘텐츠 및 캐시#

스와치 변경, AJAX로 불러온 추천 상품, 빠른 보기 또는 고객별 콘텐츠가 마운트 요소를 교체하면 컨테이너를 다시 만드세요. Magento의 contentUpdated 이벤트는 삽입된 콘텐츠의 Magento 컴포넌트를 초기화하지만, 그 자체로 선택한 SKU를 제공하지는 않습니다. 어댑터는 올바른 코드를 직접 확인하고 렌더링해야 합니다.

코드 변경 후 환경에 맞는 배포 절차를 실행하고 레이아웃/전체 페이지/블록 캐시를 비운 다음 정적 콘텐츠를 다시 배포하세요. 운영 번들링/압축 및 Varnish/CDN을 활성화한 상태에서 테스트하세요.

상품 데이터 가져오기#

단순 상품 및 하위 상품의 SKU를 ideal.house sku에 매핑하세요. 상품 업로드와 가져오기, 작업 상태, 목록 조회, 수정, 삭제, 재시도 안내를 사용하세요. Magento 내보내기, 관리 API 호출, cron 작업 및 웹훅은 고객 측 어댑터입니다.

검증 및 제거#

단순 상품, 구성 가능 상품, SKU 누락, 비활성 하위 상품 및 알 수 없는 SKU 사례를 테스트하세요. SDK 요청이 한 번만 실행되는지, 각 스와치/옵션 변경 후 SKU가 정확히 매핑되는지, 빠른 보기와 추천 상품이 올바르게 동작하는지 확인하세요. 모바일 레이아웃, 캐시 적중, 고객 그룹 페이지 및 동의 제어도 확인하세요. 소스 또는 정적 자산에 비밀 인증 정보가 나타나지 않는지 검증하세요.

제거하려면 사용자 정의 모듈을 비활성화/삭제하거나 자식 테마의 레이아웃/템플릿/RequireJS 파일을 제거하고 정적 콘텐츠를 다시 배포한 다음 캐시를 비우세요. SDK URL과 컨테이너가 없는지 확인하세요.

공식 플랫폼 참고 문서#