단계별 헤드리스 롤아웃

이제 Storefront Reference Architecture(SFRA) 및 SiteGenesis 사용자가 헤드리스 기술을 단계별로 롤아웃할 수 있습니다. 예를 들어 PWA Kit를 사용하여 제품 페이지의 과감한 새로운 경험을 배포하고 헤드리스 전환의 다음 단계까지 체크아웃 흐름을 SFRA에서 유지할 수 있습니다. 이 단계별 접근 방식은 헤드리스로의 전환을 빨리 시작하고 전환 과정에서 가동 중단을 최소화할 수 있게 해줍니다.

이 가이드에서는 세션 브리징 및 라우팅 규칙을 사용하여 PWA Kit가 하나의 페이지 세트를 구동하고 SFRA가 다른 페이지 세트를 구동하도록 하는 방법을 설명합니다.

단계별 헤드리스 롤아웃과 관련하여 Einstein 작업에 대해 자세히 알아보려면 단계별 헤드리스 롤아웃을 위한 Einstein 작업을 참조하십시오.

구매자들이 서로 다른 스토어프런트 아키텍처로 구동되는 페이지 간을 원활하게 이동할 수 있도록 하려면 세션 브리징이라는 기술을 사용해야 합니다. 세션 브리징은 쿠키를 사용하여 서로 다른 시스템 간에 구매자 새로 고침 토큰 및 세션 토큰을 공유합니다.

세션 브리징을 지원하는 데 있어 핵심은 HTTP 요청을 통해 액세스할 수 있는 새로운 인증 및 권한 부여용 표준 기반 솔루션인 Shopper Login and API Access Service(SLAS)입니다. SLAS를 사용한 구매자 인증은 OpenID Connect를 기반으로 하며, Commerce Cloud의 Shopper API에 대한 인증은 OAuth 2를 기반으로 합니다.

구매자가 헤드리스 스토어프런트를 탐색할 때는 SLAS를 사용하여 액세스 토큰과 새로 고침 토큰을 요청하고 구매자의 브라우저에 쿠키로 저장합니다. HTTP set-cookie 헤더 또는 클라이언트 측 JavaScript를 사용하여 쿠키를 설정할 수 있습니다. 구매자가 SFRA 페이지에서 PWA Kit 페이지로(또는 그 반대로) 전환하면 새로 고침 토큰이 포함된 쿠키가 HTTP 요청과 함께 전송되고, 스토어프런트 코드에서 새로 고침 토큰을 사용하여 사용자의 로그인을 처리할 수 있습니다.

플러그인 SLAS는 dwsid와 관련한 B2C Commerce 세션 및 access_token과 관련한 SLAS 세션을 관리합니다. 세션 브리징 링크 dwsid 및 access_token을 동일한 구매자 세션에 연결합니다.

플러그인 SLAS는 두 가지 세션 브리징 방법을 사용합니다.

1. SLAS 세션 브리지(API: getSessionBridgeAccessToken)
   • 플러그인 SLAS에서 신규 게스트 로그인에만 사용됩니다.
   • 세션 브리징 후 새 dwsid를 생성하지 않으므로, 스토어프론트를 다시 렌더링할 필요가 없으며, 200 OK 응답을 전송할 수 있습니다.
2. OCAPI 세션 브리지(API: OCAPI 세션 가져오기)
   • 플러그인 SLAS에서 등록된 구매자 로그인과 토큰 로그인 새로 고침에 사용됩니다.
   • 세션 브리징 후 새 dwsid를 생성하므로, 스토어프론트를 새로 고쳐야 하고 302 리디렉션 응답을 전송해야 합니다.

단계별 헤드리스 롤아웃을 생성하는 첫 번째 단계는 PWA Kit 애플리케이션이 SLAS를 사용하도록 설정하는 것입니다(아직 설정하지 않은 경우). API 액세스 설정 가이드의 지침을 따릅니다.

SFRA를 사용하여 단계별 헤드리스 롤아웃을 지원하려면 플러그인 SLAS 카트리지를 설치해야 합니다. 카트리지의 README에서 설명하는 설치 지침을 완료합니다.

SLAS 카트리지 사용자를 위한 중요 고려 사항

플러그인 SLAS 카트리지는 다양한 API를 여러 번 호출하므로, 스토어프런트 성능에 영향을 미칠 수 있습니다. 카트리지를 프로덕션 스토어프런트에 추가하기 전에, 카트리지가 있는 경우와 없는 경우의 스토어프런트 성능을 비교하여 적합한지 여부를 판단하십시오.

