Salesforce 상거래 클라우드 카트리지를 업그레이드하는 방법

학습 내용

클라비요 세일즈포스 커머스 클라우드 카트리지를 업그레이드하는 방법을 알아보세요. 

23.7.0 이전 카트리지 버전을 사용 중이신가요? 즉시 버전 23.7.0 이상으로 업그레이드하는 것이 좋습니다. 이전 버전의 카트리지는 Klaviyo의 v1 및 v2 API를 사용하며, 이는 더 이상 사용되지 않고 더 이상 예상대로 작동하지 않습니다. 항상 최신 버전(현재 24.1.0)으로 업그레이드하는 것이 좋습니다.

시작하기 전 안내 사항

버전 23.7.0(2023년 7월 13일 출시)에는 여러 가지 의미 있는 개선 사항이 포함되어 있으며, 그 중 일부는 이벤트 트리거 방식과 관련된 아키텍처 변경 사항입니다. 23.70 미만 버전에서 그 이상의 버전으로 업그레이드할 때 특별히 고려해야 할 사항은 아래에 자세히 설명되어 있습니다.

현재 통합 상태 이해하기

현재 SFCC 통합과 웹사이트에 특별히 어떤 변경 또는 사용자 지정이 이루어졌는지 파악하는 것이 중요합니다. 가장 중요한 것은 클라비요에 전송하는 특정 이벤트 데이터가 변경되거나 보강되었는지 여부와 사용자 지정 이벤트를 추가했는지 여부를 고려해야 한다는 것입니다.

이벤트 데이터를 수집하는 코드를 클라비요의 깃허브에서 제공되는 이전 버전의 클라비요 카트리지와 비교하는 것을 권장합니다. 통합을 크게 사용자 정의하지 않았다고 가정하면, 현재 데이터 어셈블리 함수는 int_klaviyo_core/cartridge/scripts/utils/klaviyo/klaviyoUtils.js에서, 주문 확인은 int_klaviyo_core/cartridge/scripts/utils/klaviyo/emailUtils.js에서 찾을 수 있습니다.

새 카트리지를 설치한 후 다시 적용할 수 있도록 사용자 지정 사항을 기록해 두세요.

SFCC 샌드박스를 클라비요 테스트 계정에 연결하기

SFCC 프로덕션 환경에 연결된 계정과 별도로 테스트용 보조 클라비요 계정을 아직 만들지 않았다면 지금 바로 만들어야 합니다. 그런 다음 SFCC 샌드박스 환경을 새 계정에 연결합니다. 새 클라비요 카트리지로 코드베이스를 업그레이드하기 전에 이벤트가 보조 클라비요 계정에서 성공적으로 송수신되는지 확인할 수 있도록 이전 클라비요 카트리지 버전을 사용하여 이 단계를 완료하는 것이 좋습니다.

이전 클라비요 카트리지 코드 제거

통합을 크게 사용자 정의하지 않은 경우, 코드베이스에서 int_klaviyo_core와 int_klaviyo(Site Genesis용) 또는 int_klaviyo_sfra(SFRA용) 두 개의 Klaviyo 카트리지 폴더를 삭제하기만 하면 이전 Klaviyo 통합의 대부분을 제거할 수 있습니다. 그러나 템플릿 파일에 추가되었을 수 있는 클라비요 관련 코드와 자바스크립트 파일도 제거해야 합니다.

사이트 제네시스의 경우

Site Genesis의 표준 통합에는 footer_UI.isml에 다음 코드가 추가됩니다:

<isinclude template="components/footer/klaviyoFooter"/>

또한 미니카트.isml에 다음 블록이 추가됩니다, cart.isml 및 기타 모든 "장바구니" isml 파일을 삭제합니다:

<isif condition="${pdict.CurrentHttpParameterMap.cartAction == 'add' || pdict.CurrentHttpParameterMap.cartAction
  == 'update'}">
  <isinclude url="${URLUtils.url('Klaviyo-RenderKlaviyoAddToCart')}"/>
</isif>

SFRA의 경우

SFCC의 표준 통합에는 pageFooter.isml에 다음 코드가 추가됩니다:

<isinclude template="klaviyo/klaviyoFooter"/>

또한 Cart.js 컨트롤러의 AddProduct 경로에 다음 코드가 추가됩니다:

 if(dw.system.Site.getCurrent().getCustomPreferenceValue('klaviyo_enabled')){
   var KlaviyoUtils = require('*/cartridge/scripts/utils/klaviyo/klaviyoUtils');
 KlaviyoUtils.trackAddToCart();
}

