Storefront Preview

Storefront Preview를 사용하면 지정된 소스 코드, 고객 그룹 또는 특정 날짜나 시간과 같은 컨텍스트에 따라 Progressive Web App(PWA) Kit 사이트가 어떻게 표시되는지 확인할 수 있습니다. 예를 들어 다가오는 세일 기간 동안 사이트가 어떻게 표시될지 미리 보고 싶다면 이 기능을 사용할 수 있습니다.

블랙 프라이데이/사이버 먼데이 세일이 다가오나요? 스테이징 환경에서 사이트 변경 사항을 미리 보십시오. 그런 다음 변경 사항을 프로덕션 환경에 배포하기 전에 제품, 가격 책정 및 마케팅 전략과 같은 항목의 변경 사항이 예상대로 작동하는지 확인하십시오.

또한 Storefront Preview를 타사 CMS(컨텐츠 관리 시스템)와 통합할 수 있습니다. 예를 들어 CMS에서 관리하는 연말연시 세일 배너가 있다고 가정해 보겠습니다. CMS가 유효 날짜 및 시간과 같은 현재 컨텍스트를 인식하도록 허용하여 사이트 미리보기에 지정된 기간의 연말연시 세일 배너와 같은 올바른 콘텐츠가 표시되도록 할 수 있습니다.

Storefront Preview는 Runtime Admin에서 사용할 수 있습니다. 이 가이드에서는 Storefront Preview를 구성 및 사용하고 문제를 해결하는 방법을 설명합니다.

Storefront Preview를 사용하려면 먼저 다음을 수행해야 합니다.

• PWA Kit 버전 2.8.3 이상 또는 3.2.x(@salesforce/commerce-sdk-react@1.4.0 또는 @salesforce/retail-react-app@2.4.0 포함)를 사용하여 사이트를 빌드합니다. Storefront Preview는 2.8.3 또는 3.2.x 이전의 PWA Kit 버전에서 사용할 수 없습니다. 현재 메이저 버전에 따라 PWA Kit 2.8.3 또는 3.2.x를 사용하도록 프로젝트를 업그레이드합니다.
• Runtime Admin에서 읽기 전용 이외의 역할로 프로젝트에 액세스할 수 있습니다. 액세스 권한이 없는 경우 Managed Runtime(MRT) 관리자 역할의 다른 사람에게 도움을 요청하십시오.
• Business Manager에서 구매자 컨텍스트를 활성화합니다.
• Storefront Preview에서 검증하려는 기능에 따라 사이트를 설정합니다. 예:
  • Business Manager에서 고객 그룹을 사용하여 맞춤형 Qualifier 및고객 그룹 ID를 설정함으로써 개인화된 가격 책정, 제품 또는 프로모션에 대한 규칙을 적용합니다.
  • 개인화된 구매자 경험을 보려면 구매자 컨텍스트 엔드포인트를 호출하는 소스 코드를 설정합니다. Storefront Preview는 개인화를 위해 컨텍스트 정보를 사용하기 때문에 이 작업이 필요합니다.
  • 특정 날짜에 제공하려는 가격을 설정합니다. 이렇게 하면 Storefront Preview에서 해당 날짜를 선택할 때 지정된 가격이 표시됩니다.
• Storefront Preview 구성 섹션에서 설명하는 구성 단계를 따릅니다.
• https://runtime.commercecloud.com에서 타사 쿠키를 허용하도록 브라우저를 구성합니다.

선택적으로, Storefront Preview를 타사 CMS와 통합하려는 경우 함수를 작성할 수 있습니다. 스토어프런트에 StorefrontPreview 구성 요소 추가 및 타사 CMS와 통합을 참조하십시오.

Storefront Preview는 최신 버전의 Chrome 또는 Safari에서 사용할 수 있습니다. 브라우저에서 https://runtime.commercecloud.com이 타사 쿠키에 액세스할 수 있도록 허용해야 합니다 . 타사 쿠키를 활성화하지 않으면 Storefront Preview가 작동하지 않습니다.

• Storefront Preview에 표시되는 데이터와 경험이 반드시 구매자 경험을 반영하는 것은 아닙니다. 구매자 개인화를 위해서는 PWA Kit 프로젝트 내에서 Shopper Context API를 사용해야 합니다. 구매자 컨텍스트에 대해 자세히 알아보십시오.
• Storefront Preview는 사이트의 게스트 사용자에게 표시되는 스토어프런트 페이지를 보여줍니다. 예를 들어 게스트 사용자는 제품 또는 마케팅 컨텐츠, 가격 책정, 프로모션, 제품 목록 또는 제품 표시 페이지를 볼 수 있습니다. 로그인한 사용자에게 표시되는 컨텐츠(예: 계정 정보 또는 장바구니)는 표시되지 않습니다.
• Storefront Preview는 Storefront Reference Architecture(SFRA) 페이지가 아니라 PWA Kit 페이지에서 작동합니다. 그러나 B2C Commerce의 Storefront Toolkit 사이트 미리보기 도구를 사용하여 SFRA 페이지를 미리 볼 수 있습니다.