또한 카트리지는 다음과 같은 조건에서 리디렉션을 실행합니다.

• 구매자가 아직 세션 쿠키를 가지고 있지 않은 경우
• 구매자의 세션 쿠키가 만료된 경우
• 검색 엔진이 사이트를 인덱싱할 때

현재, 카트리지는 Salesforce 내에 자격 증명이 저장되는 B2C Commerce 시스템에 대한 직접 로그인만 대체합니다.

위시리스트 플러그인과 함께 사용할 경우, 로그인 시 등록된 사용자에게 게스트 위시리스트가 전송되지 않습니다.

카트리지를 사용하기 전에 GitHub에서 문제 페이지를 검토하십시오.

플러그인 SLAS 카트리지는 SFRA용으로 설계되었으므로, SiteGenesis와 함께 사용하려면 추가 코드를 작성해야 합니다. SiteGenesis 구현 환경에서는 구매자 인증 및 권한 부여 흐름의 다양한 지점에 카트리지의 코드를 활용할 수 있습니다.

이 카트리지는 B2C Commerce 웹 서비스 프레임워크를 사용하여 SLAS API 호출을 처리하므로, SiteGenesis 구현에서 카트리지에 의해 구현된 웹 서비스로 요청을 보낼 수 있습니다. 이러한 웹 서비스로는 게스트 로그인, 등록 고객 로그인, 토큰 새로 고침, 로그아웃, 게스트 장바구니 병합 등이 있습니다. 또한 이 카트리지는 API 세션과 스토어프런트 세션을 병합하는 서비스를 구현합니다.

SiteGenesis 구현에서는 맞춤형 후크(app.plugin.slas.login)를 사용하여 SLAS를 사용한 게스트 및 등록 사용자의 로그인을 구현할 수도 있습니다. 구매자 로그인에 사용하는 Script API를 SLAS로 대체하는 방법은 dw.system.request.onSession에서 카트리지의 onSession 후크에 있는 맞춤형 코드를 참조하십시오.

PWA Kit로 세션 브리징을 지원하려면 로컬 스토리지 대신 쿠키를 사용하도록 API 인증을 처리하는 commerce-api/auth.js의 코드를 수정해야 합니다.

PWA Kit 프로젝트가 Retail React App 템플릿 버전 2.7.x에서 생성된 경우 auth.js의 이 코드 줄에서 주석을 제거하여 토큰 저장을 위해 CookieStorage로 전환할 수 있습니다. 이는 SFRA와 PWA Kit 사이트 간의 세션을 관리하는 데 필요합니다.

또한 구매자 로그인 후 세션 브리지 API를 호출하는 commerce-api/auth.js의 코드를 수정해야 합니다. 이렇게 하려면 auth.js에서 코드 줄의 주석을 제거해야 합니다.

시간을 절약할 수 있도록, 변경 사항이 모두 적용된 대체 버전의 파일을 만들어 공개 gist을 통해 GitHub에서 제공하고 있습니다.

PWA Kit 프로젝트가 Retail React App 템플릿의 버전 3.0.0 이상에서 생성된 경우, 위에 언급된 변경 사항은 기본적으로 활성화되며 별도로 코드를 변경할 필요가 없습니다.

인증 흐름은 새로 고침 토큰으로 시작합니다. 새로 고침 토큰 쿠키를 사용할 수 있는 경우 PWA Kit 앱은 새로 고침 토큰을 액세스 토큰과 교환합니다. 그렇지 않으면 이 앱은 OAuth 2.1 표준에 정의된 대로 인증 코드 부여 흐름을 시작합니다. 또한 코드 교환(PKCE) 흐름을 위해 증명 키를 팔로우합니다.

SLAS에서 새 액세스 토큰과 새로 고침 토큰이 부여되면 앱은 이를 쿠키에 저장합니다. 그런 다음 OCAPI의 세션 생성 엔드포인트(/session)에 POST 요청을 합니다. 이 엔드포인트는 SFRA에 사용되는 세션을 생성합니다. 이 앱은 세션 토큰을 쿠키에 저장합니다.

PWA Kit 앱이 생성하는 쿠키:

• cc-nx-g - SLAS 게스트 구매자 새로 고침 토큰
• cc-nx - SLAS 등록 구매자 새로 고침 토큰
• token - SLAS 액세스 토큰
• dwsid - Demandware 세션 ID

