Upcart V2.0 마이그레이션 가이드

개요

Upcart V2.0 모듈은 장바구니 시스템의 완전한 아키텍처 재설계를 도입해요. 이번 업데이트는 성능 개선, 향상된 사용자 지정, 더 나은 유지 관리성에 중점을 두고 있어요. 이 가이드는 V1.0에서 V2.0 모듈로 마이그레이션할 때 무엇이 변경되는지, 어떤 호환성 문제가 발생할 수 있는지, 그리고 기존 사용자 지정을 안전하게 업데이트하는 방법을 이해하는 데 도움을 줄 거예요.

주요 변경 사항 - CSS 클래스 이름 변경

V1 클래스(사용 중단)

🚨 다음 V1.0 클래스 이름은 V2.0에서 더 이상 지원되지 않아요:

.styles_Header__  
.styles_ProductRow__  
.styles_Rewards__  
.styles_TieredRewards__  
...

품절 경고 클래스인 upcart-quantity-warning과 upcart-quantity-warning-text 역시 변경되지 않았어요. 이 클래스들은 버전이 지정된 모듈이 아닌 장바구니 이니셜라이저에서 나오기 때문에 모듈이 V1이든 V2든 동일하게 출력돼요.

.styles_CartPreview__card__는 이 목록에 없어요 — 버전과 관계없이 모든 모듈 주위에 렌더링되는 공유 카트 셸 래퍼이므로, 이를 대상으로 하는 규칙은 V2에서도 계속 작동해요. 리워드 클래스는 .styles_Rewards__(단순 바)와 .styles_TieredRewards__(단계별 바)이며, .styles_RewardsModule__은 존재하지 않아요.

/*******************  
*** Cart Header ***  
*******************/  
'upcart-header',  
'upcart-header-text',  
'upcart-header-logo',  
'upcart-header-close-button',  
'upcart-header-close-button-icon',  
  
/******************  
*** Line Items ***  
******************/  
'upcart-products-section',  
'upcart-product-item',  
/** > Title */  
'upcart-product-title',  
'upcart-product-title-link',  
/** > Prices */  
'upcart-item-prices-row',  
'upcart-item-price',  
'upcart-item-compare-price',  
'upcart-product-savings',  
/** > Options/Variants */  
'upcart-item-option',  
'upcart-item-option-category',  
'upcart-item-option-value',  
/** > Bundle Item Components */  
'upcart-bundle-item-image-wrapper',  
'upcart-bundle-item-product-title',  
'upcart-bundle-item-variant-title',  
'upcart-bundle-detail-toggle',  
/** > Properties */  
'upcart-item-properties',  
'upcart-item-property',  
'upcart-item-property-subscription',  
/** > Quantity Selector */  
'upcart-product-quantity-input',  
'upcart-product-quantity-minus',  
'upcart-product-quantity-plus',  
/** > Image */  
'upcart-product-image-wrapper',  
  
/*********************  
*** Announcements ***  
*********************/  
'upcart-announcement',  
  
/***************  
*** Rewards ***  
***************/  
'upcart-rewards',  
'upcart-rewards-message',  
'upcart-rewards-bar-background',  
'upcart-rewards-bar-foreground',  
'upcart-rewards-tier',  
'upcart-rewards-tier-circle',  
'upcart-rewards-tier-icon',  
'upcart-rewards-tier-description',  
  
/***************  
*** Upsells & Recommendations ***  
***************/  
'upcart-upsells-module',  
'upcart-upsells-title',  
'upcart-upsells-button',  
'upcart-upsell-item-title',  
'upcart-upsell-item-card',  
'upcart-upsell-item-image-wrapper',  
'upcart-upsell-item-image',  
'upcart-upsell-item-price',  
'upcart-upsell-item-price-row',  
'upcart-upsell-item-compare-price',  
'upcart-upsell-item-variant-selector',  
'upcart-upsells', // deprecated  
'upcart-recommendation-module',  
'upcart-recommendations-title',  
'upcart-recommendations-shop-now-button',  
  
