설명서CommerceLive Search 안내서

검색 어댑터에서 PLP 위젯으로 마이그레이션

Last update: Thu Jan 29 2026 00:00:00 GMT+0000 (Coordinated Universal Time)

작성 대상:

  • 관리자

검색 어댑터는 ​ 4.0.0부터 ​사용되지 않음Live Search이며 보안 업데이트만 받습니다. PLP(제품 목록 페이지) 위젯은(는) 앞으로 모든 Live Search 구현에 대해 지원되는 솔루션입니다. 이 안내서는 마이그레이션이 간단한 경우와 추가 작업이 필요한 경우를 이해하는 데 도움이 됩니다.

사전 요구 사항

마이그레이션 프로세스를 시작하기 전에 환경이 이러한 요구 사항을 충족하는지 확인하십시오.

마이그레이션을 시작하기 전:

기술 요구 사항:

  • Adobe Commerce 2.4.4 이상
  • Live Search 확장이 설치되었습니다.
  • 명령줄 액세스(CLI).
  • Commerce 관리자 액세스 권한.
  • 테스트를 위한 스테이징 또는 QA 환경.

백업 및 준비:

  1. 데이터베이스와 코드를 백업합니다.
  2. 현재 사용자 지정을 문서화합니다.
  3. 경계 및 제한을 검토하여 PLP 위젯이 사용자의 요구 사항을 충족하는지 확인하십시오.
  4. 트래픽이 적은 기간 동안 마이그레이션을 예약합니다.
  5. 상점 행동에 대한 잠재적인 변경 사항을 이해 당사자에게 알립니다.

현재 구현 검토:

  • 현재 Live Search 버전을 확인하세요.
  • 사용 중인 패싯과 해당 구성을 문서화합니다.
  • 모든 검색 기능을 테스트하고 예상되는 동작을 문서화합니다.
  • 현재 검색 결과 프레젠테이션의 스크린샷을 캡처합니다.

버전 호환성:

  • Adobe Commerce 2.4.4 이상을 실행하고 있습니다.
  • Live Search 4.0.0 이상으로 업그레이드할 준비가 되었습니다.

마이그레이션 시나리오

간단한 마이그레이션(추가 작업 필요 없음)

구현이 다음 기준을 모두 충족하는 경우 PLP 위젯으로 직접 마이그레이션할 수 있습니다.

표준 Luma 기반 상점:

  • Luma 테마 또는 최소한의 사용자 지정으로 Luma에서 상속되는 테마를 사용합니다.
  • PLP 레이아웃 또는 템플릿에 대한 사용자 정의 수정을 수행하지 않았습니다.
  • 검색 결과와 상호 작용하는 사용자 지정 JavaScript 확장을 만들지 않았습니다.

표준 제품 카탈로그:

  • 모든 제품 속성은 표준 소스 모델을 사용합니다(사용자 지정 소스 모델이 아님).
  • 특수 렌더링 논리를 필요로 하는 사용자 지정 제품 유형은 없습니다.
  • 카탈로그는 표준 패싯과 필터링만 사용합니다.

표준 통합:

  • 분석에 Google 태그 관리자(GTM)를 사용하고 있지 않습니다.
  • 검색 동작을 수정하는 타사 확장을 사용하고 있지 않습니다.

구현이 이러한 기준에 일치하면 표준 마이그레이션 단계로 진행하십시오.

추가 작업이 필요한 마이그레이션

구현에 다음 중 하나가 있는 경우 추가 작업이 필요합니다.

사용자 지정 테마 수정:

  • Luma 템플릿을 오버라이드하는 사용자 정의 PLP 레이아웃입니다.
  • 검색 어댑터별 요소를 대상으로 하는 사용자 지정 CSS 또는 JavaScript.
  • PLP 또는 관련 파일에 대한 사용자 정의 템플릿 수정.
  • 테마는 Luma에서 상속하지 않습니다(예: 처음부터 사용자 지정 테마).

사용자 지정 제품 특성:

  • 사용자 지정 소스 모델이 패싯으로 사용되는 제품 속성입니다.
  • 특별 표시 요구 사항이 있는 사용자 정의 제품 유형입니다.
  • "is_user_defined": false을(를) 사용하는 프로그래밍 특성입니다.

고급 통합:

  • Google 태그 관리자(GTM)는 추적에 적극적으로 사용됩니다.
  • 서드파티 분석 또는 개인화 도구가 검색과 통합됩니다.
  • 사용자 지정 이벤트 추적 또는 데이터 레이어 구현.
  • 외부 검색 또는 추천 엔진과 통합.