단계적 롤아웃 중에 원활한 사용자 경험을 보장하려면 Managed Runtime 환경과 B2C Commerce 인스턴스라는 두 가지 다른 오리진으로 트래픽을 라우팅할 수 있는 방법이 필요합니다. 이 트래픽 라우팅은 컨텐츠 제공 네트워크(CDN)에서 처리될 수 있습니다.

다음 시나리오를 떠올려보십시오.

www.mystorefront.com에서 기존 SFRA 스토어프런트를 실행하고 있습니다. 여러분은 헤드리스 아키텍처의 이점을 잘 알고 있으며 PWA Kit를 활용하여 성능과 경쟁력 있는 경험을 제공하고자 합니다. 이와 동시에 일정에 대한 위험을 최소화하기 위해, PWA Kit 스토어프론트를 단계적으로 롤아웃하는 방법을 선택합니다.

퍼널 상단에서 페이지 요청을 PWA Kit, 즉 홈 페이지(/), 카테고리 목록 페이지(/category), 제품 세부 정보 페이지(/product)로 전송하도록 CDN을 구성합니다. 이러한 PWA Kit 페이지는 mystorefront.mobify-storefront.com에서 실행되는 Managed Runtime 환경에 배포됩니다. 구매자가 구매를 결정하면 CDN이 구매자를 www.mystorefront.com에서 실행되는 기존 SFRA 체크아웃 페이지로 리디렉션합니다.

트래픽 라우팅을 처리하려면, Salesforce(Cloudflare 기반)의 내장 CDN(eCDN) 솔루션을 선택하거나 다른 공급업체의 CDN을 선택할 수 있습니다.

eCDN을 사용하여 트래픽을 Managed Runtime으로 라우팅하려면 Commerce API 엔드포인트 createMrtRules를 사용합니다.

API는 Cloudflare 규칙 표현식을 사용하여 Managed Runtime에 대한 라우팅 트래픽을 지원합니다. 규칙 언어에서 사용 가능한 필드 중 일부를 지원합니다. 다음 필드가 지원됩니다.

• http.host는 호스트 이름을 기준으로 매칭합니다.
• http.request.uri.path는 요청 경로를 기준으로 매칭합니다.
• http.request.uri은 요청 경로 및 쿼리 문자열 모두를 기준으로 매칭합니다.
• http.cookie는 쿠키를 기준으로 매칭합니다.

프록시 영역에서는 인스턴스당 100개의 개별 규칙을 요청할 수 있고, 레거시 영역에서는 개발/프로덕션 인스턴스 간에 공유되는 총 100개의 개별 규칙을 요청할 수 있습니다.

• eCDN은 프로덕션 및 개발 인스턴스에만 사용할 수 있으며, 샌드박스 또는 ODS 인스턴스에는 사용할 수 없습니다.
• eCDN API를 사용하여 스테이징 인스턴스를 eCDN에 온보딩해야 합니다. 자세한 내용은 B2C Commerce Infocenter에서 스테이징용 eCDN 구성을 참조하고, Rhino Inquisitor 블로그에서 이 기사를 참조하십시오.
• eCDN은 위치 정보 기반의 라우팅을 지원하지 않습니다.

