> ## 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.
# Guida alla migrazione a Upcart V2.0
> Questo articolo è una guida alla migrazione per passare dai moduli Upcart V1.0 a quelli V2.0. Copre le modifiche incompatibili, le mappature delle classi CSS, gli aggiornamenti dei selettori JavaScript, la risoluzione dei problemi e il processo di migrazione passo per passo.
## Panoramica
I moduli Upcart V2.0 introducono un completo redesign architetturale del sistema del carrello. L'aggiornamento punta a prestazioni migliori, personalizzazione avanzata e migliore manutenibilità.
Questa guida ti aiuterà a capire cosa cambia migrando dai moduli V1.0 a quelli V2.0, quali problemi di compatibilità potresti incontrare e come aggiornare in sicurezza le tue personalizzazioni esistenti.
***
## Modifiche incompatibili - cambi nei nomi delle classi CSS
### Classi V1 (deprecate)
🚨 I seguenti nomi di classe V1.0 non sono più supportati in V2.0:
```
.styles_Header__
.styles_ProductRow__
.styles_Rewards__
.styles_TieredRewards__
...
```
Anche le classi di avviso di esaurimento scorte `upcart-quantity-warning` e `upcart-quantity-warning-text` sono **invariate**. Provengono dall'inizializzatore del carrello e non da un modulo con versione, quindi vengono emesse in modo identico sia che i tuoi moduli siano su V1 sia su V2.
**`.styles_CartPreview__card__` non è in questo elenco** — è il wrapper condiviso della shell del carrello renderizzato attorno a ogni modulo indipendentemente dalla versione, quindi le regole che lo interessano continuano a funzionare su V2. Le classi dei premi sono `.styles_Rewards__` (barra semplice) e `.styles_TieredRewards__` (barra a livelli); non esiste `.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'
```
### Classi V2.0 (nuovo sistema)
La V2.0 introduce un sistema di denominazione strutturato con prefissi di classe **internal** e **public**.
#### Nomi di classe interni
Sono riservati all'uso interno e possono cambiare senza preavviso.
Se sovrascrivi queste classi, la compatibilità futura non è garantita.
```
/* Internal classes - for Upcart's internal styling */
.upcart-internal-header
.upcart-internal-header__close-button
.upcart-internal-cart-items
.upcart-internal-rewards
...
```
#### Nomi di classe pubblici
🚨 Elenco dei nomi di classe pubblici disponibili
```
/*******************
***** 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'
```
Queste fanno parte dell'API di stile pubblica (`upcart-public-`) e possono essere sovrascritte in sicurezza per design personalizzati.
```
.upcart-public-header
.upcart-public-header__close-button
.upcart-public-rewards
...
```
###
### ✅ Cosa FARE
Usa solo nomi di classe `upcart-public-` per gli stili.
```
/* ✅ Correct usage */
.upcart-public-header {
font-size: 18px;
font-weight: bold;
}
```
### ❌ Cosa NON fare
Evita di sovrascrivere i nomi di classe interni
```
/* ❌ Avoid this */
.upcart-internal-header {
font-size: 18px;
font-weight: bold;
}
```
Evita di puntare a nodi specifici con selettori profondi o personalizzati.
```
/* ❌ Avoid this */
.upcart-public-upsell div a {
font-size: 18px;
font-weight: bold;
}
```
***
## Sistema di attributi data
La V2.0 introduce un **sistema strutturato di attributi data** per un targeting migliore e personalizzazioni avanzate.
```
```
Questi attributi rendono più facile creare template flessibili e basati sui dati mantenendo il codice chiaro.
***
## Modifiche alle variabili dei template
I moduli V2 usano una **nuova sintassi per le variabili dei template** con doppie parentesi graffe `{{ }}`.
## Modulo Annunci
* V1.0: `` `{TIMER}` ``
* V2.0: `` `{{timer}}` ``
## Modulo Premi a livelli
* V1.0: `` `{AMOUNT}` `` → V2: `` `{{amount}}` ``
* V1.0: `` `{COUNT}` `` → V2: `` `{{count}}` ``
***
## Processo di migrazione
#### 1. Fai un backup della configurazione attuale
Prima di apportare qualsiasi modifica, esegui il backup dei tuoi file **CSS personalizzato** e **HTML** esistenti.
#### 2. Testa in modalità sandbox
Configura il tuo carrello aggiornato usando la **modalità sandbox** per testare in sicurezza i nuovi moduli prima di andare live.
***
## Personalizzazione avanzata con la V2.0
### Template personalizzati
I moduli V2.0 supportano **template completamente personalizzati** per i merchant che vogliono il controllo totale su layout e struttura.
Per attivare i template personalizzati:
1. Vai su **Settings > Cart settings**, espandi **Advanced Settings** e seleziona **Access custom templates**. La casella si trova all'interno di quella sezione compressa, non nella scheda Cart settings stessa.
2. Attiva l'interruttore della funzionalità.
3. Consulta la documentazione per sviluppatori di Upcart per sintassi ed esempi.
**Nota:** il team di supporto di Upcart non può assistere nello sviluppo, nel debug o nella risoluzione dei problemi dei template personalizzati.
***
## Best practice
* Testa sempre prima gli aggiornamenti in **modalità sandbox**.
* Migra e aggiorna le personalizzazioni in modo incrementale.
* Usa le **classi pubbliche** per gli stili invece di quelle interne.
* Conserva i backup di tutte le versioni precedenti prima di aggiornare le impostazioni live.
***
## Considerazioni future
* I moduli V2 continueranno a ricevere nuove funzionalità, ottimizzazioni e aggiornamenti.
* I moduli V1 sono ora in **modalità di manutenzione**, con supporto limitato e senza nuove funzionalità.
* Consigliamo ai merchant di migrare a V2 il prima possibile per una compatibilità completa.
##
##