/***************  
*** Add-ons ***  
***************/  
'upcart-addons',  
'upcart-addons-title',  
'upcart-addons-product-description',  
'upcart-addons-price',  
'upcart-addons-compare-price',  
'upcart-addons-toggle',  
'upcart-addons-image-wrapper',  
  
/**********************  
*** Discount Codes ***  
**********************/  
'upcart-discount-code-row',  
'upcart-discount-code-module',  
'upcart-discount-code-button',  
'upcart-discount-code-input',  
'upcart-discount-code-badge',  
'upcart-discount-code-icon',  
'upcart-discount-code-text',  
'upcart-discount-code-input-wrapper',  
  
/*****************************  
*** Subscription Upgrades ***  
*****************************/  
'upcart-subscription-upgrade-section',  
'upcart-subscription-upgrade-button',  
'upcart-subscription-upgrade-dropdown',  
  
/***************************  
*** Express Pay Buttons ***  
***************************/  
'upcart-express-pay-buttons-container',  
'upcart-express-pay-buttons-row',  
'upcart-express-pay-button',  
'upcart-express-pay-button-shop-pay',  
'upcart-express-pay-button-google-pay',  
'upcart-express-pay-button-paypal',  
'upcart-express-pay-button-apple-pay',  
'upcart-express-pay-button-amazon-pay',  
'upcart-express-pay-button-meta-pay',  
  
/********************  
*** Trust Badges ***  
********************/  
'upcart-trust-badge',  
'upcart-trust-badge-image',  
  
/********************  
*** Integrations ***  
********************/  
'upcart-integration-zapiet-pickup',  
  
/*****************  
*** Skeletons ***  
*****************/  
'upcart-skeleton',  
'upcart-product-item-skeleton',  
'upcart-product-image-skeleton',  
'upcart-product-title-skeleton',  
'upcart-item-option-skeleton',  
'upcart-product-quantity-skeleton',  
'upcart-product-price-container-skeleton',  
'upcart-announcement-skeleton',  
'upcart-rewards-skeleton',  
'upcart-rewards-message-skeleton',  
'upcart-rewards-bar-skeleton',  
'upcart-upsells-module-skeleton',  
'upcart-upsells-title-skeleton',  
'upcart-upsell-item-image-skeleton',  
'upcart-upsell-item-title-skeleton',  
'upcart-upsell-item-price-skeleton',  
'upcart-upsells-button-skeleton',  
'upcart-trust-badge-skeleton',  
'upcart-trust-badge-image-skeleton',  
'upcart-checkout-button-container-skeleton',  
'upcart-checkout-button-skeleton',  
'upcart-addons-skeleton',  
'upcart-addons-image-wrapper-skeleton',  
'upcart-addons-skeleton-text-container',  
'upcart-discount-code-module-skeleton',  
'upcart-discount-code-input-skeleton',  
'upcart-discount-code-button-skeleton',  
'upcart-express-pay-buttons-container-skeleton',  
'upcart-express-pay-button-skeleton'

V2.0 클래스(새 시스템)

V2.0은 internal 및 public 클래스 접두사가 있는 구조화된 이름 지정 시스템을 도입해요.

Internal 클래스 이름

이 클래스들은 내부용으로 예약되어 있으며 예고 없이 변경될 수 있어요. 이 클래스를 재정의하면 향후 호환성이 보장되지 않아요.

/* Internal classes - for Upcart's internal styling */   
.upcart-internal-header  
.upcart-internal-header__close-button  
.upcart-internal-cart-items  
.upcart-internal-rewards  
...

Public 클래스 이름

🚨 사용 가능한 public 클래스 이름 목록

/*******************  
***** Skeleton *****  
*******************/  
'upcart-public-skeleton'  
  
/*******************  
****** Header ******  
*******************/  
'upcart-public-header'  
'upcart-public-header__close-button'  
'upcart-public-header__close-button-icon'  
  
/*******************  
*** Announcement ***  
*******************/  
'upcart-public-announcement'  
  
