Salesforce Commerce Cloud 카트리지를 업그레이드하는 방법

학습 내용

Klaviyo Salesforce Commerce Cloud 카트리지를 업그레이드하는 방법을 알아보세요.

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

시작하기 전에 알아야 할 것

버전 23.7.0에는 여러 가지 의미 있는 개선 사항이 포함되어 있으며, 그중 일부는 이벤트가 트리거되는 방식과 관련된 아키텍처 변경 사항이에요. 23.70 미만 버전에서 23.70 초과 버전으로 업그레이드할 때의 특별 고려 사항은 아래에 자세히 설명되어 있어요.

현재 연동을 이해하세요

현재 SFCC 연동과 웹사이트에 맞게 구체적으로 어떤 변경 또는 사용자 지정이 이루어졌는지 잘 파악하는 것이 중요해요. 가장 중요한 것은 Klaviyo로 전송하는 특정 이벤트 데이터가 변경되었거나 보강되었는지, 그리고 맞춤 이벤트를 추가했는지 여부를 고려하는 거예요.

이벤트 데이터를 조합하는 코드를 Klaviyo 카트리지의 이전 버전( Klaviyo의 Github에서 이용 가능)과 비교해 보시는 것을 권장합니다. 연동이 크게 사용자 지정되지 않았다고 가정하면 현재 데이터 조립 함수를 int_klaviyo_core/cartridge/scripts/utils/klaviyo/klaviyoUtils.js에서 확인할 수 있으며, Order Confirmation의 경우 int_klaviyo_core/cartridge/scripts/utils/klaviyo/emailUtils.js에서 확인할 수 있어요.

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

SFCC 샌드박스를 Klaviyo 테스트 계정에 연결

아직 SFCC 프로덕션 환경에 연결된 계정과는 별도로 테스트용 보조 Klaviyo 계정을 만들지 않았다면, 만들어 두는 것이 좋아요. 그런 다음 SFCC 샌드박스 환경을 새 계정에 연결하세요. 이전 Klaviyo 카트리지 버전을 사용해 이 단계를 완료하는 것을 권장해요. 그러면 새 Klaviyo 카트리지로 코드베이스를 업그레이드하기 전에 이벤트가 보조 Klaviyo 계정으로 성공적으로 전송되고 수신되는지 확인할 수 있어요.

이전 Klaviyo 카트리지 코드를 제거하세요.

연동을 크게 맞춤 설정하지 않았다면, 코드베이스에서 두 Klaviyo cartridge 폴더(int_klaviyo_core 및 int_klaviyo(Site Genesis용) 또는 int_klaviyo_sfra(SFRA용))를 삭제하기만 하면 이전 Klaviyo 연동의 대부분을 제거할 수 있어요. 하지만 템플릿 파일과 경우에 따라 JavaScript 파일에 추가됐을 수 있는 Klaviyo 관련 코드도 모두 제거해야 해요.

Site Genesis용

Site Genesis용 Standard 연동에는 footer_UI.isml에 다음 코드가 추가돼요:

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

또한 다음 블록이 minicart.isml에 추가돼요, cart.isml 및 기타 모든 “cart” isml 파일:

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

SFRA용

SFCC용 Standard 연동에는 다음 코드가 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 모두에서 카트리지 폴더와 위에 언급된 코드 조각을 제거한 후에는 코드베이스에서 “Klaviyo”라는 단어를 검색하는 것이 좋습니다. 새 카트리지를 설치한 뒤 다시 적용해야 할 사용자 지정 설정을 나타낼 수 있으므로, 제거하기 전에 코드베이스에 남아 있는 모든 Klaviyo 관련 코드가 어떤 역할을 하는지 반드시 파악해 두세요.

서비스 제거

이전 연동을 통해 Administration > Operations > Service에서 KlaviyoTrackService, KlaviyoTrackProfile, KlaviyoTrackCredentials가 생성되었을 거예요. 새 Klaviyo 카트리지를 통합하는 과정에서 이름이 다른 새 서비스가 생성되므로, 이 세 가지는 모두 안전하게 제거할 수 있어요.