헤드리스 또는 PWA 구현:

  • Headless 아키텍처(예: PWA Studio, Vue Storefront) 사용.
  • 사용자 지정 프론트엔드 프레임워크(React, Vue, Angular).
  • 카탈로그 쿼리에만 GraphQL 사용.
  • 사용자 지정 Storefront 이벤트 구현.

사용자 지정 위젯 코드:

  • 이전에 검색 어댑터 코드를 사용자 지정했습니다.
  • 자체 CDN에서 위젯의 사용자 정의 버전을 호스팅합니다.
  • 검색 기능을 위한 사용자 지정 JavaScript 확장.

구현에 이러한 시나리오가 있는 경우 복잡한 마이그레이션 시나리오를 참조하십시오.

표준 마이그레이션 단계

특별한 사용자 지정 사항이 없는 구현의 경우 다음 단계를 따르십시오.

1단계: Live Search 업그레이드

PLP 위젯에 액세스하려면 Live Search 확장을 버전 4.0 이상으로 업그레이드하십시오.

역할: 판매자 또는 파트너

  1. 현재 Live Search 버전 확인:

    code language-bash 
    composer show magento/live-search | grep version

  2. 버전 3.x 또는 이전 버전인 경우 업그레이드하기 전에 AdvancedSearch 모듈을 활성화합니다.

    code language-bash 
    bin/magento module:enable Magento_AdvancedSearch

  3. composer.json을(를) 업데이트하여 Live Search 4.0 이상 필요:

    code language-json 
    "require": {
   "magento/live-search": "^4.0"
}

  4. 업그레이드 실행:

    code language-bash 
    composer update magento/live-search --with-dependencies

  5. 설치 업그레이드 실행 및 다시 컴파일:

    code language-bash 
    bin/magento setup:upgrade
bin/magento setup:di:compile

  6. 필요한 경우 정적 콘텐츠를 배포합니다.

    code language-bash 
    bin/magento setup:static-content:deploy

2단계: PLP 위젯 활성화

Commerce 관리에서 PLP 위젯을 구성합니다.

역할: 판매자

PLP 위젯은 Live Search 4.0.0+의 새 설치에 대해 기본적으로 활성화됩니다. 이전 버전에서 업그레이드하는 경우:

  1. Stores > 설정 > Configuration(으)로 이동합니다.
  2. Live Search > Storefront Features(으)로 이동합니다.
  3. Storefront Features 섹션을 확장합니다.
  4. Enable Product Listing Widgets​을(를) 예(으)로 설정합니다.
  5. Save Config​을(를) 클릭합니다.
  6. 캐시를 플러시합니다. System > 도구 > Cache Management > Flush Magento Cache.

3단계: 스테이징 시 테스트

시작하기 전에 비프로덕션 환경에서 마이그레이션의 유효성을 검사하십시오.

역할: 판매자/파트너

프로덕션에 배포하기 전에 검색 기능을 철저히 테스트하십시오.

기능 테스트:

  • 검색 결과가 올바르게 표시되는지 확인합니다.
  • 구성된 모든 Facet을 테스트합니다.
  • 범주 탐색이 작동하는지 확인합니다.
  • 결과를 통해 페이지 매김을 테스트합니다.
  • 정렬 옵션이 예상대로 작동하는지 확인합니다.
  • 간단한 제품에 대한 장바구니 추가 기능을 테스트합니다.

시각적 테스트:

  • 제품 이미지가 올바르게 표시되는지 확인합니다.
  • 제품 이름과 가격이 올바르게 렌더링되는지 확인합니다.
  • 색상 견본 테스트(사용하는 경우).
  • 모바일 장치에서 응답형 동작을 확인합니다.
  • 스타일이 브랜드와 일치하는지 확인합니다.

성능 테스트:

  • 페이지 로드 시간 측정
  • 실제 카탈로그 크기로 테스트합니다.
  • 서버 리소스 사용을 모니터링합니다.
  • 브라우저 콘솔에서 JavaScript 오류를 확인합니다.

4단계: 프로덕션에 배포

검증된 구성을 라이브 스토어프론트로 이동합니다.

역할: 판매자/파트너

  1. 가능한 경우 유지 관리 기간 동안 배포를 예약합니다.
  2. 표준 배포 프로세스를 따릅니다.
  3. 2단계: PLP 위젯을 사용하도록 설정을 사용하여 프로덕션에서 PLP 위젯을 사용하도록 설정합니다.
  4. 배포 후 즉시 모든 문제를 모니터링합니다.
  5. 중요한 문제가 발생하면 롤백 계획을 준비하십시오.

