Come aggiungere codici a barre ai tuoi messaggi

Cosa imparerai

Scopri come usare il tag {% barcode %} per generare codici a barre Code 128 nei tuoi messaggi e-mail, MMS, RCS e WhatsApp. Il valore del codice a barre può essere una stringa statica, una proprietà del profilo, una variabile dell’evento o un codice coupon Klaviyo.

Riferimento rapido

Prima di iniziare

Il {% barcode %} Il tag funziona generando un URL. Quando l'URL viene caricato (in un'anteprima, in una casella di posta o in un dispositivo mobile), viene visualizzata un'immagine PNG del codice a barre. Ciò significa che l'immagine del codice a barre non viene creata fino a quando l'URL non viene effettivamente recuperato.

Il {% barcode %} Il tag è supportato in:

• E-mail
• MMS
• RCS
• WhatsApp

Per la messaggistica mobile, ti serve il canale corrispondente configurato nel tuo account. Le immagini dei codici a barre MMS possono essere recapitate solo dove il tuo numero mittente e il paese del destinatario supportano MMS. Consulta Capire le best practice per immagini e GIF MMS per i paesi e i tipi di numero supportati.

Utilizzo di base

Il modo più semplice per utilizzare il tag del codice a barre è:

{% barcode 'MyCode' %}

Questo produce un URL che restituisce un'immagine PNG di un codice a barre. Durante la scansione, il codice a barre contiene il valore MyCode.

Puoi personalizzare il codice a barre passando gli argomenti al tag. Per esempio:

{% barcode 'MyCode' width=200 height=100 %}

Consulta la sezione di riferimento degli argomenti qui di seguito per tutte le opzioni disponibili.

Utilizzo di codici a barre con canali diversi

E-mail

Per le e-mail, hai due opzioni per il rendering del codice a barre:

Opzione 1: modalità HTML (consigliata per le e-mail)

Imposta mode=html per ottenere l'output di un tag HTML <img> direttamente. Questo è l'approccio più semplice per includere un codice a barre in un'e-mail.

{% barcode 'MyCode' mode=html %}

Inserisci questo tag in un blocco di testo o in un blocco HTML nell'editor dei modelli di e-mail.

Opzione 2: modalità URL

Lascia la modalità non impostata (o imposta mode=url) per generare un URL. Usa questa opzione con un blocco immagine per controllare lo stile dell'immagine.

{% barcode 'MyCode' %}

1. Aggiungi un blocco immagine al tuo modello di e-mail e selezionalo.
2. Fai clic su Seleziona immagine, quindi apri la scheda Immagine dinamica.
3. Incolla il tag del codice a barre in Variabile dinamica o URL dinamico.
4. Clicca su Salva.

MMS

Per i messaggi MMS, aggiungi il tag del codice a barre nella scheda Immagine dinamica dell’editor SMS/MMS, non nel corpo del testo.

1. Apri il tuo messaggio MMS nell’editor, seleziona contenuto e attiva allegato.
2. Seleziona Immagine, poi fai clic su Seleziona immagine. Se l’editor mostra Contenuti multimediali, selezionalo e fai clic su Seleziona contenuti multimediali.
3. Vai alla scheda Immagine dinamica.
4. Incolla il tag del codice a barre in Variabile dinamica o URL dinamico, ad esempio:

{% barcode person.LoyaltyId %}

1. Clicca su Salva.

Segue lo stesso processo dell’aggiunta di qualsiasi immagine dinamica a un MMS. Per maggiori dettagli, vedi Come aggiungere un’immagine dinamica a un servizio di messaggistica di testo.

RCS

Per i messaggi RCS, usa mode=rcs per applicare le dimensioni predefinite del codice a barre e dell’area di lavoro per le immagini RCS. Prima di inviare, visualizza l’anteprima e testa il messaggio sui tipi di dispositivo dei destinatari.

{% barcode 'MyCode' mode=rcs %}

1. Nell’editor dei messaggi RCS, attiva la sezione Allegato della scheda.
2. Seleziona Immagine, poi fai clic su Seleziona immagine. Se l’editor mostra Contenuti multimediali, selezionalo e fai clic su Seleziona contenuti multimediali.
3. Apri Immagine dinamica, incolla il tag del codice a barre in Variabile dinamica o URL dinamico e fai clic su Salva.

Impostazioni predefinite RCS:

• Larghezza: 600 px
• Altezza: 300 px
• Aggiunto a: 1440x720px