/*******************  
** Recommendation **  
****** Upsell ******  
*******************/  
'upcart-public-component-upsell-tile'  
'upcart-public-component-upsell-tile__image-container'  
'upcart-public-component-upsell-tile__image'  
'upcart-public-component-upsell-tile__info'  
'upcart-public-component-upsell-tile__title-link'  
'upcart-public-component-upsell-tile__title'  
'upcart-public-component-upsell-tile__rating-row'  
'upcart-public-component-upsell-tile__stars'  
'upcart-public-component-upsell-tile__star--partial'  
'upcart-public-component-upsell-tile__reviews'  
'upcart-public-component-upsell-tile__price-row'  
'upcart-public-component-upsell-tile__price-compare-at'  
'upcart-public-component-upsell-tile__price'  
'upcart-public-component-upsell-tile__variant-row'  
'upcart-public-component__button'  
'upcart-public-component-loader'  
'upcart-public-upsell__skeleton'  
'upcart-public-upsell__skeleton-title'  
'upcart-public-upsell__skeleton-image'  
'upcart-public-upsell__skeleton-product-title'  
'upcart-public-upsell__skeleton-product-price'  
  
/*******************  
****** Notes *******  
*******************/  
'upcart-public-notes'  
'upcart-public-component-collapse__dropdown-container'  
'upcart-public-component-collapse__expand-icon'  
'upcart-public-notes__text-container'  
'upcart-public-notes__textarea'  
  
/*******************  
** Discount Code ***  
*******************/  
'upcart-public-discount-code'  
'upcart-public-discount-code__form'  
'upcart-public-discount-code__input-wrapper'  
'upcart-public-discount-code__input'  
'upcart-public-discount-code__suffix'  
'upcart-public-discount-code__error'  
'upcart-public-discount-code__button'  
'upcart-public-component__button'  
'upcart-public-skeleton'  
'upcart-public-discount-code__skeleton'  
'upcart-public-discount-code__skeleton-input'  
'upcart-public-discount-code__skeleton-button'  
  
/*******************  
** Trust Badges ****  
*******************/  
'upcart-public-trust-badges'  
'upcart-public-trust-badges__image'  
  
/*******************  
** Tiered Rewards **  
*******************/  
'upcart-public-rewards'  
'upcart-public-rewards__message'  
'upcart-public-rewards__bar'  
'upcart-public-component-segmented-progress-bar'  
'upcart-public-component-segmented-progress-bar__segments-container'  
'upcart-public-component-segmented-progress-bar__segment'  
'upcart-public-component-segmented-progress-bar__segment-fill'  
'upcart-public-component-segmented-progress-bar__milestone'  
'upcart-public-component-segmented-progress-bar__milestone--bottom'  
'upcart-public-component-segmented-progress-bar__milestone--top'  
'upcart-public-component-segmented-progress-bar__milestone--middle'  
'upcart-public-component-segmented-progress-bar__milestone-icon'  
'upcart-public-component-segmented-progress-bar__milestone-label'  
'upcart-public-component-segmented-progress-bar__milestone-label--align-right'  
'upcart-public-component-segmented-progress-bar__milestone-label--align-center'  
'upcart-public-rewards__skeleton',  
'upcart-public-rewards__skeleton-message',  
'upcart-public-rewards__skeleton-bar',  
  