기존 서비스를 제거하는 것이 필수는 아니지만, 향후 혼동을 피하기 위해 정리해 두는 것을 권장해요.

리뷰 사이트 환경 설정 검토

새 Klaviyo 카트리지를 통합하는 과정에서는 이전 Klaviyo 사이트 환경설정의 일부가 유지되고, 새로운 설정도 일부 추가돼요. Merchant tools > Site Preferences > Custom Preferences > klaviyo 에서 Klaviyo 기본 설정 그룹의 사이트 기본 설정을 확인하고, 웹사이트에 대해 특별히 추가된 사용자 지정 기본 설정이 있는지 확인해 주세요. 사용자 설정을 추가하기 위해 cartridge를 사용자 지정했다면 해당 설정을 유지하는 것이 좋아요. 참고로 이전 Klaviyo 연동에 기본으로 포함된 사이트 기본 설정은 다음 4가지예요.

• Klaviyo Enabled (ID: klaviyo_enabled)
  Klaviyo가 켜져 있는지 또는 꺼져 있는지 표시하는 플래그입니다.
• Klaviyo 계정(ID: klaviyo_account)
  Klaviyo 공개 API 키 또는 사이트 ID입니다.
• Klaviyo 비공개 API 키(ID: klaviyo_api_key)
  Klaviyo 비공개 API 키입니다.
• Klaviyo용 이미지 유형(ID: klaviyo_image_size)
  Large, small, thumbnail 등

새 카트리지를 설정하기 전에 Administration > Site Development > Site Import & Export에서 내보내 현재 사이트 환경설정을 백업하는 것을 권장해요. Sites를 확장한 다음 Site Name을 선택하고, 파일 이름을 입력해 내보내기 전에 사이트 환경설정 확인란을 선택하세요. 나중에 새 카트리지를 설치하더라도 현재 Klaviyo 환경설정이 불리하게 영향을 받지는 않겠지만, 나중에 참고할 수 있도록 백업해 두는 것이 좋아요.

카트리지 경로에서 Klaviyo 카트리지를 제거해 주세요.

Administration > Sites > Manage Sites > [Site Name] > Settings의 카트리지 경로에서 int_klaviyo_core와 int_klaviyo(Site Genesis) 또는 int_klaviyo_sfra(SFRA) 중 하나를 제거해 주세요. 이 단계를 수행하지 않으면, 더 이상 존재하지 않는 카트리지를 로드하려고 SFCC가 검색하면서 오류가 발생해요.

오류가 있는지 개발자 콘솔과 서버 측 로그를 확인해 주세요.

이 단계에서는 더 이상 코드베이스에 Klaviyo 코드가 없어야 합니다. 프론트엔드를 검토하고 검색 결과, PLP, PDP와 같은 페이지를 방문하고 장바구니에 제품 추가, 입력 및 결제 완료와 같은 작업을 수행하는 것이 좋습니다. 이렇게 할 때 개발자 콘솔을 주시하여 새로운 오류가 생성되었는지 확인합니다. 요청 로그에서도 동일한 작업을 수행합니다. Klaviyo와 관련된 새 오류가 표시되는 경우 이전 Klaviyo 코드를 모두 완전히 제거하지 않았을 가능성이 높습니다. 새로운 오류의 출처를 추적하고 제거하기 전에 기록해 두는 것이 중요합니다.

새 Klaviyo cartridge 설치

Salesforce Commerce Cloud 시작하기에 안내된 단계에 따라 새 카트리지를 코드베이스에 연동해요. 예를 들어 SFCC 인스턴스에 OCAPI 부분에 대해 이미 연결이 설정되어 있을 수도, 없을 수도 있으므로 완료할 필요가 없는 단계가 있을 수 있어요. 하지만 일반적으로 연동의 각 단계를 따라야 해요. Klaviyo 카트리지를 둘 다 교체하고 코드 조각을 다시 추가해야 해요.