Queste impostazioni predefinite seguono i consigli di formattazione delle immagini RCS di Klaviyo. Puoi sostituirle con i modelli personalizzati width, height, padded_widthe padded_height se necessario.

WhatsApp

1. Nell’editor dei messaggi WhatsApp, attiva Intestazione e seleziona File multimediali.
2. Fai clic su Seleziona file multimediali, poi apri la scheda Immagine dinamica.
3. Incolla il tag del codice a barre in Variabile dinamica o URL dinamico, ad esempio:

{% barcode person.MembershipId %}

1. Clicca su Salva.

Non è necessaria alcuna configurazione o modalità speciale per WhatsApp. L'impostazione predefinita mode=url funziona correttamente.

Riferimento agli argomenti del tag del codice a barre

Utilizzo dei codici a barre con le proprietà del profilo e i dati degli eventi

Puoi utilizzare le Proprietà del profilo o le variabili evento come valore del codice a barre per personalizzarlo per ogni destinatario. I destinatari con lo stesso valore ricevono lo stesso codice a barre.

Esempi di proprietà del profilo:

{% barcode person.LoyaltyId %}
{% barcode person.email %}
{% barcode person.MembershipNumber %}

Esempi di variabili evento (per i flussi attivati da metriche):

{% barcode event.Code %}
{% barcode event.OrderId %}

Gestione dei valori mancanti:

Se per un destinatario non è impostata la proprietà, l'URL del codice a barre non sarà valido e l'immagine non verrà caricata. Hai due opzioni:

Opzione 1: usare un default Filtra per impostare un valore di riserva significativo:

{% barcode person.BarcodeCode|default:'STORE-MEMBER' %}

Assicurati che l'impostazione predefinita sia un valore che abbia senso se scansionato. Un segnaposto generico come "riserva" produrrebbe un codice a barre scansionabile ma inutile.

Opzione 2 (e-mail): usa un'istruzione condizionale per nascondere completamente il codice a barre quando il valore manca:

{% if person.BarcodeCode %}
  {% barcode person.BarcodeCode mode=html %}
{% endif %}

Esempio combinato di e-mail:

{% barcode person.LoyaltyId width=200 height=75 mode=html %}

Utilizzo dei codici a barre con i codici coupon di Klaviyo

Per prima cosa, crea o carica un coupon in Klaviyo. Imposta coupon=True e sostituisci ShopifyCoupon nell’esempio qui sotto con il nome esatto del coupon in Klaviyo. Klaviyo assegna un codice coupon al destinatario, oppure utilizza il suo codice valido esistente, e codifica quel codice nel codice a barre. Consulta Primi passi con i codici coupon in Klaviyo per la configurazione e i requisiti di disponibilità dei coupon.

{% barcode 'ShopifyCoupon' coupon=True %}

Funziona su tutti i canali. Ad esempio, per inviare un codice a barre coupon tramite RCS:

{% barcode 'ShopifyCoupon' coupon=True mode=rcs %}

{% barcode person.CouponCode %}

Ridimensionamento e dimensionamento

Per impostazione predefinita, la larghezza e l’altezza dell’immagine del codice a barre generata vengono ridimensionate di un fattore di 3x. Questo significa:

• A width di 100 rendering a 300 px di larghezza effettiva
• A height di 50 rendering a un'altezza effettiva di 150 px

In mode=html, l’immagine dell’e-mail viene visualizzata alla larghezza e all’altezza originali del tag. Ad esempio, width=100 height=50 genera un'immagine di 300x150px e ne imposta le dimensioni di visualizzazione su 100x50px.

Problema: quando mode=rcs, il fattore di scalabilità è 1x. Ciò consente un controllo più preciso sulle dimensioni del codice a barre per adattarsi ai requisiti di formattazione delle immagini RCS.

I valori di padding non vengono ridimensionati. Gli argomenti padded_width e padded_height rappresentano le dimensioni complete dell'area di disegno in pixel. Per le modalità URL e HTML, ognuna deve essere almeno 3 volte la larghezza o l'altezza corrispondente. Per mode=rcs, ognuna deve essere almeno la larghezza o l'altezza corrispondente perché RCS utilizza un ridimensionamento 1x. Per esempio:

{% barcode 'Code' width=200 height=100 padded_width=700 padded_height=400 %}

