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

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 sem definição (ou defina como mode=url) para obter um URL e, depois, insira esse URL no campo URL da imagem do bloco de imagem. Assim, você tem mais controle sobre o estilo da imagem.

{% barcode 'MyCode' %}

MMS

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

1. Abra sua mensagem de MMS no editor.
2. Clique no ícone Adicionar imagem na caixa de mensagem.
3. Acesse a guia Imagem dinâmica.
4. Cole sua tag de código de barras, 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 formatar o código de barras de acordo com os requisitos de imagem do RCS. Esse modo define automaticamente dimensões que são exibidas corretamente no Android e no iOS.

{% barcode 'MyCode' mode=rcs %}

Adicione o tag de código de barras na seção Imagem dinâmica do editor de mensagens RCS, da mesma forma que você faria para MMS.

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

Para mensagens do WhatsApp, adicione a tag do código de barras na seção Imagem dinâmica do editor de mensagens, do mesmo jeito que você faria para MMS.

{% barcode person.MembershipId %}

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 o valor do código de barras, para que cada destinatário receba um código de barras exclusivo.

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: usar 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

Se você usa códigos de cupom gerenciados pela Klaviyo e quer renderizá-los como códigos de barras, defina coupon=True. Isso informa ao sistema para atribuir um código de cupom ao destinatário e usar esse código como o valor do código de barras.

{% 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 do código de barras são escalonadas 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

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 sempre representam valores reais em pixels. Como o código de barras interno é dimensionado em 3x, os valores de preenchimento devem ser maiores que 3 vezes a largura e a altura. 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. Se o código de barras não carregar na visualização, ele não vai carregar quando for enviado.
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.

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, o URL gerado ficará sem o código e a imagem não será renderizada. Para corrigir isso, adicione um filtro default:

{% 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:

• Códigos com mais de 15 caracteres precisam de uma largura maior do que o padrão 100 (300px renderizados).
• 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 MMS, incluindo onde encontrar a seção de 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.