/*******************  
**** Cart Items ****  
*******************/  
'upcart-public-component-product-tile'  
'upcart-public-component-product-tile__content'  
'upcart-public-component-product-tile__image-wrapper'  
'upcart-public-component-product-tile__image'  
'upcart-public-component-product-tile__info'  
'upcart-public-component-product-tile__header'  
'upcart-public-component-product-tile__product-title'  
'upcart-public-component-product-tile__title-link'  
'upcart-public-component-product-tile__remove-button'  
'upcart-public-component-loader'  
'upcart-public-component-product-tile__variant'  
'upcart-public-component-product-tile__properties'  
'upcart-public-component-product-tile__bundle'  
'upcart-public-component-product-tile__product-pricing'  
'upcart-public-component-product-tile__price-compare-at'  
'upcart-public-component-product-tile__price'  
'upcart-public-component-product-tile__savings'  
'upcart-public-component-product-tile__controls'  
'upcart-public-component-product-tile__quantity-selector'  
'upcart-public-component-product-tile__quantity-minus'  
'upcart-public-component-product-tile__quantity-plus'  
'upcart-public-component-product-tile__discount-codes'  
'upcart-public-component-tag'  
'upcart-public-component-tag__icon'  
'upcart-public-component-tag__text'  
'upcart-public-component-product-tile__subscription-upgrade'  
'upcart-public-component__button'  
'upcart-public-component-product-tile__select-wrapper'  
'upcart-public-component-product-tile__select'  
'upcart-public-product-properties__subscription'  
'upcart-public-product-properties__item'  
'upcart-public-product-properties__link'  
'upcart-public-cart-items__key-value-pair'  
'upcart-public-bundle-properties'  
'upcart-public-bundle-properties__variant-title'  
'upcart-public-component-collapse__dropdown-container'  
'upcart-public-bundle-properties__header'  
'upcart-public-component-collapse__expand-icon'  
'upcart-public-notes__text-container'  
'upcart-public-bundle-properties__item-components'  
'upcart-public-bundle-properties__item-component-row'  
'upcart-public-bundle-properties__image-wrapper'  
'upcart-public-bundle-properties__content'  
'upcart-public-bundle-properties__product-title'  
'upcart-public-upsell__skeleton'  
'upcart-public-upsell__skeleton-title'  
'upcart-public-upsell__skeleton-image'  
'upcart-public-upsell__skeleton-product-title'  
'upcart-public-upsell__skeleton-product-price'  
  
/*******************  
***** Add-ons ******  
*******************/  
'upcart-public-addons'  
'upcart-public-addons__image-wrapper'  
'upcart-public-addons__content-wrapper'  
'upcart-public-addons__content-title-wrapper'  
'upcart-public-addons__content-title'  
'upcart-public-addons__content-price'  
'upcart-public-addons__compare-at-price'  
'upcart-public-addons__price'  
'upcart-public-addons__content-description'  
'upcart-public-addons__toggle-wrapper'  
'upcart-public-addons__toggle'  
'upcart-public-addons__toggle-switch'  
'upcart-public-addons__toggle-slider'  
'upcart-public-skeleton'  
'upcart-public-addons__skeleton'  
'upcart-public-addons__skeleton-image'  
'upcart-public-addons__skeleton-text'  
  
/*******************  
*** Cart summary ***  
*******************/  
'upcart-public-cart-summary'  
'upcart-public-cart-summary__discount-codes'  
'upcart-public-cart-summary__discount-label'  
'upcart-public-cart-summary__slide-codes'  
'upcart-public-cart-summary__total-discount'

이 클래스들은 public 스타일링 API(upcart-public-)의 일부이며, 사용자 지정 디자인을 위해 안전하게 재정의할 수 있어요.

.upcart-public-header  
.upcart-public-header__close-button  
.upcart-public-rewards  
...

✅ 해야 할 것

스타일링에는 upcart-public- 클래스 이름만 사용하세요.

/* ✅ Correct usage */  
.upcart-public-header {     
  font-size: 18px;  
  font-weight: bold;   
}

❌ 하지 말아야 할 것

internal 클래스 이름 재정의를 피하세요

/* ❌ Avoid this */  
.upcart-internal-header {     
  font-size: 18px;  
  font-weight: bold;   
}

깊거나 커스텀한 셀렉터로 특정 노드를 대상으로 하는 것을 피하세요.

/* ❌ Avoid this */  
.upcart-public-upsell div a {     
  font-size: 18px;  
  font-weight: bold;   
}

데이터 속성 시스템

V2.0은 향상된 타겟팅과 고급 사용자 지정을 위한 구조화된 데이터 속성 시스템을 도입해요.

<!-- V2 data attributes for targeting -->   
<div data-upcart-chunk="header-title-content" />     
<div data-internal-properties="hasNonDefaultTitleAlignment=true" />       
<div data-placement="topOfFooter" />

이러한 속성을 사용하면 코드 명확성을 유지하면서 유연한 데이터 기반 템플릿을 더 쉽게 만들 수 있어요.

템플릿 변수 변경 사항

V2 모듈은 이중 중괄호 {{ }}를 사용하는 새로운 템플릿 변수 문법을 사용해요.

공지사항 모듈

V1.0: `{TIMER}`
V2.0: `{{timer}}`