Site Genesis와 SFRA 모두 카트리지 폴더와 위에서 언급한 코드 스니펫을 제거한 후 코드베이스에서 "클라비요"라는 단어를 검색하는 것이 좋습니다. 코드베이스에 남아 있는 클라비요 관련 코드는 새 카트리지를 설치한 후 다시 제자리에 넣어야 할 사용자 지정 블록일 수 있으므로 제거하기 전에 어떤 기능을 하는지 잘 알고 있어야 합니다.

서비스 제거

이전 통합은 관리 > 운영 > 서비스에서 KlaviyoTrack서비스, KlaviyoTrack프로필 및 KlaviyoTrack크레딧을 생성했을 것입니다. 새로운 클라비요 카트리지를 통합하는 과정에서 다른 이름의 새 서비스가 생성되므로 세 가지 모두 안전하게 제거할 수 있습니다.

이전 서비스를 반드시 제거해야 하는 것은 아니지만 향후 혼란을 방지하기 위해 정리하는 것이 좋습니다.

사이트 기본 설정 검토

새 클라비요 카트리지를 통합하는 과정에서 이전 클라비요 사이트 환경설정 중 일부는 유지되며, 새로운 환경설정도 추가됩니다. 판매자 도구 > 사이트 기본 설정 > 사용자 지정 기본 설정 > klaviyo의 클라 비요 기본 설정 그룹에서 사이트 기본 설정을 살펴보고 웹사이트에 특별히 추가된 사용자 지정 기본 설정이 있는지 확인합니다. 카트리지를 사용자 지정하여 고유한 설정을 추가한 경우 해당 설정을 보존하고 싶을 것입니다. 참고로, 이전 클라비요 통합에 내장된 네 가지 사이트 환경 설정은 다음과 같습니다:

• 클라비요 사용(ID: klaviyo_enabled)
  클라비요가 켜져 있는지 또는 꺼져 있는지 플래그를 지정합니다.
• 클라비요 계정(ID: klaviyo_account)
  클라비요 공개 API 키 또는 사이트 ID.
• 클라비요 비공개 API 키(ID: klaviyo_api_key)
  클라비요 비공개 API 키입니다.
• 클라비요용 이미지 유형(ID: klaviyo_image_size)
  대형, 소형, 썸네일 등.

새 카트리지를 설정하기 전에 관리 > 사이트 개발 > 사이트 가져오기 & 내보내기에서 현재 사이트 기본 설정을 내보내 백업해 두는 것이 좋습니다. 사이트를 확장한 다음 사이트 이름을 확장하고 사이트 기본 설정 상자를 선택한 다음 내보낼 파일 이름을 입력합니다. 현재 클라비요 기본 설정은 나중에 새 카트리지를 설치할 때 부정적인 영향을 받지 않지만, 나중에 참조할 수 있도록 백업해 두는 것이 좋습니다.

카트리지 경로에서 클라비요 카트리지를 제거합니다.

관리 > 사이트 > 사이트 관리 > [사이트 이름] > 설정에서 카트리지 경로에서 int_klaviyo_core 및 int_klaviyo(사이트 제네시스) 또는 int_klaviyo_sfra(SFRA)를 제거합니다. 이 단계를 수행하지 않으면 SFCC가 더 이상 존재하지 않는 로드할 카트리지를 찾는 데 따른 오류가 발생합니다.

개발자 콘솔 및 서버 측 로그에서 오류를 확인합니다.

이 시점에서 코드베이스에 더 이상 클라비요 코드가 없어야 합니다. 프런트엔드를 검토하고 검색 결과, PLP, PDP 등의 페이지를 방문하여 장바구니에 제품 추가, 입력, 결제 완료 등의 작업을 수행하는 것이 좋습니다. 이 과정에서 개발자 콘솔을 주시하여 새로운 오류가 생성되는지 확인하세요. 요청 로그에서도 동일하게 수행합니다. 클라비요와 관련된 새로운 오류가 표시된다면 이전 클라비요 코드를 모두 완전히 제거하지 않았을 가능성이 높습니다. 새로운 오류의 원인을 추적하여 제거하기 전에 메모해 두는 것이 중요합니다.

새 클라비요 카트리지 설치

Salesforce Commerce Cloud 시작하기에 설명된 단계에 따라 새 카트리지를 코드베이스에 통합합니다. 완료하지 않아도 되는 단계가 있을 수 있지만(예: SFCC 인스턴스에 OCAPI 부분에 대한 연결이 이미 설정되어 있을 수도 있고 아닐 수도 있음), 일반적으로 각 통합 단계를 따라야 합니다. 클라비요 카트리지를 모두 교체하고 코드 스니펫을 다시 추가해야 합니다. 