5단계: 유효성 검사 및 모니터링

마이그레이션 후 검색 성능 및 고객 경험을 추적합니다.

역할: 판매자

배포 후 주요 지표를 모니터링합니다.

  • 결과 없음 검색률
  • Search-to-Cart 전환율
  • 페이지 로드 성능
  • 고객 피드백 또는 지원 티켓
  • 브라우저 콘솔의 JavaScript 오류

복잡한 마이그레이션 시나리오

다음 시나리오에서는 표준 마이그레이션 단계를 넘어 추가적인 계획 수립, 사용자 지정 개발 또는 전문 지원이 필요합니다.

레이아웃을 수정한 사용자 정의 테마

이 시나리오에는 기본 제품 목록 동작을 재정의하는 사용자 지정 템플릿 또는 레이아웃이 있습니다.

역할: 개발자/파트너

  1. 사용자 지정 감사:

    • 테마의 모든 사용자 지정 레이아웃 XML 파일을 문서화합니다.
    • 제품 목록 페이지 또는 관련 파일에 대한 사용자 지정 템플릿 수정 사항을 검토합니다.
    • 스타일링에 사용되는 사용자 지정 CSS 클래스를 식별합니다.
    • 사용자 지정 JavaScript 상호 작용을 문서화합니다.

  2. CSS 기반 사용자 지정으로 마이그레이션:

    • PLP 위젯은 특정 CSS 클래스를 사용합니다(PLP 스타일 가이드 참조).
    • PLP 위젯 CSS 클래스를 사용하여 시각적 맞춤화를 재생성합니다.
    • 사용자 정의 스타일이 올바르게 적용되는지 테스트합니다.

  3. 충돌하는 사용자 지정 제거:

    • 제품 목록 구조를 수정하는 레이아웃 XML을 제거합니다.
    • 검색 어댑터별 요소를 대상으로 하는 JavaScript을 정리합니다.
    • 위젯 렌더링과 충돌하는 템플릿 재정의를 업데이트합니다.

  4. 철저하게 테스트:

    • 모든 시각적 사용자 지정이 PLP 위젯에서 작동하는지 확인합니다.
    • 레이아웃 충돌이 없는지 확인합니다.
    • 모든 중단점 및 장치에서 테스트합니다.

사용자 정의 소스 모델이 있는 제품 속성

이 시나리오에서는 검색 어댑터에서 지원하지 않지만 PLP 위젯에서 지원하는 사용자 정의 소스 모델과 함께 제품 속성을 사용하는 패싯이 있습니다.

역할: 판매자(관리자 구성)

  1. 영향을 받는 특성 식별:

    • 패싯으로 사용되는 제품 속성을 검토하십시오.
    • 사용자 정의 소스 모델을 사용하는 사용자를 식별합니다.
    • 현재 Facet 구성을 문서화합니다.

  2. PLP 위젯 업그레이드 및 활성화:

  3. 패싯 다시 구성:

    • Marketing > SEO 및 검색 > Live Search(으)로 이동합니다.
    • 영향을 받는 속성에 대한 Facet 구성을 검토합니다.
    • 테스트 패싯이 사용자 지정 소스 모델에 올바르게 작동합니다.

  4. 유효성 검사:

    • 사용자 지정 소스 모델 패싯을 사용하여 필터링을 테스트합니다.
    • 모든 속성 값이 올바르게 표시되는지 확인합니다.
    • 성능이 적절한지 확인합니다.

Google Tag Manager (GTM) 통합

이 시나리오에서, PLP 위젯을 활성화하는 것은 GTM을 실패하게 할 수 있는 알려진 문제가 있다.

역할: 개발자/파트너 + 고객 엔지니어링

옵션 1: 검색 어댑터를 사용하여 계속합니다(임시 전용)

  • GTM이 비즈니스에 중요한 경우 검색 어댑터를 활성화한 상태로 유지합니다.
  • 보안 업데이트만 받습니다.
  • GTM 호환성이 해결되면 마이그레이션할 계획입니다.
  • GTM 호환성에 대한 업데이트는 Adobe 지원 센터에 문의하십시오.