오리진 규칙을 설계하는 데 도움이 되는, PWA Kit 페이지의 포괄적인 경로 목록을 참조하십시오. Retail React App 템플릿을 기반으로 하는 PWA Kit 프로젝트의 경우 경로가 app/routes.jsx에 나열됩니다. PWA Kit용 서버 측 렌더링 시스템은 프록시 및 정적 자산에 대한 내부 경로를 사용하므로 라우팅 규칙에 /mobify/*도 포함해야 합니다.

예제 시나리오의 경우 CDN에 다음 경로를 구성해야 합니다.

목록의 모든 PWA Kit 경로를 포함하는 오리진 규칙을 빌드하여 요청을 Managed Runtime 환경(이 예제 시나리오에서는 mystorefront.mobify-storefront.com)으로 전달합니다.

다음 다이어그램은 앞서 설명한 예제 시나리오의 eCDN 구성을 보여 줍니다.

기본적으로 PWA Kit 프로젝트의 Retail React App 템플릿은 URL 라우팅 패턴이 SFRA와는 다릅니다. 예를 들어 Retail React App에서 제품 세보 정보 페이지의 URL 경로는 /products/{productId}입니다. SFRA의 경우 이 패턴은 /{categoryId}/{productId}입니다.

PWA Kit 스토어프런트의 라우팅 패턴을 SFRA 사이트에 맞게 변경하는 것이 좋습니다. 특정 페이지의 URL 패턴(예: URL에 카테고리 ID를 사용할 수 없는 경우 제품 목록 페이지)과 맞출 수 없는 경우 리디렉션 카트리지를 사용하여 차이를 해결하는 리디렉션을 설정할 수 있습니다. 전체 설치 지침은 카트리지의 README에 나와 있습니다.

단계별 헤드리스 롤아웃 위한 설정 프로세스를 완료하려면 PWA Kit 프로젝트를 몇 가지 더 변경해야 합니다.

기본적으로 PWA Kit는 탐색에 History API를 사용합니다. 구매자가 React Router의 <Link> 구성 요소로 만든 링크를 클릭하면 app/routes.jsx에 정의된 경로 오브젝트의 경로와 일치하는 구성 요소에 대한 소프트 탐색이 트리거됩니다. PWA Kit 페이지 이외의 페이지(예: SFRA가 제공하는 페이지)에 연결하려면 해당 URL 경로 이름과 일치하는 경로를 app/routes.jsx에서 제거해야 합니다.

예를 들어 Retail React App 템플릿 버전 2.7.x 또는 버전 3.x에서 확장성 기능을 사용하지 않고 PWA Kit 프로젝트를 생성한 경우, 경로 배열에서 체크아웃을 제거합니다.

Retail React App 템플릿 버전 3.x에서 확장성 기능을 사용하여 PWA Kit 프로젝트를 생성한 경우, javascript를 사용하여 비PWA Kit 페이지에 대한 링크를 필터링하도록 overrides/app/routes.jsx 파일을 재정의합니다. /cart 및 /checkout 경로를 필터링하기 위한 모든 변경 사항이 적용된 overrides/app/routes.jsx 파일의 예제 재정의를 만들어 공개 gist를 통해 GitHub에서 제공하고 있습니다.

마지막으로 app/routes.jsx에서 PWA 캐치올 경로(/*)를 업데이트합니다. PWA <PageNotFound /> 구성요소를 기본 오리진에 대한 리디렉션으로 바꿉니다.

PIG 인스턴스의 경우, 고객은 eCDN을 사용하여 SFRA(또는 SG)와 MRT 오리진 간의 트래픽을 "분할"할 수 있습니다. 하지만 eCDN은 SIG 인스턴스와 ODS를 지원하지 않습니다. SIG 인스턴스에서 로컬로 단계별 롤아웃 사이트를 설정하고 테스트하려면, 고객이 자체 역 프록시 또는 CDN을 사용하여 트래픽을 분할해야 합니다.

PWA Kit 및 SFRA/SiteGenesis에 걸친 하이브리드 배포 구매자 흐름을 개발하고 테스트하는 데 사용할 수 있는 샘플 Node.js 앱을 만들었습니다. 역방향 프록시 설정을 위한 설정 및 구성 지침은 리포지토리에 대한 README를 참조하십시오.

SIG 인스턴스에서 단계별 롤아웃을 설정하는 단계를 보여주는 데모 비디오를 한곳에서 제공합니다.

프로덕션 구성과 유사한 별칭 구성을 사용하도록 ODS를 구성하면, 로컬 설정과 프로덕션 설정을 동일하게 유지할 수 있습니다. 예를 들어 / URI에서 하이브리드 사이트를 사용할 수 있도록 샌드박스를 구성하면, 사이트 ID를 포함하도록 pwa-kit에서 전송한 URL을 변환할 필요가 없습니다. 일반적으로 프로덕션 사이트는 이렇게 구성됩니다.

Business Manager에서 별칭을 활성화하려면 Trailhead의 Salesforce B2C Commerce 호스트 이름 별칭에 대한 이 모듈의 지침을 따르십시오.

모든 발신 URL(예: SFRA용 URL)에 /s/SiteID 접두사를 포함하도록 PWA Kit 경로 설정을 구성할 수 있습니다. 이렇게 하면 인스턴스에서 호스트 이름 별칭을 명시적으로 구성할 필요 없이 샌드박스에서 일반적으로 사용되는 방식으로 컨트롤러 URL을 수신할 수 있습니다. 이는 프로덕션 구성에 적합하지 않을 수 있으므로, 프로덕션 배포와 샌드박스 배포 간에 서로 다른 캐치올 경로를 설정할 수 있습니다.

경로 접두사를 구성하려면 app/routes.jsx 또는 overrides/app/routes.jsx에서 PWA 캐치올 경로(/*)를 업데이트합니다.