Przewodnik migracji do Upcart V2.0

Przegląd

Moduły Upcart V2.0 wprowadzają całkowicie przeprojektowaną architekturę systemu koszyka. Aktualizacja skupia się na lepszej wydajności, rozszerzonych możliwościach personalizacji i łatwiejszym utrzymaniu. Ten przewodnik pomoże Ci zrozumieć, co zmienia się przy migracji z modułów V1.0 na V2.0, jakie problemy ze zgodnością możesz napotkać oraz jak bezpiecznie zaktualizować istniejące personalizacje.

Zmiany łamiące kompatybilność — zmiany nazw klas CSS

Klasy V1 (przestarzałe)

🚨 Następujące nazwy klas z V1.0 nie są już obsługiwane w V2.0:

.styles_Header__  
.styles_ProductRow__  
.styles_Rewards__  
.styles_TieredRewards__  
...

Klasy ostrzeżenia o braku towaru upcart-quantity-warning i upcart-quantity-warning-text również pozostają bez zmian. Pochodzą one z inicjalizatora koszyka, a nie z wersjonowanego modułu, więc są emitowane identycznie niezależnie od tego, czy Twoje moduły działają na V1 czy V2.

.styles_CartPreview__card__ nie znajduje się na tej liście — to współdzielony wrapper powłoki koszyka renderowany wokół każdego modułu niezależnie od wersji, więc reguły celujące w tę klasę nadal działają na V2. Klasy nagród to .styles_Rewards__ (prosty pasek) i .styles_TieredRewards__ (pasek progowy); nie istnieje klasa .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'

Klasy V2.0 (nowy system)

V2.0 wprowadza ustrukturyzowany system nazewnictwa z prefiksami klas wewnętrznych i publicznych.

Wewnętrzne nazwy klas

Są one zarezerwowane do użytku wewnętrznego i mogą się zmienić bez powiadomienia. Jeśli nadpiszesz te klasy, przyszła zgodność nie jest gwarantowana.

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

Publiczne nazwy klas

🚨 Lista dostępnych publicznych nazw klas

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

Są one częścią publicznego API stylowania (upcart-public-) i można je bezpiecznie nadpisywać w celu tworzenia niestandardowych projektów.

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

✅ Co ROBIĆ

Do stylowania używaj wyłącznie nazw klas upcart-public-.

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

❌ Czego NIE robić

Unikaj nadpisywania wewnętrznych nazw klas

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

Unikaj celowania w konkretne węzły za pomocą głębokich lub niestandardowych selektorów.

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

System atrybutów data

V2.0 wprowadza ustrukturyzowany system atrybutów data dla lepszego celowania i zaawansowanej personalizacji.

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

Te atrybuty ułatwiają tworzenie elastycznych szablonów opartych na danych przy zachowaniu przejrzystości kodu.

Zmiany zmiennych szablonów

Moduły V2 używają nowej składni zmiennych szablonów z podwójnymi nawiasami klamrowymi {{ }}.

Moduł ogłoszeń

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

Moduł nagród progowych

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

Proces migracji

1. Utwórz kopię zapasową bieżącej konfiguracji

Zanim wprowadzisz jakiekolwiek zmiany, wykonaj kopię zapasową istniejących plików niestandardowego CSS i HTML.

2. Testuj w trybie piaskownicy

Skonfiguruj zaktualizowany koszyk w trybie piaskownicy (sandbox), aby bezpiecznie przetestować nowe moduły przed publikacją.

Zaawansowana personalizacja z V2.0

Niestandardowe szablony

Moduły V2.0 obsługują w pełni niestandardowe szablony dla sprzedawców, którzy chcą mieć pełną kontrolę nad układem i strukturą. Aby włączyć niestandardowe szablony:

Przejdź do Settings > Cart settings, rozwiń sekcję Advanced Settings i zaznacz Access custom templates. Pole wyboru znajduje się wewnątrz tej zwiniętej sekcji, a nie na samej karcie Cart settings.
Włącz przełącznik funkcji.
Zapoznaj się z dokumentacją deweloperską Upcart, aby poznać składnię i przykłady.

Zaznaczone pole wyboru Access custom templates wraz z opisem w ustawieniach koszyka Upcart

Uwaga: Zespół wsparcia Upcart nie może pomagać w tworzeniu, debugowaniu ani rozwiązywaniu problemów z niestandardowymi szablonami.

Najlepsze praktyki

Zawsze najpierw testuj aktualizacje w trybie piaskownicy.
Migruj i aktualizuj personalizacje stopniowo.
Do stylowania używaj klas publicznych zamiast wewnętrznych.
Zachowuj kopie zapasowe wszystkich poprzednich wersji przed aktualizacją ustawień na żywo.

Plany na przyszłość

Moduły V2 będą nadal otrzymywać nowe funkcje, optymalizacje i aktualizacje.
Moduły V1 są obecnie w trybie utrzymania z ograniczonym wsparciem i bez nowych funkcji.
Zachęcamy sprzedawców do jak najszybszej migracji do V2 w celu zapewnienia pełnej zgodności.

Pierwsze kroki

Moduły koszyka

Ustawienia koszyka

Przyklejony przycisk koszyka

Multicart

Personalizacje

Analityka

Integracje i kompatybilność

Rozliczenia i konto

Rozwiązywanie problemów

Przegląd

Zmiany łamiące kompatybilność — zmiany nazw klas CSS

Klasy V1 (przestarzałe)

Klasy V2.0 (nowy system)

Wewnętrzne nazwy klas

Publiczne nazwy klas

✅ Co ROBIĆ

❌ Czego NIE robić

System atrybutów data

Zmiany zmiennych szablonów

Moduł ogłoszeń

Moduł nagród progowych

Proces migracji

1. Utwórz kopię zapasową bieżącej konfiguracji

2. Testuj w trybie piaskownicy

Zaawansowana personalizacja z V2.0

Niestandardowe szablony

Najlepsze praktyki

Plany na przyszłość

​Przegląd

​Zmiany łamiące kompatybilność — zmiany nazw klas CSS

​Klasy V1 (przestarzałe)

​Klasy V2.0 (nowy system)

​Wewnętrzne nazwy klas

​Publiczne nazwy klas

​

​✅ Co ROBIĆ

​❌ Czego NIE robić

​System atrybutów data

​Zmiany zmiennych szablonów

​Moduł ogłoszeń

​Moduł nagród progowych

​Proces migracji

​1. Utwórz kopię zapasową bieżącej konfiguracji

​2. Testuj w trybie piaskownicy

​Zaawansowana personalizacja z V2.0

​Niestandardowe szablony

​Najlepsze praktyki

​Plany na przyszłość

​

​

Przegląd

Zmiany łamiące kompatybilność — zmiany nazw klas CSS

Klasy V1 (przestarzałe)

Klasy V2.0 (nowy system)

Wewnętrzne nazwy klas

Publiczne nazwy klas

✅ Co ROBIĆ

❌ Czego NIE robić

System atrybutów data

Zmiany zmiennych szablonów

Moduł ogłoszeń

Moduł nagród progowych

Proces migracji

1. Utwórz kopię zapasową bieżącej konfiguracji

2. Testuj w trybie piaskownicy

Zaawansowana personalizacja z V2.0

Niestandardowe szablony

Najlepsze praktyki

Plany na przyszłość