옵션 2: GTM 추적을 대체 접근 방식으로 마이그레이션

  1. 사용자 지정 이벤트 컬렉션 구현:

    • Storefront Events SDK를 사용하십시오.
    • 검색 및 제품 상호 작용 이벤트를 캡처합니다.
    • 이벤트를 GTM 데이터 레이어에 수동으로 푸시합니다.

  2. 다음 단계를 완료하십시오:

    • 현재 GTM 추적 요구 사항 감사
    • GTM 이벤트를 Storefront 이벤트에 매핑합니다.
    • 사용자 지정 이벤트 리스너를 구현합니다.
    • GTM으로의 데이터 흐름을 테스트합니다.
    • 분석 보고서의 유효성을 검사합니다.

옵션 3: GTM을 Adobe Analytics으로 바꾸기

  • 해당되는 경우 Adobe Analytics​(으)로 마이그레이션하는 것이 좋습니다.
  • 지침은 고객 엔지니어링 팀에 문의하십시오.

문의할 사람: GTM 호환성 업데이트 또는 고객 엔지니어링 지원에 대한 지원 티켓을 제출합니다.

시나리오: Headless 또는 PWA 구현

이 시나리오에서는 사용자 정의 이벤트 수집이 필요하며 표준 PLP 위젯 UI를 사용할 수 없는 Headless 또는 PWA 스토어프론트가 있습니다.

역할: 개발자/파트너

  1. 참조 구현 검토:

  2. 사용자 지정 UI 구현:

    • 쿼리에 Live Search GraphQL API를 사용합니다.
    • 구성 요소를 나열하는 사용자 정의 제품을 빌드합니다.
    • 얼굴 맞춤화를 위한 UI 구현
    • 페이지 매김 및 정렬을 처리합니다.

  3. 이벤트 컬렉션 구현:

    • Storefront 이벤트 설명서를 검토하십시오.

    • 필요한 이벤트를 구현합니다.

      • search-request-sent
      • search-response-received
      • search-results-view
      • product-page-view
      • add-to-cart

    • Adobe Commerce에 대한 이벤트 데이터 흐름을 테스트합니다.

  4. 패싯 정렬 구성:

    • Headless 구현의 경우 패싯을 카운트별로 정렬할 수 있습니다.
    • Live Search > Facets 작업 영역에서 구성합니다.
    • 더 나은 UX를 위해 Sort Type​을(를) Count(으)로 설정하십시오.

  5. 테스트 및 유효성 검사:

    • 검색 결과의 정확성을 확인합니다.
    • Facet 기능을 테스트합니다.
    • 이벤트가 올바르게 추적되는지 확인합니다.
    • 성능 지표 모니터링.
    • 지능형 머천다이징 기능이 작동하는지 확인합니다.

시나리오: 사용자 정의 위젯 코드 수정

이 시나리오에서는 이전에 검색 어댑터 또는 위젯 코드를 사용자 정의했으며 사용자 정의를 마이그레이션해야 합니다.

역할: 개발자/파트너

  1. 기존 사용자 지정 문서:

    • 검색 어댑터에 대한 모든 사용자 지정을 나열합니다.
    • 각 맞춤화를 추진하는 비즈니스 요구 사항 파악
    • 맞춤화가 계속 필요한지 확인합니다.

  2. 기본 제공 기능이 사용자의 요구를 충족하는지 확인:

    • PLP 위젯 기능을 검토합니다.
    • CSS 기반 사용자 지정이 충분한지 확인합니다.
    • 기본 PLP 위젯 동작을 테스트합니다.

  3. 사용자 지정 코드가 필요한 경우:

    • PLP 위젯 리포지토리를 복제합니다.
    • 맞춤화 구현.
    • 자체 CDN에서 호스팅합니다.
    • 사용자 정의 위젯을 사용하도록 Commerce 구성을 업데이트합니다.
    note warning
    WARNING
    리포지토리의 코드를 사용하여 PLP 위젯을 사용자 정의하는 경우 유지 관리 및 업데이트를 담당합니다. Adobe의 새 PLP 위젯 기능이 사용자 정의 기능과 호환되지 않을 수 있습니다.

  4. 철저하게 테스트:

    • 모든 사용자 지정 기능을 테스트합니다.
    • Commerce 업데이트가 사용자 지정을 중단하지 않는지 확인합니다.
    • 사용자 지정 구현을 문서화합니다.
    • 지속적인 유지 관리를 위한 계획.

알려진 제한 사항 및 극단적 사례

마이그레이션할 때 다음 제한 사항에 유의하십시오.

