Dodawanie GARAN-Label i informacji o gwarancji ustawowej w Magento 2
Dwa zadania, dwa mechanizmy: informacja dla całego sklepu przez blok CMS i layout XML oraz GARAN-Label dla każdego produktu przez atrybut produktu. Oba działają natywnymi środkami Magento, na Luma i na Hyvä.
Stan na 11 września 2026 r., Magento Open Source i Adobe Commerce nie mają natywnej funkcji dla informacji o gwarancji ustawowej ani GARAN-Label. Temat pokrywa kilka rozszerzeń z marketplace. Ta strona pokazuje, jak zrobić to środkami wbudowanymi, abyś mógł zdecydować, czy w ogóle potrzebujesz rozszerzenia. To rekomendacja oparta na obecnej sytuacji rynkowej, a nie porada prawna.
Dwa zadania, dwa mechanizmy
Informacja o gwarancji ustawowej: dla całego sklepu
Identyczna dla każdego produktu, ale inna dla każdego języka. W terminologii Magento: blok CMS dla każdego widoku sklepu, wstawiony raz do layoutu strony produktu.
GARAN-Label: dla każdego produktu
Inny dla każdego modelu (marka, model, okres gwarancji), identyczny we wszystkich językach. W terminologii Magento: atrybut produktu z zakresem globalnym, renderowany małym szablonem na stronie produktu.
Informacja o gwarancji ustawowej: blok CMS plus layout XML
- W Content > Blocks utwórz blok z identyfikatorem
legal-guarantee-noticei prześlij obraz informacji w języku tego widoku sklepu. - Utwórz po jednym bloku na język, wszystkie z tym samym identyfikatorem, i przypisz każdy do pasujących widoków sklepu. Magento rozwiązuje identyfikator per widok sklepu, więc layout potrzebuje tylko jednego odwołania.
- Wstaw blok na stronę produktu aktualizacją layoutu w swoim motywie:
<!-- app/design/frontend/Vendor/theme/Magento_Catalog/layout/catalog_product_view.xml -->
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
<body>
<referenceContainer name="product.info.main">
<block class="Magento\Cms\Block\Block" name="legal.guarantee.notice" after="product.info.overview">
<arguments>
<argument name="block_id" xsi:type="string">legal-guarantee-notice</argument>
</arguments>
</block>
</referenceContainer>
</body>
</page> Nie masz dostępu do motywu? Ten sam efekt osiągniesz bez kodu: w Content > Widgets utwórz widget typu „CMS Static Block", wybierz aktualizację layoutu „Catalog Product View" i kontener w głównym obszarze treści. Page Builder może też edytować samą treść bloku, co jest wygodne, gdy informację utrzymuje marketing, a nie dział IT.
GARAN-Label: tworzenie atrybutu produktu
W Stores > Attributes > Product dodaj nowy atrybut z tymi ustawieniami:
| Attribute code | garan_label_url | Małe litery, bez spacji. Będziesz się do niego odwoływać w szablonach i plikach importu. |
| Catalog input type | Text Field | Przechowuje adres URL samodzielnie hostowanego PNG. Dlaczego nie Media Image: patrz FAQ. |
| Scope | Global | Label jest neutralny językowo: marka, model i okres gwarancji są takie same w każdym widoku sklepu. Zakres globalny oznacza jedną wartość, jeden wiersz importu na SKU. |
| Visible on Catalog Pages on Storefront | No | W przeciwnym razie surowy adres URL pojawi się w zakładce „Więcej informacji". Zamiast tego renderujesz obraz samodzielnie. |
| Attribute set | Wszystkie zestawy zawierające produkty z gwarancją | W Stores > Attributes > Attribute Set przeciągnij atrybut do grupy w każdym istotnym zestawie. Produkty w zestawie bez tego atrybutu nie mogą przechowywać wartości. |
Decyzja o zakresie to ta, która ma znaczenie przy konfiguracji z 24 językami: informacja różni się per widok sklepu i mieszka w blokach CMS; label jest globalny i mieszka w jednym atrybucie. Pomylenie tego to najczęstsze źródło późniejszych problemów z importem.
Renderowanie labela na stronie produktu
Masz trzy opcje, od największej do najmniejszej kontroli:
- Szablon plus layout XML. Dodaj do motywu mały szablon, który wyświetla obraz, gdy atrybut jest ustawiony, i odwołaj się do niego w
catalog_product_view.xmlobok bloku informacji. Działa na Luma i Hyvä; różnią się tylko znaczniki. - Page Builder lub blok CMS z dynamicznym fragmentem. Nadaje się do informacji; nie nadaje się do labela per produkt, ponieważ statyczny blok nie odczyta atrybutu bieżącego produktu bez własnego kodu.
- Widget. To samo ograniczenie co bloki CMS przy danych per produkt. Dobry do informacji, nie do labela.
<?php /** @var \Magento\Catalog\Block\Product\View $block */
$labelUrl = $block->getProduct()->getData('garan_label_url'); ?>
<?php if ($labelUrl): ?>
<div class="garan-label">
<img src="<?= $block->escapeUrl($labelUrl) ?>"
alt="<?= $block->escapeHtmlAttr(__('Unijna etykieta gwarancyjna (GARAN) dla tego produktu')) ?>"
loading="lazy" />
</div>
<?php endif; ?> Zasady umieszczania
- Na stronie produktu, w obszarze informacyjnym obok zdjęcia produktu i ceny, nie w galerii zdjęć.
- W kolorze i w czytelnym rozmiarze. Nie skaluj go do wielkości ikony.
- Widoczny bez interakcji: nie po najechaniu kursorem, nie tylko w zakładce, nie tylko na podlinkowanej stronie.
- Użyj wersji PNG. Dlaczego PNG, a nie SVG →
Masowe wypełnianie atrybutu przez import CSV
Przy dużym katalogu nie wypełniasz atrybutu produkt po produkcie. Wygeneruj labele masowo, hostuj pliki PNG na własnym serwerze lub CDN i zaimportuj adresy URL natywnym importem produktów Magento w System > Data Transfer > Import:
- Entity type: Products. Import behavior: Add/Update.
- Plik potrzebuje tylko dwóch kolumn:
skuigaran_label_url. Wszystkie pozostałe dane produktu pozostają nietknięte. - Atrybut musi istnieć przed importem. Kolumna dla nieznanego atrybutu nie jest stosowana.
sku,garan_label_url
GSR18V-55-BLUE,https://cdn.example.com/garan/bosch-gsr-18v-55.png
GSR18V-55-BLACK,https://cdn.example.com/garan/bosch-gsr-18v-55.png
DHP486Z,https://cdn.example.com/garan/makita-dhp486.png Pułapka zakresu multi-store: jeśli utworzyłeś
atrybut z zakresem widoku sklepu, wiersze bez kolumny
store_view_code zapisują tylko do zakresu domyślnego,
a poszczególne widoki sklepu mogą zachować starszą wartość. Przy
zakresie globalnym, zalecanym powyżej, kolumna nie jest potrzebna
i ten problem nie występuje.
Import CSV na GARAN-Label.com daje Ci markę, model i adres URL labela w każdym wierszu; połączenie tego z listą SKU to zwykłe wyszukiwanie w dowolnym arkuszu kalkulacyjnym. Jak działa generowanie masowe i ile kosztuje →
Cache: odświeżaj po każdej aktualizacji atrybutu
Klasyczny moment w Magento: import zgłasza sukces, panel admina pokazuje nową wartość, sklep nadal nic nie pokazuje. Strony produktów są serwowane z full-page cache, a import nie unieważnia ich niezawodnie.
- W System > Cache Management odśwież typy cache oznaczone jako unieważnione, albo
- z wiersza poleceń:
bin/magento cache:clean full_page block_html, oraz - jeśli Twoje indeksery działają w trybie „Update by Schedule", poczekaj na uruchomienie crona lub wywołaj
bin/magento indexer:reindexdla indekserów produktów.
Przy Varnish lub Fastly przed sklepem to samo dotyczy edge cache. Uczyń odświeżenie cache częścią swojej rutyny importu, a nie dodatkiem na koniec.
Synchronizacja: cron plus API dla zmieniających się katalogów
Jeśli nowe produkty pojawiają się co tydzień, ręczna wymiana plików CSV szybko się nudzi. Wersja zautomatyzowana ma trzy części:
- Zadanie cron wybiera produkty z okresem gwarancji dłuższym niż dwa lata i pustym
garan_label_url. - Dla każdego z nich wywołuje API GARAN-Label z marką, modelem i okresem gwarancji i zapisuje zwrócony PNG na Twoim własnym storage.
- Zapisuje adres URL z powrotem przez REST API Magento (
PUT /V1/products/{sku}z atrybutem niestandardowym) lub bezpośrednio przez repozytorium w małym module, a następnie czyści cache dla tego produktu.
Żądania dla kombinacji, która ma już label, zwracają istniejący plik bez zużywania kredytu, więc zadanie może działać idempotentnie. Dokumentacja API z przykładowym kodem →
Multi-store i wiele języków: która informacja w którym widoku sklepu
Widok sklepu w Magento to naturalna jednostka dla języka informacji. Przypisz blok CMS z polską informacją do polskich widoków sklepu, z niemiecką do niemieckich i tak dalej. Jeśli widok sklepu obsługuje kraj w języku, w którym informacja nie jest dostępna, użyj urzędowego języka UE tego kraju. GARAN-Label nie potrzebuje takiego mapowania: jeden label na model obsługuje każdy widok sklepu.
Sklepy z jedną witryną na kraj i kilkoma widokami sklepu na witrynę powinny przypisywać bloki na poziomie widoku sklepu, a nie witryny, aby belgijska witryna mogła pokazywać obok siebie informację francuską i niderlandzką.
Jak wygenerować labele
Zacznij od założenia darmowego konta na GARAN-Label.com. Następnie zdecyduj, jak chcesz generować labele:
Mały katalog
Tryb ręczny: podaj markę, model i okres gwarancji, pobierz PNG, prześlij go do swojej biblioteki mediów i wklej adres URL do atrybutu.
Duży katalog
Tryb CSV dla istniejącego asortymentu, API dla nowych produktów. Oba zwracają adres URL dla każdego labela, który hostujesz samodzielnie i importujesz.
Gotowy, aby oznakować swój katalog w Magento?
Zarejestruj się za darmo i wypróbuj tryb sandbox, zanim wydasz choć jeden kredyt.
Wypróbuj za darmoUżywasz Shopware zamiast Magento? Oto przewodnik dla Shopware →
Najczęściej zadawane pytania dotyczące Magento 2
Czy potrzebuję rozszerzenia Magento 2 do GARAN-Label?
Nie. Blok CMS plus aktualizacja layoutu XML wystarczą dla informacji o gwarancji ustawowej, a atrybut produktu plus mały szablon dla GARAN-Label. Rozszerzenia istnieją i mogą oszczędzić czas, ale nic tutaj ich nie wymaga.
Czy to działa z motywem Hyvä?
Tak. Atrybut, blok CMS i layout XML są niezależne od motywu. Różni się tylko plik szablonu renderujący obraz: w Hyvä umieszczasz go w motywie potomnym i używasz klas Tailwind zamiast znaczników Luma.
Czy atrybut powinien być typu Media Image, czy polem tekstowym z adresem URL?
Pole tekstowe z adresem URL samodzielnie hostowanego labela to pragmatyczny wybór. Atrybut Media Image dodaje rolę obrazu do galerii produktu, czyli dokładnie tam, gdzie label nie powinien się pojawiać, a do tego trudniej go wypełnić przez import CSV.
Czy mogę po prostu pokazać atrybut w zakładce „Więcej informacji"?
Nie jako jedyne miejsce. Label musi być widoczny na stronie produktu w kolorze, a zakładka, którą klient musi najpierw kliknąć, to słaby punkt. Renderuj go w głównym obszarze informacji o produkcie i nie umieszczaj atrybutu na automatycznej liście atrybutów.
Zaimportowałem nowe wartości atrybutu, ale sklep nadal pokazuje stary stan. Dlaczego?
Full-page cache. Import nie unieważnia niezawodnie zbuforowanych stron produktów. Odśwież unieważnione typy cache w System > Cache Management lub uruchom bin/magento cache:clean full_page, a jeśli indeksery działają według harmonogramu, wykonaj reindeksację.