Guida alla migrazione a Upcart V2.0

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.

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

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:

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.
Attiva l’interruttore della funzionalità.
Consulta la documentazione per sviluppatori di Upcart per sintassi ed esempi.

Casella Access custom templates attivata con la relativa descrizione nelle impostazioni del carrello di Upcart

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.

Per iniziare

Moduli del carrello

Impostazioni del carrello

Pulsante carrello fisso

Multicart

Personalizzazioni

Analisi

Integrazioni e compatibilità

Fatturazione e account

Risoluzione dei problemi

Panoramica

Modifiche incompatibili - cambi nei nomi delle classi CSS

Classi V1 (deprecate)

Classi V2.0 (nuovo sistema)

Nomi di classe interni

Nomi di classe pubblici

✅ Cosa FARE

❌ Cosa NON fare

Sistema di attributi data

Modifiche alle variabili dei template

Modulo Annunci

Modulo Premi a livelli

Processo di migrazione

1. Fai un backup della configurazione attuale

2. Testa in modalità sandbox

Personalizzazione avanzata con la V2.0

Template personalizzati

Best practice

Considerazioni future

​Panoramica

​Modifiche incompatibili - cambi nei nomi delle classi CSS

​Classi V1 (deprecate)

​Classi V2.0 (nuovo sistema)

​Nomi di classe interni

​Nomi di classe pubblici

​

​✅ Cosa FARE

​❌ Cosa NON fare

​Sistema di attributi data

​Modifiche alle variabili dei template

​Modulo Annunci

​Modulo Premi a livelli

​Processo di migrazione

​1. Fai un backup della configurazione attuale

​2. Testa in modalità sandbox

​Personalizzazione avanzata con la V2.0

​Template personalizzati

​Best practice

​Considerazioni future

​

​

Panoramica

Modifiche incompatibili - cambi nei nomi delle classi CSS

Classi V1 (deprecate)

Classi V2.0 (nuovo sistema)

Nomi di classe interni

Nomi di classe pubblici

✅ Cosa FARE

❌ Cosa NON fare

Sistema di attributi data

Modifiche alle variabili dei template

Modulo Annunci

Modulo Premi a livelli

Processo di migrazione

1. Fai un backup della configurazione attuale

2. Testa in modalità sandbox

Personalizzazione avanzata con la V2.0

Template personalizzati

Best practice

Considerazioni future