메타데이터.zip을 가져온 후 참고하세요, 를 사용하면 이전 버전의 카트리지에서 생성된 4개의 사이트 환경설정 외에 4개의 새로운 사이트 환경설정을 사용할 수 있습니다. 새 환경설정을 가져와도 이전 환경설정이 영향을 받지 않아야 하지만, 계속 진행하기 전에 모든 클라비요 사이트 환경설정이 올바른지 다시 한 번 확인하는 것이 좋습니다.

버전 23.7.0 이전 카트리지에서 업그레이드하는 것이므로 새 사이트 기본 설정에서 이벤트 레이블을 SFCC로 지정하고 카트에 추가 이벤트 전송을 '장바구니에 추가'로 각각 아니요 및 예로 설정해야 합니다. 이렇게 하면 Salesforce Commerce Cloud 메트릭 레이블 없이 이벤트를 계속 전송하고 새로운 장바구니에 추가 됨이 아닌 장바구니에 추가됨 이벤트 유형을 사용합니다. 이 두 사이트 환경설정이 잘못 설정되면 보고가 중단되고 잠재적으로 클라비요의 기존 흐름이 중단될 수 있습니다.

모든 기본 제공 이벤트가 작동하는지 확인합니다.

이전 연동에서 사용자 지정한 내용을 다시 추가하기 전에 새로 설치한 클라비요 카트리지가 올바르게 작동하는지 확인해야 합니다. 프론트엔드를 사용하여 검색된 사이트, 본 카테고리, 본 제품, 장바구니에 추가, 결제 시작 및 주문 확인에 대한 이벤트를 생성한 다음 클라비요 계정을 확인하여 이러한 이벤트가 올바르게 추적되고 있는지 확인합니다. 

개발자 콘솔에서 클라비요 이벤트를 생성하는 모든 페이지에서 연동과 관련된 새로운 오류가 있는지 확인하세요. 관리 > 운영 > 서비스 > 클라비요이벤트서비스 - 세부정보에서 통신 로그 사용 확인란을 선택하여 자세한 서비스 로깅을 활성화한 다음 서버 측 로그 파일을 검토하여 오류가 없는지, 각 이벤트 유형에 대해 이벤트 데이터가 제대로 생성되고 있는지 확인합니다.

이벤트 데이터와 프로덕션 데이터 비교

이제 테스트 계정과 프로덕션 클라비요 계정의 이벤트 데이터를 비교하여 누락된 것이 없는지, 현재 값이 예상 유형과 일치하는지 확인해야 합니다. 새로운 통합으로 인해 보고 또는 흐름이 영향을 받을지 여부를 파악하는 것이 중요합니다. 이전 카트리지 버전에 비해 추가 속성이 설정되어 클라비요로 전송되는 것을 확인할 수 있습니다. 

다시 사이트별 사용자 정의 추가

이제 클라비요 코드에 사용자 지정 기능을 다시 추가할 수 있습니다. 최신 클라비요 카트리지에는 구조 및 아키텍처 변경 사항이 많기 때문에 사용자 지정 코드를 복사하여 클라비요 카트리지에 직접 붙여넣을 수 없을 것입니다.

클라비요 카트리지의 각 이벤트 유형에는 각 이벤트 유형에 대해 이름이 지정된 별도의 스크립트 파일에 있는 getData 함수가 있습니다. 이러한 파일은 int_klaviyo_core/cartridge/scripts/klaviyo/eventData 폴더에서 찾을 수 있으며, 각 이벤트에 대해 전달되는 데이터 객체를 추가하거나 업데이트하기 위해 가장 많이 변경할 수 있는 곳입니다. 새 사용자 정의 이벤트를 만드는 경우, 새 이벤트 전용 스크립트 파일에서 getData 함수를 호출하는 코드를 서버 측 컨트롤러에 추가하는 기존 패턴 (예: SiteGen에서 직접 또는 SFRA의 server.append를 통해)을 따르고, 트랙 이벤트 함수를 사용하여 KlaviyoEventService를 통해 해당 데이터를 Klaviyo에 전송하는 것이 좋습니다.

결과

이제 Salesforce Commerce Cloud용 클라비요 카트리지를 업그레이드했습니다. 

추가 자료 

• Salesforce 상거래 클라우드 시작하기
• Salesforce 상거래 클라우드 데이터 참조
• 통합 참조 동기화 빈도
• 지원팀에 문의하는 방법