Aggiungere il GARAN-Label e l'avviso di garanzia legale in Magento 2
Due compiti, due meccanismi: un avviso valido per tutto il sito tramite blocco CMS e layout XML, e un GARAN-Label per prodotto tramite attributo prodotto. Entrambi funzionano con i mezzi nativi di Magento, su Luma e su Hyvä.
All'11 settembre 2026, Magento Open Source e Adobe Commerce non includono alcuna funzionalità nativa per l'avviso di garanzia legale o il GARAN-Label. Diverse estensioni del marketplace coprono il tema. Questa pagina mostra come farlo con i mezzi di bordo, così puoi decidere se ti serve davvero un'estensione. È una raccomandazione basata sulla situazione attuale del mercato, non una consulenza legale.
Due compiti, due meccanismi
Avviso di garanzia legale: per tutto il sito
Identico per ogni prodotto, ma diverso per lingua. In termini Magento: un blocco CMS per store view, inserito una volta sola nel layout della pagina prodotto.
GARAN-Label: per prodotto
Diverso per ogni modello (marchio, modello, durata della garanzia), identico in tutte le lingue. In termini Magento: un attributo prodotto con ambito globale, mostrato da un piccolo template nella scheda prodotto.
Avviso di garanzia legale: blocco CMS più layout XML
- Sotto Content > Blocks, crea un blocco con l'identificatore
legal-guarantee-noticee carica l'immagine dell'avviso nella lingua di quella store view. - Crea un blocco per ogni lingua, tutti con lo stesso identificatore, e assegna ciascuno alle store view corrispondenti. Magento risolve l'identificatore per store view, quindi al layout basta un solo riferimento.
- Inserisci il blocco nella pagina prodotto con un layout update nel tuo tema:
<!-- 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> Non hai accesso al tema? Lo stesso risultato è possibile senza codice: sotto Content > Widgets, crea un widget di tipo "CMS Static Block", scegli il layout update "Catalog Product View" e un container nell'area di contenuto principale. Anche Page Builder può modificare il contenuto del blocco, comodo se a gestire l'avviso è il marketing e non lo sviluppo.
GARAN-Label: creare l'attributo prodotto
Sotto Stores > Attributes > Product, aggiungi un nuovo attributo con queste impostazioni:
| Attribute code | garan_label_url | Minuscolo, senza spazi. Lo richiamerai nei template e nei file di import. |
| Catalog input type | Text Field | Contiene l'URL del PNG ospitato da te. Vedi la FAQ sul perché non un Media Image. |
| Scope | Global | Il label è neutro rispetto alla lingua: marchio, modello e durata sono gli stessi in ogni store view. Ambito globale significa un valore, una riga di import per SKU. |
| Visible on Catalog Pages on Storefront | No | Altrimenti l'URL grezzo compare nella scheda "Maggiori informazioni". L'immagine la mostri tu. |
| Attribute set | Tutti i set che contengono prodotti con garanzia | Sotto Stores > Attributes > Attribute Set, trascina l'attributo in un gruppo di ogni set pertinente. I prodotti in un set senza l'attributo non possono memorizzare un valore. |
La decisione sull'ambito è quella che conta per la configurazione a 24 lingue: l'avviso cambia per store view e vive nei blocchi CMS; il label è globale e vive in un unico attributo. Confonderli è la fonte più comune di problemi di import in seguito.
Mostrare il label nella scheda prodotto
Hai tre opzioni, dalla più alla meno controllabile:
- Template più layout XML. Aggiungi al tuo tema un piccolo template che stampa l'immagine quando l'attributo è valorizzato, e richiamalo in
catalog_product_view.xmlaccanto al blocco dell'avviso. Funziona su Luma e Hyvä; cambia solo il markup. - Page Builder o blocco CMS con snippet dinamico. Adatto all'avviso; non adatto al label per prodotto, perché un blocco statico non può leggere l'attributo del prodotto corrente senza codice personalizzato.
- Widget. Stesso limite dei blocchi CMS per i dati per prodotto. Va bene per l'avviso, non per il label.
<?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(__('Etichetta di garanzia UE (GARAN) per questo prodotto')) ?>"
loading="lazy" />
</div>
<?php endif; ?> Regole di posizionamento
- Nella scheda prodotto, nell'area informativa vicino all'immagine del prodotto e al prezzo, non nella galleria immagini.
- A colori e in dimensione leggibile. Non ridurlo a un'icona.
- Visibile senza interazione: non dietro un hover, non solo dentro una tab, non solo su una pagina collegata.
- Usa la versione PNG. Perché PNG e non SVG →
Compilare l'attributo in blocco via import CSV
Per un grande catalogo non compili l'attributo prodotto per prodotto. Genera i label in blocco, ospita i file PNG sul tuo server o CDN e importa gli URL con l'import prodotti nativo di Magento sotto System > Data Transfer > Import:
- Entity type: Products. Import behavior: Add/Update.
- Al file bastano due colonne:
skuegaran_label_url. Tutti gli altri dati prodotto restano intatti. - L'attributo deve esistere prima dell'import. Una colonna per un attributo sconosciuto non viene applicata.
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 La trappola dell'ambito multi-store: se hai creato
l'attributo con ambito store view, le righe senza una colonna
store_view_code scrivono solo nell'ambito predefinito,
e le singole store view possono conservare un valore precedente.
Con l'ambito globale, come consigliato sopra, la colonna non serve
e il problema non si pone.
La generazione CSV di GARAN-Label ti dà marchio, modello e URL del label per riga; incrociarla con il tuo elenco SKU è un CERCA.VERT in qualsiasi foglio di calcolo. Come funziona la generazione in blocco e quanto costa →
Cache: aggiornala dopo ogni modifica dell'attributo
Il classico momento Magento: l'import segnala successo, l'admin mostra il nuovo valore, il frontend non mostra ancora nulla. Le pagine prodotto vengono servite dalla full-page cache, e un import non le invalida in modo affidabile.
- Sotto System > Cache Management, aggiorna i tipi di cache segnati come invalidati, oppure
- da riga di comando:
bin/magento cache:clean full_page block_html, e - se i tuoi indexer sono impostati su "Update by Schedule", attendi il cron oppure lancia
bin/magento indexer:reindexper gli indexer dei prodotti.
Con Varnish o Fastly davanti al negozio lo stesso vale per la cache edge. Fai dell'aggiornamento della cache una parte della tua routine di import, non un ripensamento.
Tenerlo sincronizzato: cron più API per cataloghi che cambiano
Se arrivano nuovi prodotti ogni settimana, il giro manuale con il CSV stanca in fretta. La versione automatizzata ha tre parti:
- Un cron job seleziona i prodotti con una durata di garanzia superiore a due anni e un
garan_label_urlvuoto. - Per ciascuno chiama l'API di GARAN-Label con marchio, modello e durata e salva il PNG restituito sul tuo storage.
- Scrive l'URL tramite l'API REST di Magento (
PUT /V1/products/{sku}con l'attributo personalizzato) oppure direttamente via repository in un piccolo modulo, poi pulisce la cache per quel prodotto.
Le richieste per una combinazione che ha già un label restituiscono il file esistente senza consumare un credito, quindi il job può girare in modo idempotente. Riferimento API con codice di esempio →
Multi-store e multilingua: quale avviso per ogni store view
La store view di Magento è l'unità naturale per la lingua dell'avviso. Assegna il blocco CMS con l'avviso in italiano alle store view italiane, quello in francese alle store view francesi, e così via. Se una store view serve un paese in una lingua in cui l'avviso non è fornito, usa la lingua ufficiale UE di quel paese. Il GARAN-Label non ha bisogno di questa mappatura: un label per modello serve ogni store view.
I negozi con un website per paese e più store view per website dovrebbero assegnare i blocchi a livello di store view, non di website, così un website belga può mostrare l'avviso in francese e in olandese fianco a fianco.
Come generare i label
Inizia creando un account gratuito su GARAN-Label.com. Decidi poi come vuoi generare i label:
Piccolo catalogo
Modalità manuale: inserisci marchio, modello e durata della garanzia, scarica il PNG, caricalo nel tuo storage media e incolla l'URL nell'attributo.
Grande catalogo
Modalità CSV per l'assortimento esistente, API per i nuovi prodotti. Entrambe restituiscono un URL per label che ospiti tu e importi.
Pronto a etichettare il tuo catalogo Magento?
Registrati gratis e prova la modalità sandbox prima di spendere un solo credito.
Prova gratisUsi Shopware invece di Magento? Ecco la guida per Shopware →
Domande frequenti su Magento 2
Serve un'estensione Magento 2 per il GARAN-Label?
No. Un blocco CMS più un layout update XML copre l'avviso di garanzia legale, e un attributo prodotto più un piccolo template copre il GARAN-Label. Le estensioni esistono e possono far risparmiare tempo, ma niente di quanto descritto qui ne richiede una.
Funziona con il tema Hyvä?
Sì. L'attributo, il blocco CMS e il layout XML sono indipendenti dal tema. Cambia solo il file template che mostra l'immagine: in Hyvä lo metti nel tuo child theme e usi classi Tailwind al posto del markup Luma.
L'attributo dovrebbe essere un Media Image o un campo di testo con l'URL?
Un campo di testo con l'URL del label ospitato da te è la scelta pragmatica. Un attributo Media Image aggiunge un ruolo immagine alla galleria del prodotto, cioè esattamente dove il label non dovrebbe comparire, ed è più difficile da compilare via import CSV.
Posso semplicemente mostrare l'attributo nella scheda "Maggiori informazioni"?
Non come unica posizione. Il label deve essere visibile a colori nella scheda prodotto, e una tab che il cliente deve prima cliccare è un punto debole. Mostralo nell'area principale delle informazioni prodotto e tieni l'attributo fuori dall'elenco automatico degli attributi.
Ho importato i nuovi valori dell'attributo ma il frontend mostra ancora lo stato precedente. Perché?
Full-page cache. Un import non invalida in modo affidabile le pagine prodotto in cache. Aggiorna i tipi di cache invalidati in System > Cache Management oppure esegui bin/magento cache:clean full_page, e reindicizza se i tuoi indexer girano a pianificazione.