Storefront Preview를 사용하는 각 사이트에 요구되는 다음 일회성 구성 단계를 수행합니다.

• 1. B2C Commerce 인스턴스에 대한 SLAS 프라이빗 클라이언트 생성
• 2. SLAS 프라이빗 클라이언트 세부 정보 및 Commerce API 단축 코드를 사용하여 MRT 환경 변수 생성
• 3. Account Manager 사용자에게 B2C Commerce 인스턴스에 대한 액세스 권한이 있는지 확인
• 4. 스토어프런트에 StorefrontPreview 구성 요소 추가
• 5. 스토어프런트 컨텐츠 보안 정책 헤더 업데이트

스토어프런트에서 사용하는 B2C Commerce 인스턴스의 범위 sfcc.shopper-context.rw 및 sfcc.ts_ext_on_behalf_of를 사용하여 Shopper Login and API Access Service(SLAS) 전용 클라이언트를 생성해야 합니다. Storefront Preview는 SLAS 프라이빗 클라이언트를 사용하여 스토어프런트의 컨텍스트를 설정합니다. SLAS 프라이빗 클라이언트는 SLAS 관리자 UI를 사용하여 쉽게 만들 수 있습니다.

Shopper API 승인 가이드의 단계에 따라 Storefront Preview를 사용할 각 B2C Commerce 인스턴스에 대한 SLAS 프라이빗 클라이언트를 생성합니다.

• Which App Type will be used?(어떤 앱 유형을 사용합니까?) 필드에서 BFF 또는 웹앱 앱 유형을 선택하여 프라이빗 클라이언트를 생성합니다.
• Enter the shopper scopes(구매자 범위 입력) 필드에서 공백으로 구분된 범위를 지정합니다. sfcc.shopper-context.rw sfcc.ts_ext_on_behalf_of

다음 단계에서 사용할 수 있도록 결과 페이지 상단에 표시되는 자동으로 생성된 클라이언트 암호와 클라이언트 ID를 복사합니다.

MRT 환경 변수를 생성하려면 MRT API 엔드포인트 projects_target_env_var_partial_update를 호출합니다. $SLAS_PRIVATE_CLIENT_ID와 $SLAS_PRIVATE_CLIENT_SECRET을 1단계에서 복사한 값으로 바꿉니다. $CC_SHORT_CODE를 Business Manager의 단축 코드 구성 값로 바꿉니다. Runtime Admin을 사용하여 환경 변수를 관리할 수도 있습니다. Environment Variables(환경 변수)를 참조하십시오.

B2C Commerce 인스턴스에 연결된 스토어프런트에서 Storefront Preview를 사용하려면 Business Manager 관리자 또는 Business Manager 사용자라는 Account Manager 사용자 역할 중 하나가 있어야 합니다. 이들 역할 중 하나가 있는지 확인하려면 Account Manager에서 역할을 확인합니다.

필요한 역할 중 하나가 없는 경우 다음 권한 부여 지침에 따라 Account Manager 사용자에게 인스턴스를 추가합니다.

Runtime Admin과 스토어프런트 간의 통신이 작동하도록 통신 채널을 설정합니다. 여기에는 다음 두 단계가 포함됩니다.

• 통신을 활성화하려면 스토어프런트의 PWA Kit React SDK에서 StorefrontPreview 구성 요소를 렌더링합니다. StorefrontPreview 구성 요소는 Runtime Admin과의 통신을 설정하는 스크립트를 삽입합니다. 이 스크립트는 스토어프런트가 Storefront Preview에서 실행 중일 때만 로드되므로 스토어프런트의 성능에 영향을 미치지 않습니다.
• StorefrontPreview를 렌더링할 때마다 getToken 속성을 정의해야 하며, 이 속성은 현재 구매자의 액세스 토큰을 반환해야 합니다.

선택적으로 Storefront Preview를 타사 CMS와 통합하려는 경우 StorefrontPreview 구성 요소에 onContextChange 속성을 추가할 수 있습니다. 타사 CMS와의 통합을 참조하십시오. 아래 예에서는 onContextChange 속성을 추가하고 handleContextChange라는 비동기 함수를 전달합니다. handleContextChange 함수의 console.log 문을 사용자 고유의 논리로 대체하여 컨텍스트 변경에 응답할 수 있습니다. 특정 요구 사항에 따라 handleContextChange 함수를 맞춤화합니다. 이 함수의 newContext 매개변수에는 업데이트된 컨텍스트 정보가 포함됩니다.

