> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> 이 문서는 Upcart V1.0에서 V2.0 모듈로 업그레이드하기 위한 마이그레이션 가이드예요. 주요 변경 사항, CSS 클래스 매핑, JavaScript 셀렉터 업데이트, 문제 해결 및 단계별 마이그레이션 프로세스를 다뤄요.

<div id="overview">
  ## 개요
</div>

Upcart V2.0 모듈은 장바구니 시스템의 완전한 아키텍처 재설계를 도입해요. 이번 업데이트는 성능 개선, 향상된 사용자 지정, 더 나은 유지 관리성에 중점을 두고 있어요.

이 가이드는 V1.0에서 V2.0 모듈로 마이그레이션할 때 무엇이 변경되는지, 어떤 호환성 문제가 발생할 수 있는지, 그리고 기존 사용자 지정을 안전하게 업데이트하는 방법을 이해하는 데 도움을 줄 거예요.

***

<div id="breaking-changes-css-classname-changes">
  ## 주요 변경 사항 - CSS 클래스 이름 변경
</div>

<div id="v1-classes-deprecated">
  ### V1 클래스(사용 중단)
</div>

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

```
.styles_Header__  
.styles_ProductRow__  
.styles_Rewards__  
.styles_TieredRewards__  
...
```

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

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

```
/*******************  
*** 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'
```

<div id="v20-classes-new-system">
  ### V2.0 클래스(새 시스템)
</div>

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

<div id="internal-classnames">
  #### Internal 클래스 이름
</div>

이 클래스들은 내부용으로 예약되어 있으며 예고 없이 변경될 수 있어요.

이 클래스를 재정의하면 향후 호환성이 보장되지 않아요.

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

<div id="public-classnames">
  #### Public 클래스 이름
</div>

🚨 사용 가능한 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  
...
```

###

<div id="dos">
  ### ✅ 해야 할 것
</div>

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

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

<div id="donts">
  ### ❌ 하지 말아야 할 것
</div>

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;   
}
```

***

<div id="data-attribute-system">
  ## 데이터 속성 시스템
</div>

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

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

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

***

<div id="template-variable-changes">
  ## 템플릿 변수 변경 사항
</div>

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

<div id="announcement-module">
  ## 공지사항 모듈
</div>

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

<div id="tiered-rewards-module">
  ## 단계별 리워드 모듈
</div>

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

***

<div id="migration-process">
  ## 마이그레이션 프로세스
</div>

<div id="1-backup-current-configuration">
  #### 1. 현재 구성 백업하기
</div>

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

<div id="2-test-in-sandbox-mode">
  #### 2. 샌드박스 모드에서 테스트하기
</div>

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

***

<div id="advanced-customization-with-v20">
  ## V2.0을 사용한 고급 사용자 지정
</div>

<div id="custom-templates">
  ### 커스텀 템플릿
</div>

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

커스텀 템플릿을 활성화하려면:

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

<img src="https://mintcdn.com/aftersell/uVGuDiyXpd6WOLO4/images/upcart/v2-migration-enabled-access-custom-templates.png?fit=max&auto=format&n=uVGuDiyXpd6WOLO4&q=85&s=43b637828ba38b90360f58fb3c6c5a37" alt="Upcart 장바구니 설정에서 설명과 함께 활성화된 Access custom templates 체크박스" width="1612" height="164" data-path="images/upcart/v2-migration-enabled-access-custom-templates.png" />

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

***

<div id="best-practices">
  ## 모범 사례
</div>

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

***

<div id="future-considerations">
  ## 향후 고려 사항
</div>

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

##

##