metadata.zip을 가져온 후, 이전 버전의 카트리지가 만든 4개에 더해, 새 사이트 기본 설정 4개가 추가돼요. 새 기본 설정을 가져와도 기존 기본 설정은 영향을 받지 않아야 하지만, 계속 진행하기 전에 모든 Klaviyo 사이트 기본 설정이 올바른지 다시 확인하는 것이 좋아요.

23.7.0 버전 이전의 카트리지에서 업그레이드하는 경우, 새 사이트 기본 설정인 Label Events as SFCC 및 Send Added To Cart Event as ‘Add To Cart’는 각각 No 및 Yes로 설정되어야 해요. 그러면 Salesforce Commerce Cloud 지표 레이블 없이도 이벤트 전송이 계속되며, (새 Added to Cart가 아니라) Add To Cart 이벤트 유형을 사용하게 돼요. 이 두 가지 사이트 기본 설정이 잘못 설정되면 보고가 중단되고, Klaviyo의 기존 플로우도 중단될 가능성이 있어요.

기본 제공 이벤트가 모두 제대로 작동하는지 확인해 주세요.

이전 연동에서 가져온 사용자 지정 항목을 다시 추가하기 전에, 새로 설치한 Klaviyo 카트리지가 제대로 작동하는지 반드시 확인해 주세요. 프런트엔드를 사용해 Searched Site, Viewed Category, Viewed Product, Added To Cart, Started Checkout, Order Confirmation 이벤트를 생성한 다음, Klaviyo 계정에서 이러한 이벤트가 올바르게 추적되고 있는지 확인해 주세요.

Klaviyo 이벤트를 생성하는 모든 페이지에서 연동과 관련될 수 있는 새로운 오류가 있는지 개발자 콘솔을 확인해 주세요. Administration > Operations > Services > KlaviyoEventService - Details 에서 Communication Log Enabled 확인란을 선택해 자세한 서비스 로깅을 활성화한 다음, 서버 측 로그 파일을 검토해 오류가 없는지, 그리고 이벤트 유형별로 이벤트 데이터가 제대로 생성되고 있는지 확인해 주세요.

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

이제 테스트 및 프로덕션 Klaviyo 계정의 이벤트 데이터를 비교해 누락된 항목이 없는지, 현재 값이 예상된 유형과 일치하는지 확인해야 해요. 새 연동으로 인해 어떤 보고 또는 플로우가 영향을 받을지 판단하는 것이 중요해요. 이전 카트리지 버전과 비교했을 때 추가 속성이 이제 설정되어 Klaviyo로 전송되는 것을 확인할 수 있어요.

사이트별 커스텀 설정 추가

이제 사용자 지정 설정을 Klaviyo 코드에 다시 추가할 수 있어요. 최신 Klaviyo 카트리지에는 구조 및 아키텍처 변경 사항이 많이 포함되어 있어 사용자 지정 코드를 Klaviyo 카트리지에 직접 복사하여 붙여넣기만 하기는 어려울 수 있어요.

Klaviyo 카트리지의 각 이벤트 유형에는 각 이벤트 유형의 이름을 딴 별도의 스크립트 파일에 있는 getData 함수가 있어요. 이 파일은 int_klaviyo_core/cartridge/scripts/klaviyo/eventData 폴더에서 찾을 수 있으며, 각 이벤트에 대해 전달되는 데이터 오브젝트를 추가하거나 업데이트하기 위해 수정할 가능성이 가장 높은 위치예요. 새 맞춤 이벤트를 생성하는 경우, 새 이벤트 전용 스크립트 파일의 getData 함수를 호출하는 코드를 서버 측 컨트롤러((예: SiteGen에서 직접 또는 SFRA에서 server.append를 통해)에 추가한 다음, trackEvent 함수를 사용해 KlaviyoEventService를 통해 해당 데이터를 Klaviyo로 전송하는 기존 패턴을 따르는 것을 권장해요.

결과

이제 Salesforce Commerce Cloud용 Klaviyo 카트리지를 업그레이드했어요.

추가 자료