Como adicionar códigos de barras às suas mensagens

O que você vai aprender

Aprenda a usar a tag {% barcode %} para gerar códigos de barras Code 128 nas suas mensagens de e-mail, MMS, RCS e WhatsApp. O valor do código de barras pode ser uma string estática, uma propriedade do perfil, uma variável de evento ou um código de cupom da Klaviyo.

Referência rápida

Antes de começar

A tag {% barcode %} funciona gerando um URL. Quando esse URL é carregado (em uma prévia, uma caixa de entrada ou um dispositivo móvel), ele renderiza uma imagem PNG do código de barras. Isso significa que a imagem do código de barras não é criada até que o URL seja realmente buscado.

A tag {% barcode %} é compatível com:

• E-mail
• MMS
• RCS
• WhatsApp

Para mensagens móveis, você precisa configurar o canal correspondente na sua conta. Imagens de código de barras de MMS só podem ser entregues onde o seu número de envio e o país do destinatário oferecem suporte a MMS. Consulte Como entender as melhores práticas para imagens e GIFs de MMS para países e tipos de número compatíveis.

Uso básico

A forma mais simples de usar a tag de código de barras é:

{% barcode 'MyCode' %}

Isso gera um URL que retorna uma imagem PNG de um código de barras. Quando escaneado, o código de barras contém o valor MyCode.

Você pode personalizar o código de barras passando argumentos para a tag. Por exemplo:

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

Consulte a seção de referência de argumentos abaixo para ver todas as opções disponíveis.

Usar códigos de barras com diferentes canais

E-mail

Para e-mail, você tem duas opções de como o código de barras é renderizado:

Opção 1: modo HTML (recomendado para e-mail)

Defina mode=html para que a tag gere diretamente um elemento HTML <img>. Essa é a abordagem mais simples para incluir um código de barras em um e-mail.

{% barcode 'MyCode' mode=html %}

Coloque esta tag em um bloco de texto ou bloco de HTML no editor de modelos de e-mail.

Opção 2: modo de URL

Deixe o modo não definido (ou defina mode=url) para gerar uma URL. Use esta opção com um bloco de imagem para controlar o estilo da imagem.

{% barcode 'MyCode' %}

1. Adicione um bloco de imagem ao modelo do seu e-mail e selecione-o.
2. Clique em Selecionar imagem e depois abra a guia Imagem dinâmica.
3. Cole a tag do código de barras em Variável ou URL dinâmicos.
4. Clique em Save.

MMS

Para mensagens MMS, adicione a tag de código de barras na aba Imagem dinâmica do editor de SMS/MMS, e não no corpo do texto.

1. Abra sua mensagem MMS no editor, selecione Conteúdo e ative Anexo.
2. Selecione Imagem e clique em Selecionar imagem. Se o editor mostrar Mídia, selecione essa opção e clique em Selecionar mídia.
3. Vá para a aba Imagem dinâmica.
4. Cole a tag do seu código de barras em Variável dinâmica ou URL dinâmica, por exemplo:

{% barcode person.LoyaltyId %}

1. Clique em Save.

Isso segue o mesmo processo de adicionar qualquer imagem dinâmica a um MMS. Para mais detalhes, veja Como adicionar uma imagem dinâmica a uma mensagem de texto.

RCS

Para mensagens RCS, use mode=rcs para aplicar o código de barras padrão e as dimensões padrão da tela para imagens RCS. Visualize e teste a mensagem nos tipos de dispositivo dos seus destinatários antes de enviar.

{% barcode 'MyCode' mode=rcs %}

1. No editor de mensagens do RCS, ative a seção Anexo do cartão.
2. Selecione Imagem e clique em Selecionar imagem. Se o editor mostrar Mídia, selecione essa opção e clique em Selecionar mídia.
3. Abra Imagem dinâmica, cole a tag de código de barras em Variável dinâmica ou URL dinâmica e clique em Salvar.

Padrões do RCS:

• Largura: 600px
• Altura: 300px
• Com preenchimento até: 1440x720px

Esses padrões seguem as recomendações de formatação de imagem RCS da Klaviyo. Você pode substituí-los por valores personalizados de width, height, padded_width e padded_height, se necessário.

WhatsApp

1. No editor de mensagens do WhatsApp, ative Cabeçalho e selecione Mídia.
2. Clique em Selecionar mídia e, em seguida, abra a aba Imagem dinâmica.
3. Cole a tag do seu código de barras em Variável dinâmica ou URL dinâmica, por exemplo:

{% barcode person.MembershipId %}

1. Clique em Save.

Nenhuma configuração especial ou modo é necessário para o WhatsApp. O padrão mode=url funciona corretamente.

Referência de argumentos de tag de código de barras

Como usar códigos de barras com Propriedades do perfil e dados de evento

Você pode usar Propriedades do perfil ou variáveis de evento como valor do código de barras para personalizá-lo para cada destinatário. Destinatários com o mesmo valor recebem o mesmo código de barras.

Exemplos de propriedades do perfil:

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

Exemplos de variáveis de evento (para fluxos disparados por métricas):

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

Como lidar com valores ausentes:

Se um destinatário não tiver a propriedade definida, o URL do código de barras será inválido e a imagem não será carregada. Você tem duas opções:

Opção 1: use um filtro default para definir um valor de fallback significativo:

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

Verifique se o padrão é um valor que faça sentido quando escaneado. Um placeholder genérico como "fallback" geraria um código de barras escaneável, mas inútil.

Opção 2 (e-mail): use uma instrução condicional para ocultar o código de barras completamente quando o valor estiver ausente:

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

Exemplo combinado para e-mail:

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

Uso de códigos de barras com código de cupom da Klaviyo