PLP 위젯 제한:

  • 정렬 순서 방향: PLP 위젯이 활성화되면 제품 목록 페이지의 정렬 순서 방향을 변경할 수 없습니다(오름차순/내림차순).
  • 장바구니에 추가: 장바구니에 추가 단추는 위젯의 간단한 제품에만 사용할 수 있습니다.
  • 계층 가격: PLP 위젯에서는 지원되지 않습니다.
  • VAT 표시: 가격에는 VAT가 포함되지만 VAT는 별도의 값으로 표시할 수 없습니다.

검색 어댑터의 기능 차이점:

  • 색상 견본: 견본이 제대로 작동하려면 color 특성의 철자를 color("color" 또는 사용자 지정 이름이 아님)과 정확히 동일하게 지정해야 합니다.
  • 테마 스타일: 사용자 지정 테마 클래스는 위젯에서 상속되지 않습니다. 위젯별 CSS 클래스를 대상으로 해야 합니다.
  • 사용자 지정 제품 유형: 위젯에서 지원되지 않습니다.

성능 고려 사항:

  • 큰 카탈로그(50,000개 이상의 제품)는 초기 페이지 로드 시간이 길어질 수 있습니다.
  • 값이 많은 여러 패싯이 성능에 영향을 줄 수 있습니다.
  • 모바일 장치 성능은 카탈로그 크기에 따라 달라질 수 있습니다.

호환성 문제:

  • Google 태그 관리자 호환성 문제(GTM 시나리오 참조).
  • 일부 서드파티 확장이 PLP 위젯과 충돌할 수 있습니다.
  • 사용자 지정 체크아웃 확장 기능은 업데이트가 필요할 수 있습니다.

도움말 보기

특정 요구 사항에 따라 적절한 리소스에 문의하십시오.

Adobe 지원​은(는) 다음을 지원할 수 있습니다.

  • 표준 라이브 검색 마이그레이션 절차
  • PLP 위젯 구성 문제
  • 패싯 또는 속성 색인화 문제
  • 기본 구현과 관련된 성능 문제
  • 업그레이드 오류

개발 파트너/시스템 통합업체​에게 연락하여 문의해야 하는 사항:

  • 사용자 정의 테마 수정
  • 사용자 지정 위젯 코드 구현
  • 타사 확장 호환성
  • 헤드리스 또는 PWA 구현
  • 사용자 지정 이벤트 추적

Adobe 지원에 문의하려면 도움말 센터 사용 안내서를 참조하세요.

FAQ

검색 어댑터에서 PLP 위젯으로 마이그레이션하는 방법에 대한 일반적인 질문에 대한 답변을 살펴보십시오.

Q: 검색 어댑터가 버그 수정 또는 기능 업데이트를 수신합니까?

A: 아니요. 검색 어댑터는 더 이상 사용되지 않으며 보안 업데이트만 수신합니다. 버그 수정, 성능 개선 및 새로운 기능은 PLP 위젯에서만 사용할 수 있습니다. 검색 어댑터에 문제가 발생하면 PLP 위젯으로 마이그레이션하는 것이 좋습니다.

Q: 마이그레이션으로 인해 내 상점이 중단됩니까?

A: 스테이징에서 적절한 테스트 절차를 따르는 경우 마이그레이션이 원활하게 이루어져야 합니다. 프로덕션 배포에 대한 롤백 계획이 준비되었습니다.

Q: 마이그레이션에 얼마나 걸립니까?

A: 표준 구현의 경우: 1~2시간. 사용자 지정 구현의 경우: 복잡성에 따라 1~4주.

Q: 내 검색 머천다이징 규칙이 계속 작동합니까?

A: 예. Live Search 작업 영역에 구성된 모든 검색 머천다이징 규칙, 동의어 및 패싯이 PLP 위젯에서 계속 작동합니다.

Q: Facet을 다시 구성해야 합니까?

A: 일반적으로 그렇지는 않지만, 검색 어댑터가 있는 사용자 정의 소스 모델 속성에 의해 제한된 경우 이제 PLP 위젯에서 사용할 수 있습니다.

Q: 사용자 지정 CSS는 어떻게 됩니까?

A: PLP 위젯 클래스를 타깃팅하려면 CSS를 업데이트해야 합니다. CSS 클래스 참조를 참조하십시오.

Q: 검색 성능에 영향을 줍니까?

A: PLP 위젯은 성능 기준에 맞게 디자인되었습니다. 대부분의 상인들은 동등하거나 더 나은 성과를 본다. 스테이징에서 큰 카탈로그를 테스트해야 합니다.

recommendation-more-help
8eedb3c4-09d2-4e4f-917b-524833fc6b4f