Guide de migration Upcart V2.0

Aperçu

Les modules Upcart V2.0 introduisent une refonte architecturale complète du système de panier. La mise à jour se concentre sur l’amélioration des performances, une personnalisation renforcée et une meilleure maintenabilité. Ce guide vous aidera à comprendre ce qui change lors de la migration des modules V1.0 vers V2.0, quels problèmes de compatibilité vous pouvez rencontrer et comment mettre à jour vos personnalisations existantes en toute sécurité.

Changements majeurs - modifications des noms de classes CSS

Classes V1 (obsolètes)

🚨 Les noms de classes V1.0 suivants ne sont plus pris en charge dans la V2.0 :

.styles_Header__  
.styles_ProductRow__  
.styles_Rewards__  
.styles_TieredRewards__  
...

Les classes d’avertissement de rupture de stock upcart-quantity-warning et upcart-quantity-warning-text sont également inchangées. Elles proviennent de l’initialiseur du panier plutôt que d’un module versionné, elles sont donc émises de manière identique que vos modules soient en V1 ou en V2.

.styles_CartPreview__card__ ne figure pas dans cette liste — il s’agit de l’enveloppe partagée de l’enveloppe du panier rendue autour de chaque module quelle que soit la version, donc les règles qui la ciblent continuent de fonctionner en V2. Les classes de récompenses sont .styles_Rewards__ (barre simple) et .styles_TieredRewards__ (barre à paliers) ; il n’existe pas de .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'

Classes V2.0 (nouveau système)

La V2.0 introduit un système de nommage structuré avec des préfixes de classes internes et publics.

Noms de classes internes

Ceux-ci sont réservés à un usage interne et peuvent changer sans préavis. Si vous remplacez ces classes, la compatibilité future n’est pas garantie.

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

Noms de classes publics

🚨 Liste des noms de classes publics disponibles

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

Ceux-ci font partie de l’API de style publique (upcart-public-) et peuvent être remplacés en toute sécurité pour des designs personnalisés.

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

✅ À FAIRE

Utilisez uniquement les noms de classes upcart-public- pour le style.

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

❌ À ÉVITER

Évitez de remplacer les noms de classes internes

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

Évitez de cibler des nœuds spécifiques avec des sélecteurs profonds ou personnalisés.

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

Système d’attributs de données

La V2.0 introduit un système d’attributs de données structuré pour un ciblage amélioré et une personnalisation avancée.

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

Ces attributs facilitent la création de modèles flexibles et pilotés par les données tout en préservant la clarté du code.

Modifications des variables de modèle

Les modules V2 utilisent une nouvelle syntaxe de variables de modèle avec des doubles accolades {{ }}.

Module d’annonces

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

Module de récompenses à paliers

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

Processus de migration

1. Sauvegarder la configuration actuelle

Avant d’effectuer toute modification, sauvegardez vos fichiers CSS personnalisé et HTML existants.

2. Tester en mode sandbox

Configurez votre panier mis à jour à l’aide du mode sandbox pour tester les nouveaux modules en toute sécurité avant la mise en ligne.

Personnalisation avancée avec la V2.0

Modèles personnalisés

Les modules V2.0 prennent en charge des modèles entièrement personnalisés pour les marchands qui souhaitent un contrôle complet sur la mise en page et la structure. Pour activer les modèles personnalisés :

Allez dans Settings > Cart settings, dépliez Advanced Settings et cochez Access custom templates. La case à cocher se trouve dans cette section repliée, pas sur l’onglet Cart settings lui-même.
Activez la bascule de fonctionnalité.
Consultez la documentation développeur d’Upcart pour la syntaxe et des exemples.

Note : l’équipe d’assistance d’Upcart ne peut pas aider au développement, au débogage ou au dépannage des modèles personnalisés.

Bonnes pratiques

Testez toujours les mises à jour d’abord en mode sandbox.
Migrez et mettez à jour les personnalisations de manière progressive.
Utilisez les classes publiques pour le style plutôt que les classes internes.
Conservez des sauvegardes de toutes les versions précédentes avant de mettre à jour les paramètres en production.

Considérations futures

Les modules V2 continueront de recevoir de nouvelles fonctionnalités, des optimisations et des mises à jour.
Les modules V1 sont désormais en mode maintenance avec une assistance limitée et aucune nouvelle fonctionnalité.
Les marchands sont encouragés à migrer vers la V2 dès que possible pour une compatibilité complète.

Getting Started

Cart Modules

Cart Settings

Sticky Cart Button

Multicart

Customizations

Analytics

Integrations & Compatibility

Billing & Account

Troubleshooting

Aperçu

Changements majeurs - modifications des noms de classes CSS

Classes V1 (obsolètes)

Classes V2.0 (nouveau système)

Noms de classes internes

Noms de classes publics

✅ À FAIRE

❌ À ÉVITER

Système d’attributs de données

Modifications des variables de modèle

Module d’annonces

Module de récompenses à paliers

Processus de migration

1. Sauvegarder la configuration actuelle

2. Tester en mode sandbox

Personnalisation avancée avec la V2.0

Modèles personnalisés

Bonnes pratiques

Considérations futures

​Aperçu

​Changements majeurs - modifications des noms de classes CSS

​Classes V1 (obsolètes)

​Classes V2.0 (nouveau système)

​Noms de classes internes

​Noms de classes publics

​

​✅ À FAIRE

​❌ À ÉVITER

​Système d’attributs de données

​Modifications des variables de modèle

​Module d’annonces

​Module de récompenses à paliers

​Processus de migration

​1. Sauvegarder la configuration actuelle

​2. Tester en mode sandbox

​Personnalisation avancée avec la V2.0

​Modèles personnalisés

​Bonnes pratiques

​Considérations futures

​

​

Aperçu

Changements majeurs - modifications des noms de classes CSS

Classes V1 (obsolètes)

Classes V2.0 (nouveau système)

Noms de classes internes

Noms de classes publics

✅ À FAIRE

❌ À ÉVITER

Système d’attributs de données

Modifications des variables de modèle

Module d’annonces

Module de récompenses à paliers

Processus de migration

1. Sauvegarder la configuration actuelle

2. Tester en mode sandbox

Personnalisation avancée avec la V2.0

Modèles personnalisés

Bonnes pratiques

Considérations futures