Primeiro, crie ou faça upload de um cupom no Klaviyo. Defina coupon=True e substitua ShopifyCoupon no exemplo abaixo pelo nome exato do cupom no Klaviyo. O Klaviyo atribui um código de cupom ao destinatário ou usa o código válido existente dele e codifica esse código no código de barras. Consulte Guia de introdução aos códigos de cupom no Klaviyo para requisitos de configuração e disponibilidade de cupons.

{% barcode 'ShopifyCoupon' coupon=True %}

Isso funciona em todos os canais. Por exemplo, para enviar um código de barras de cupom via RCS:

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

{% barcode person.CouponCode %}

Escalonamento e dimensionamento

Por padrão, a largura e a altura da imagem do código de barras gerado são dimensionadas por um fator de 3x. Isso significa:

• Um width de 100 é renderizado com 300px de largura real
• Um height de 50 renderizações com 150px de altura real

Em mode=html, a imagem do e-mail é exibida na largura e altura originais da tag. Por exemplo, width=100 height=50 gera uma imagem de 300x150px e define seu tamanho de exibição como 100x50px.

Exceção: quando mode=rcs, o fator de escala é 1x. Isso permite um controle mais preciso sobre as dimensões do código de barras para atender aos requisitos de formatação de imagem do RCS.

Os valores de preenchimento não são dimensionados. Os argumentos padded_width e padded_height representam o tamanho total da tela em pixels. Nos modos URL e HTML, cada um deve ter pelo menos 3 vezes a largura ou altura correspondente. Para mode=rcs, cada um deve ter pelo menos a largura ou altura correspondente, porque o RCS usa dimensionamento 1x. Por exemplo:

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

Aqui, o código de barras é renderizado a 600x300px (200×3, 100×3) dentro de uma tela com padding de 700x400px.

Tamanho máximo da imagem: o serviço de código de barras não vai gerar imagens maiores que 4096x4096 pixels. Esse limite se aplica ao tamanho renderizado após o redimensionamento. Para códigos de barras que não são RCS (dimensionamento de 3x), isso significa que o argumento width máximo é de aproximadamente 1365 (1365 × 3 = 4095px). Para códigos de barras RCS (dimensionamento de 1x), o máximo é 4096.

Diretrizes de largura para código longo:

• Para códigos de barras que não sejam RCS: se o seu código exceder 15 caracteres, aumente a largura além do padrão de 100 (que é renderizado em 300px).
• Para códigos de barras RCS: se o seu código exceder 30 caracteres, aumente a largura para além do padrão de 600px.

Se a largura for estreita demais para codificar os dados, a imagem do código de barras não será gerada.

Solução de problemas

Sempre faça uma prévia antes de enviar

Como a tag {% barcode %} gera uma URL no momento da renderização e a imagem só é gerada quando essa URL é buscada, as falhas podem não ficar aparentes até você pré-visualizar ou enviar a mensagem. Siga estas etapas para identificar problemas mais cedo:

1. Visualize a mensagem com um perfil que tenha a propriedade obrigatória e, para uma variável de evento, o evento relevante. Se o código de barras não carregar, verifique o valor, a sintaxe da tag e as dimensões antes de enviar.
2. Escaneie o código de barras. Use uma ferramenta de leitura de código de barras (como imagetotext.info/barcode-scanner) para verificar se o código de barras codifica o valor esperado.
3. Envie uma mensagem de teste para você mesmo antes de enviar para seu público.

Para códigos de barras de cupom, uma visualização no app usa o nome do cupom seguido de -PREVIEW, não um código de cupom resgatável. O envio de uma mensagem de teste pode usar um código de cupom disponível. Verifique o valor escaneado e teste com os comprimentos dos códigos que você realmente enviará.

Problemas comuns

A imagem do código de barras não carrega

A causa mais comum é um valor de código de barras vazio. Isso acontece quando a tag faz referência a uma Propriedades do perfil ou variável de evento que o destinatário não tem. Por exemplo:

{% barcode person.BarcodeCode %}

Se o destinatário não tiver um valor de BarcodeCode, a URL gerada vai ficar sem o código e a imagem não será exibida. Para corrigir isso, adicione um filtro de default. Substitua o fallback de exemplo por um valor que seu scanner ou sistema de ponto de venda reconheça:

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

A imagem do código de barras não é gerada, mas o URL parece correto

A largura do código de barras provavelmente é estreita demais para codificar todos os dados do seu código. Tente aumentar o valor de width. Como regra geral:

• Para códigos de barras não RCS, códigos com mais de 15 caracteres precisam de uma largura maior do que o padrão 100 (renderizado em 300px).
• Códigos RCS com mais de 30 caracteres precisam de uma largura maior do que o padrão de 600px.

O código de barras não aparece em um bloco de texto (e-mail)

Verifique se o bloco de texto tem lógica de mostrar/ocultar aplicada. Se uma condição estiver ocultando o bloco, o código de barras não será renderizado mesmo se a tag estiver correta. Abra as configurações do bloco para verificar.

Recursos adicionais

• Guia de introdução aos códigos de cupom na Klaviyo — Saiba como criar e gerenciar códigos de cupom, incluindo como usar a tag {% barcode_code %} mais antiga para códigos de barras de cupom no e-mail.
• Como adicionar uma imagem dinâmica a uma mensagem de texto — Saiba como adicionar imagens dinâmicas a mensagens de MMS, incluindo onde encontrar a aba Imagem dinâmica no editor.
• Referência de personalização de mensagens — Referência para todas as tags de personalização disponíveis no Klaviyo, incluindo propriedades do perfil, variáveis de evento e filtros.
• Entenda as práticas recomendadas para imagens e GIFs em MMS — Práticas recomendadas de dimensionamento e formatação de imagens em mensagens MMS.