PWA Kit 버전 2.8.x가 있는 경우 스토어프런트에서 다음 코드를 사용하여 통신 채널을 설정합니다. _app/index.jsx 파일에서 IntlProvider 구성 요소 주위에 StorefrontPreview 구성 요소를 추가합니다.

PWA Kit 버전 3.2.x가 있는 경우 스토어프런트에서 다음 코드를 사용하여 통신 채널을 설정합니다. _app/index.jsx 파일에서 IntlProvider 구성 요소 주위에 StorefrontPreview 구성 요소를 추가합니다.

통신 채널을 활성화하려면 스토어프런트가 다음을 수행해야 합니다.

• 런타임 관리자(runtime.commercecloud.com)에 의해 그 자체가 iframe에 포함될 수 있도록 허용합니다.
• 4단계에서 언급한 스크립트를 로드하고 실행하도록 허용합니다.

컨텐츠 보안 정책(CSP) frame-ancestors , connect-src 및 script-src 지시문에 https://runtime.commercecloud.com을 추가하여 통신 채널을 활성화합니다. 이 작업을 자동으로 처리하려면 pwa-kit-runtime 패키지에서 제공하는 defaultPwaKitSecurityHeaders 미들웨어를 가져와서 사용하십시오.

StorefrontPreview 구성 요소를 스토어프런트에 이미 추가했고 이제 타사 CMS와 통합하려는 경우 StorefrontPreview 구성 요소에 onContextChange 속성을 추가합니다. 타사 CMS와 통합을 참조하십시오.

아래 예에서는 onContextChange 속성과 handleContextChange라는 비동기 함수를 추가합니다. handleContextChange 함수의 console.log 문을 고객의 자체 로직으로 대체하여 컨텍스트 변경에 응답할 수 있습니다. 특정 요구 사항에 따라 handleContextChange 함수를 맞춤화합니다. 이 함수의 newContext 매개변수에는 업데이트된 컨텍스트 정보가 포함됩니다.

PWA Kit 버전 2.8.x가 있는 경우 다음 코드를 사용하여 _app/index.jsx 파일에 onContextChange 속성을 추가합니다.

PWA Kit 버전 3.2.x가 있는 경우 다음 코드를 사용하여 _app/index.jsx 파일에 onContextChange 속성을 추가합니다.

Storefront Preview를 사용하려면 다음 단계를 따르십시오.

1. 브라우저에서 Runtime Admin을 열고 Account Manager 자격 증명을 사용하여 로그인합니다.

2. 프로젝트의 환경 페이지로 이동하여 사이트를 미리 보려는 환경 옆에 있는 사이트 미리보기를 클릭합니다.

   왼쪽 사이드바에 Storefront Preview 양식이 있는 스토어프런트를 보여주는 새 탭이 열립니다.

3. (선택 사항) 미리 볼 컨텍스트의 유효 날짜 및 시간을 선택합니다. 표시되는 날짜 및 시간은 컴퓨터의 표준 시간대를 기준으로 하며 컨텍스트를 설정하는 요청을 보내기 전에 UTC 시간으로 변환됩니다. 날짜 및 시간을 지정하지 않으면 미리보기에 현재 날짜 및 시간이 반영됩니다.

4. (선택 사항) 미리 보려는 컨텍스트에 대한 프로모션을 트리거하는 소스 코드(캠페인 할당) 및 Price Book(소스 코드 그룹에 할당됨)을 입력합니다.

5. (선택 사항) Business Manager에서 설정한 고객 그룹 ID를 입력합니다. 쉼표를 사용하여 각 ID를 구분합니다.

6. (선택 사항) Business Manager에서 설정한 개인화된 가격, 제품 또는 프로모션에 적용되는 맞춤형 Qualifier를 입력합니다. 맞춤형 qualifier 키는 고유해야 합니다. 최대 20개의 맞춤형 qualifier를 정의할 수 있습니다.

7. 미리보기를 클릭합니다.

   이제 미리 보려는 컨텍스트를 사용하여 스토어프런트를 탐색할 수 있습니다.

   보다 쉽게 공유할 수 있도록 브라우저 탭의 URL이 컨텍스트 값을 포함하도록 업데이트됩니다.

Storefront Preview에 문제가 있는 경우 MRT 환경에서 Storefront Preview 로그를 활성화할 수 있습니다. 이렇게 하면 미리보기 버튼을 클릭할 때 추가 로그가 인쇄되어 문제를 디버깅하는 데 도움이 됩니다.

Storefront Preview 로그를 활성화하려면 MRT 환경에 MRT 환경 변수STOREFRONT_PREVIEW_DEBUG=1를 추가합니다.

MRT 비상 로그를 사용하여 Storefront Preview 로그를 읽을 수 있습니다.