단계별 리워드 모듈

V1.0: `{AMOUNT}` → V2: `{{amount}}`
V1.0: `{COUNT}` → V2: `{{count}}`

마이그레이션 프로세스

1. 현재 구성 백업하기

변경하기 전에 기존 커스텀 CSS 및 HTML 파일을 백업하세요.

2. 샌드박스 모드에서 테스트하기

라이브로 전환하기 전에 샌드박스 모드를 사용하여 업데이트된 장바구니를 설정하고 새 모듈을 안전하게 테스트하세요.

V2.0을 사용한 고급 사용자 지정

커스텀 템플릿

V2.0 모듈은 레이아웃과 구조를 완벽하게 제어하려는 판매자를 위해 완전한 커스텀 템플릿을 지원해요. 커스텀 템플릿을 활성화하려면:

Settings > Cart settings로 이동하여 Advanced Settings를 펼치고 Access custom templates를 체크하세요. 이 체크박스는 Cart settings 탭 자체가 아니라 해당 접힌 섹션 안에 있어요.
기능 토글을 활성화하세요.
문법과 예시는 Upcart의 개발자 문서를 참고하세요.

Upcart 장바구니 설정에서 설명과 함께 활성화된 Access custom templates 체크박스

참고: Upcart 지원팀은 커스텀 템플릿의 개발, 디버깅 또는 문제 해결을 지원할 수 없어요.

모범 사례

항상 샌드박스 모드에서 먼저 업데이트를 테스트하세요.
사용자 지정을 점진적으로 마이그레이션하고 업데이트하세요.
스타일링에는 internal 클래스 대신 public 클래스를 사용하세요.
라이브 설정을 업데이트하기 전에 이전 버전을 모두 백업해 두세요.

향후 고려 사항

V2 모듈은 앞으로도 새로운 기능, 최적화 및 업데이트를 계속 받을 거예요.
V1 모듈은 이제 제한된 지원과 신규 기능 없이 유지 보수 모드에 있어요.
완전한 호환성을 위해 가능한 한 빨리 V2로 마이그레이션하는 것을 권장해요.

장바구니 기능 참조

CSS 참조

스타일링 레시피

기능 레시피

사용자 지정 템플릿

Upcart 공개 API

Upcart V2.0 마이그레이션 가이드

개요

주요 변경 사항 - CSS 클래스 이름 변경

V1 클래스(사용 중단)

V2.0 클래스(새 시스템)

Internal 클래스 이름

Public 클래스 이름

✅ 해야 할 것

❌ 하지 말아야 할 것

데이터 속성 시스템

템플릿 변수 변경 사항

공지사항 모듈

단계별 리워드 모듈

마이그레이션 프로세스

1. 현재 구성 백업하기

2. 샌드박스 모드에서 테스트하기

V2.0을 사용한 고급 사용자 지정

커스텀 템플릿

모범 사례

향후 고려 사항

​개요

​주요 변경 사항 - CSS 클래스 이름 변경

​V1 클래스(사용 중단)

​V2.0 클래스(새 시스템)

​Internal 클래스 이름

​Public 클래스 이름

​

​✅ 해야 할 것

​❌ 하지 말아야 할 것

​데이터 속성 시스템

​템플릿 변수 변경 사항

​공지사항 모듈

​단계별 리워드 모듈

​마이그레이션 프로세스

​1. 현재 구성 백업하기

​2. 샌드박스 모드에서 테스트하기

​V2.0을 사용한 고급 사용자 지정

​커스텀 템플릿

​모범 사례

​향후 고려 사항

​

​

개요

주요 변경 사항 - CSS 클래스 이름 변경

V1 클래스(사용 중단)

V2.0 클래스(새 시스템)

Internal 클래스 이름

Public 클래스 이름

✅ 해야 할 것

❌ 하지 말아야 할 것

데이터 속성 시스템

템플릿 변수 변경 사항

공지사항 모듈

단계별 리워드 모듈

마이그레이션 프로세스

1. 현재 구성 백업하기

2. 샌드박스 모드에서 테스트하기

V2.0을 사용한 고급 사용자 지정

커스텀 템플릿

모범 사례

향후 고려 사항