Qui, il codice a barre viene visualizzato a 600x300px (200×3, 100×3) all'interno di una tela imbottita 700x400px.

Dimensione massima dell'immagine: il servizio di codice a barre non genererà immagini di dimensioni superiori a 4096x4096 pixel. Questo limite si applica alle dimensioni del rendering dopo la scalatura. Per i codici a barre non RCS (scala 3x), ciò significa il massimo width L'argomento è circa 1365 (1365 × 3 = 4095px). Per i codici a barre RCS (scala 1x), il massimo è 4096.

Linee guida sulla larghezza per i codici lungi:

• Per i codici a barre non RCS: se il tuo codice supera i 15 caratteri, aumenta la larghezza oltre il valore predefinito di 100 (che viene visualizzato a 300px).
• Per i codici a barre RCS: se il tuo codice supera i 30 caratteri, aumenta la larghezza oltre il valore predefinito di 600px.

Se la larghezza è troppo stretta per codificare i dati, l'immagine del codice a barre non verrà generata.

Risoluzione dei problemi

Visualizza sempre l'anteprima prima dell'invio

Perché il {% barcode %} Il tag produce un URL al momento del rendering e l'immagine non viene generata fino a quando l'URL non viene recuperato. Gli errori potrebbero non essere evidenti fino a quando non visualizzi l'anteprima o invii il messaggio. Segui questi passaggi per individuare tempestivamente i problemi:

1. Visualizza l’anteprima del messaggio con un profilo che ha la proprietà richiesta e, per una variabile evento, l’evento pertinente. Se il codice a barre non si carica, controlla il valore, la sintassi del tag e le dimensioni prima di inviare.
2. Esegui la scansione del codice a barre. Usa uno strumento di scansione dei codici a barre (ad esempio imagetotext.info/barcode-scanner) per verificare che il codice a barre codifichi il valore previsto.
3. Invia un messaggio di prova prima di inviarlo al tuo pubblico.

Per i codici a barre dei coupon, un’anteprima in-app utilizza il nome del coupon seguito da -PREVIEW, non un codice coupon riscattabile. L’invio di un messaggio di prova può utilizzare un codice coupon disponibile. Controlla il valore scansionato e fai una prova con le lunghezze dei codici che invierai davvero.

Problemi comuni

L'immagine del codice a barre non viene caricata

La causa più comune è un valore di codice a barre vuoto. Questo avviene quando il tag fa riferimento a una proprietà del profilo o a una variabile evento che il destinatario non ha. Per esempio:

{% barcode person.BarcodeCode %}

Se il destinatario non ha alcun valore per BarcodeCode, nell’URL generato mancherà il codice e l’immagine non verrà visualizzata. Per risolvere il problema, aggiungi un filtro default. Sostituisci il fallback di esempio con un valore che il tuo scanner o il tuo sistema POS riconosce:

{% barcode person.BarcodeCode|default:'defaultCode' %}

L'immagine del codice a barre non viene generata, ma l'URL sembra corretto

Probabilmente la larghezza del codice a barre è troppo stretta per codificare tutti i dati del tuo codice. Prova ad aumentare width valore. Come regola generale:

• Per i codici a barre non RCS, i codici con più di 15 caratteri richiedono una larghezza superiore al valore predefinito 100 (300px renderizzati).
• I codici RCS di oltre 30 caratteri hanno bisogno di una larghezza superiore ai 600 px predefiniti.

Il codice a barre non appare in un blocco di testo (e-mail)

Controlla se al blocco di testo è applicata la logica mostra/nascondi. Se una condizione nasconde il blocco, il codice a barre non viene visualizzato anche se il tag è corretto. Apri le impostazioni del blocco per verificare.

Risorse aggiuntive

• Primi passi con i codici coupon in Klaviyo — Scopri come creare e gestire i codici coupon, incluso come usare la vecchia tag {% barcode_code %} per i codici a barre dei coupon nelle e-mail.
• Come aggiungere un’immagine dinamica a un messaggio di testo — Scopri come aggiungere immagini dinamiche ai messaggi MMS, incluso dove trovare la scheda Immagine dinamica nell’editor.
• Riferimento per la personalizzazione dei messaggi — Riferimento per tutti i tag di personalizzazione disponibili in Klaviyo, incluse le Proprietà del profilo, le variabili di evento e i filtri.
• Comprendere le best practice per immagini e GIF MMS — Best practice per dimensionamento e formattazione delle immagini nei messaggi MMS.