이 섹션에서는 Storefront Preview를 사용하는 동안 발생할 수 있는 일반적인 오류의 해결 방법을 제안합니다.

브라우저에 따라 타사 쿠키가 활성화되지 않은 경우 다른 동작이 발생할 수 있습니다.

• Chrome:"이 스토어프런트에서 미리보기가 활성화되지 않았습니다"라는 모달이 나타나고 스토어프런트에 SecurityError가 표시됩니다.
• Safari:"Storefront Preview를 초기화하지 못했습니다"라는 모달이 나타나고 스토어프런트가 표시되지 않습니다.

**원인:**브라우저에서 https://runtime.commercecloud.com에서 타사 쿠키를 허용하지 않습니다.

제안된 솔루션:https://runtime.commercecloud.com에서 타사 쿠키를 허용하기 위해 사용할 수 있는 브라우저 설정 및 확장 프로그램을 업데이트합니다.

Storefront Preview를 로드할 때 다음 오류 메시지가 표시됩니다. "Preview is not enabled on this storefront!"

**원인:**스토어프런트에 Runtime Admin과의 통신을 지원하는 스크립트 파일이 없습니다.

제안된 솔루션: 오류 메시지 창에 표시된 지침을 따르거나 4단계의 구성을 완료합니다.

미리보기 버튼을 클릭할 때 다음 응답 오류 메시지가 표시됩니다.

제안된 솔루션: 1단계와 2단계의 구성을 완료합니다.

브라우저에 따라 올바른 컨텐츠 보안 정책이 없는 경우 오류가 발생할 수 있습니다.

• Chrome: "이 스토어프런트에 미리보기가 활성화되지 않았습니다"라는 모달이 나타나고 스토어프런트에 "연결 거부"라는 오류 페이지가 표시됩니다.
• Safari: "이 스토어프런트에 미리보기가 활성화되지 않았습니다"라는 모달이 나타나고 스토어프런트가 표시되지 않습니다.

**원인:**스토어프런트가 컨텐츠 보안 정책에서 Runtime Admin을 허용하지 않습니다.

제안된 솔루션: 5단계의 지침에 따라 콘텐츠 보안 정책을 올바르게 구성합니다.

Storefront Preview에서 로드되는 초기 페이지는 환경의 외부 호스트 이름으로 구성된 도메인입니다.

원인: 환경 설정에서 외부 호스트 이름이 올바르게 구성되지 않았습니다.

제안된 솔루션: 환경 설정의 고급 섹션에서 외부 호스트 이름이 올바른 도메인을 가리키도록 구성합니다.

미리보기 버튼을 클릭할 때 다음 응답 오류 메시지가 표시됩니다.

제안된 솔루션: 3단계를 완료합니다.

미리보기 버튼을 클릭할 때 다음 응답 오류 메시지가 표시됩니다.

원인: MRT 환경 변수 SLAS_PRIVATE_CLIENT_ID 및 SLAS_PRIVATE_CLIENT_SECRET의 값이 잘못되었거나 SLAS 프라이빗 클라이언트 구성이 잘못되었습니다.

제안된 솔루션: 1단계와 2단계를 완료합니다.

StorefrontPreview 구성 요소에 onContextChange 속성을 추가한 후 사이트를 미리 보는 동안 오류 메시지나 예기치 않은 결과가 나타날 수 있습니다.

원인: onContextChange 속성에 의해 호출된 함수에 문제가 있을 수 있습니다.

제안된 솔루션: StorefrontPreview 구성 요소에서 onContextChange 속성과 이 속성이 호출하는 함수를 제거합니다. 그런 다음 사이트를 미리 보고 동일한 문제가 발생하는지 확인합니다. 그렇지 않은 경우 함수를 디버그하여 오류를 해결합니다. 예를 들어, 다음을 수행할 수 있습니다.

• onContextChange 속성과 이 속성이 호출하는 함수를 StorefrontPreview 구성 요소에 다시 추가합니다. 타사 CMS와 통합을 참조하십시오.
• 사이트를 미리 보는 동안 네트워크 활동을 검사하고 가져오기 요청이 정상적인 데이터를 전송하는지 확인합니다.

onContextChange 속성과 이 속성이 호출하는 함수를 제거한 후에도 여전히 문제가 있는 경우 지원 사례를 엽니다.

사이트를 미리 보는 동안 컨텐츠가 정상적으로 표시되지 않고 위와 같은 오류가 전혀 발생하지 않습니다. 예를 들어 가격이 Storefront Preview에서 입력한 값에 따라 변경되지 않습니다.

원인: 사전 요구 사항 중 하나 이상을 완료하지 않았을 수 있습니다.

제안된 솔루션: 사전 요구 사항을 모두 완료했는지 확인합니다. 그렇게 했는데도 문제가 계속 발생하면 지원 사례를 엽니다.