Cómo agregar códigos de barras a tus mensajes
Objetivos del artículo
Descubre cómo usar la etiqueta {% barcode %} para generar códigos de barras Code 128 en tus mensajes de email, MMS, RCS y WhatsApp. El valor del código de barras puede ser una cadena estática, una propiedades del perfil, una variable de evento o un código de cupón de Klaviyo.
Referencia rápida
Canal | Modo | Dónde agregar la etiqueta |
|---|---|---|
Correo electrónico |
| Campo de URL de bloque de texto, bloque de HTML o bloque de imagen |
MMS |
| Sección de imagen dinámica |
RCS |
| Sección de imagen dinámica |
| Sección de imagen dinámica |
Antes de empezar
La etiqueta {% barcode %} funciona al generar una URL. Cuando se carga esa URL (en una vista previa, una bandeja de entrada o un dispositivo móvil), renderiza una imagen PNG del código de barras. Esto significa que la imagen del código de barras no se crea hasta que realmente se obtiene la URL.
La etiqueta {% barcode %} es compatible en:
- Correo electrónico
- MMS
- RCS
Si actualmente estás usando {% barcode_code %} del artículo Primeros pasos con códigos de cupón, la etiqueta {% barcode %} es el reemplazo recomendado. Admite todos los canales (no solo el correo electrónico) y funciona con cualquier valor, no solo con códigos de cupón de Klaviyo. La etiqueta {% barcode_code %} todavía funciona para las implementaciones existentes, pero los nuevos códigos de barras deben usar {% barcode %}.
Uso básico
La forma más sencilla de usar la etiqueta de código de barras es:
{% barcode 'MyCode' %}Esto genera una URL que devuelve una imagen PNG de un código de barras. Al escanearse, el código de barras contiene el valor MyCode.
Se requiere el valor del código de barras. La etiqueta siempre debe incluir un valor: ya sea una cadena estática entre comillas o una variable. Una etiqueta sin valor (o una variable que se resuelve como vacía) generará una URL no válida.
Puedes personalizar el código de barras pasando argumentos a la etiqueta. Por ejemplo:
{% barcode 'MyCode' width=200 height=100 %}Consulta la sección de referencia de argumentos a continuación para ver todas las opciones disponibles.
Usar códigos de barras con diferentes canales
Correo electrónico
Para el correo electrónico, tienes dos opciones para cómo se renderiza el código de barras:
Opción 1: modo HTML (recomendado para correo electrónico)
Configura mode=html para que la etiqueta muestre directamente un elemento HTML <img>. Esta es la forma más sencilla de incluir un código de barras en un correo electrónico.
{% barcode 'MyCode' mode=html %}Coloca esta etiqueta en un bloque de texto o un bloque HTML en el editor de plantillas de correo electrónico.
Opción 2: modo de URL
Deja el modo sin configurar (o establece mode=url) para obtener una URL y luego coloca esa URL en el campo URL de imagen de un bloque de imagen. Esto te da más control sobre el estilo de la imagen.
{% barcode 'MyCode' %}Si el código de barras no aparece en un bloque de texto, revisa si el bloque tiene aplicada una lógica de mostrar/ocultar que pueda estar ocultándolo.
MMS
Para mensajes MMS, agrega la etiqueta de código de barras en la sección Imagen dinámica del editor de SMS/MMS, no en el cuerpo del texto.
- Abre el mensaje MMS en el editor.
- Haz clic en el ícono Agregar imagen en el cuadro de mensaje.
- Ve a la pestaña Imagen dinámica.
- Pega tu etiqueta de código de barras, por ejemplo:
{% barcode person.LoyaltyId %}- Haz clic en Guardar.
Esto sigue el mismo proceso que agregar cualquier imagen dinámica a un MMS. Para obtener más información, consulta Cómo agregar una imagen dinámica a un mensaje de texto.
RCS
Para los mensajes de RCS, usa mode=rcs para dar formato al código de barras según los requisitos de imagen de RCS. Este modo establece automáticamente dimensiones que se muestran correctamente tanto en Android como en iOS.
{% barcode 'MyCode' mode=rcs %}Agrega la etiqueta del código de barras en la sección Imagen dinámica del editor de mensajes RCS, del mismo modo que lo harías para MMS.
Valores predeterminados de RCS:
- Ancho: 600px
- Altura: 300px
- Con relleno a: 1440x720px
Estos valores predeterminados siguen las recomendaciones de Klaviyo para el formato de imágenes de RCS. Puedes reemplazarlos con valores personalizados de width, height, padded_width y padded_height si es necesario.
Si las dimensiones personalizadas del código de barras superan 1440x720 px, no se aplicará el relleno predeterminado porque la imagen no cabrá en el lienzo estándar. En este caso, proporciona tus propios valores padded_width y padded_height.
Para los mensajes de WhatsApp, agrega la etiqueta de código de barras en la sección Imagen dinámica del editor de mensajes, del mismo modo que lo harías para MMS.
{% barcode person.MembershipId %}No se necesita ninguna configuración ni modo especial para WhatsApp. El valor predeterminado mode=url funciona correctamente.
Referencia de argumentos de etiqueta de código de barras
Argumento | Uso | Valores | Predeterminado |
|---|---|---|---|
| Configura el ancho del código de barras | Un número (el tamaño renderizado no debe superar los 4096 px; consulta Escalado y dimensionamiento) | 100 |
| Configura la altura del código de barras | Un número (el tamaño renderizado no debe superar los 4096 px; consulta Escalado y dimensionamiento) | 50 |
| Establece el formato de salida |
|
|
| Especifica que el valor es un código de cupón administrado por Klaviyo |
|
|
| Ancho del área de la imagen con relleno en píxeles. Se debe proporcionar con | Un número menor que 4096 | Ninguno (1440 para |
| Altura del área de imagen con relleno en píxeles. Se debe proporcionar con | Un número menor que 4096 | Ninguno (720 para |
Usar códigos de barras con propiedades del perfil y datos de eventos
Puedes usar propiedades del perfil o variables de eventos como el valor del código de barras, para que cada destinatario reciba un código de barras único.
Ejemplos de propiedades del perfil:
{% barcode person.LoyaltyId %}
{% barcode person.email %}
{% barcode person.MembershipNumber %}Ejemplos de variables de evento (para flujos activados por métricas):
{% barcode event.Code %}
{% barcode event.OrderId %}Manejo de valores faltantes:
Si un destinatario no tiene la propiedad configurada, la URL del código de barras no será válida y la imagen no se cargará. Tienes dos opciones:
Opción 1: Usa un filtro default para establecer un valor alternativo significativo:
{% barcode person.BarcodeCode|default:'STORE-MEMBER' %}Asegúrate de que el valor predeterminado tenga sentido si se escanea. Un marcador de posición genérico como "fallback" produciría un código de barras escaneable, pero inútil.
Opción 2: Usa una instrucción condicional para ocultar por completo el código de barras cuando falte el valor:
{% if person.BarcodeCode %}
{% barcode person.BarcodeCode mode=html %}
{% endif %}Maneja siempre el caso de valor faltante cuando el valor del código de barras provenga de una propiedad del perfil o de una variable de evento. Sin un valor predeterminado o una condición, los destinatarios a los que les falte esa propiedad verán una imagen dañada.
Ejemplo combinado para el correo electrónico:
{% barcode person.LoyaltyId width=200 height=75 mode=html %}Uso de códigos de cupón de Klaviyo con códigos de barras
Si usas códigos de cupón gestionados por Klaviyo y quieres mostrarlos como códigos de barras, configura coupon=True. Esto le indica al sistema que asigne un código de cupón al destinatario y use ese código como el valor del código de barras.
{% barcode 'ShopifyCoupon' coupon=True %}Esto funciona en todos los canales. Por ejemplo, para enviar un código de barras de cupón a través de RCS:
{% barcode 'ShopifyCoupon' coupon=True mode=rcs %}Solo establece coupon=True cuando uses códigos de cupón administrados por Klaviyo. Si gestionas tus propios códigos de cupón y los almacenas como una propiedad del perfil, haz referencia a la propiedad directamente sin coupon=True:
{% barcode person.CouponCode %}Escalado y tamaño
De forma predeterminada, el ancho y el alto del código de barras se escalan por un factor de 3x. Esto significa:
- Un
widthde 100 se renderiza con un ancho real de 300px - Un
heightde 50 se renderiza a una altura real de 150px
Excepción: Cuando mode=rcs, el factor de escala es 1x. Esto permite un control más preciso sobre las dimensiones del código de barras para cumplir con los requisitos de formato de imagen de RCS.
Los valores de relleno no se escalan. Los argumentos padded_width y padded_height siempre representan valores reales de píxeles. Como el código de barras interno se escala 3x, los valores de relleno deben ser más de 3 veces el ancho y el alto. Por ejemplo:
{% barcode 'Code' width=200 height=100 padded_width=700 padded_height=400 %}Aquí, el código de barras se renderiza a 600x300 px (200 × 3, 100 × 3) dentro de un lienzo con relleno de 700x400 px.
Tamaño máximo de la imagen: El servicio de códigos de barras no generará imágenes de más de 4096x4096 píxeles. Este límite se aplica al tamaño renderizado después de escalar. Para códigos de barras que no sean RCS (escalado de 3x), eso significa que el argumento width máximo es de aproximadamente 1365 (1365 × 3 = 4095px). Para códigos de barras RCS (escalado 1x), el máximo es 4096.
Lineamientos de ancho para códigos largos:
- Para códigos de barras que no sean RCS: si el código supera los 15 caracteres, aumenta el ancho más allá del valor predeterminado de 100 (que se muestra a 300 px).
- Para códigos de barras de RCS: si el código supera los 30 caracteres, aumenta el ancho más allá del valor predeterminado de 600px.
Si el ancho es demasiado estrecho para codificar los datos, la imagen del código de barras no se generará.
Guía de solución de problemas
Siempre revisa la vista previa antes de enviar
Dado que la etiqueta {% barcode %} genera una URL en el momento de renderización y la imagen no se genera hasta que se recupera esa URL, es posible que los errores no sean evidentes hasta que previsualices o envíes el mensaje. Sigue estos pasos para detectar problemas desde el principio:
- Obtén una vista previa del mensaje. Si el código de barras no se carga en la vista previa, no se cargará cuando se envíe.
- Escanea el código de barras. Usa una herramienta para escanear códigos de barras (como imagetotext.info/barcode-scanner) para verificar que el código de barras codifique el valor esperado.
- Envíate un mensaje de prueba antes de enviar a tu audiencia.
Problemas comunes
La imagen del código de barras no carga
La causa más común es un valor de código de barras vacío. Esto ocurre cuando la etiqueta hace referencia a una propiedad del perfil o variable de evento que el destinatario no tiene. Por ejemplo:
{% barcode person.BarcodeCode %}Si el destinatario no tiene un valor de BarcodeCode, la URL generada no incluirá el código y la imagen no se mostrará. Para solucionar esto, agrega un filtro de default:
{% barcode person.BarcodeCode|default:'defaultCode' %}La imagen del código de barras no se genera, pero la URL se ve correcta
Es probable que el ancho del código de barras sea demasiado estrecho para codificar todos los datos del código. Prueba aumentar el valor de width. Como regla general:
- Los códigos de más de 15 caracteres necesitan un ancho mayor que el predeterminado de 100 (300 px renderizados).
- Los códigos RCS de más de 30 caracteres necesitan un ancho mayor que los 600 px predeterminados.
El código de barras no aparece en un bloque de texto (correo electrónico)
Verifica si el bloque de texto tiene lógica de mostrar/ocultar aplicada. Si una condición está ocultando el bloque, el código de barras no se mostrará, incluso si la etiqueta es correcta. Abre la configuración del bloque para verificarlo.
Recursos adicionales
- Primeros pasos con códigos de cupón en Klaviyo — Descubre cómo crear y gestionar códigos de cupón, incluido cómo usar la etiqueta
{% barcode_code %}anterior para códigos de barras de cupones en email. - Cómo agregar una imagen dinámica a un mensaje de texto — Aprende a agregar imágenes dinámicas a mensajes MMS, incluido dónde encontrar la sección Imagen dinámica en el editor.
- Referencia de personalización de mensajes — Referencia de todas las etiquetas de personalización disponibles en Klaviyo, incluidas las propiedades del perfil, las variables de evento y los filtros.
- Comprender las prácticas recomendadas para imágenes y GIF en MMS — Prácticas recomendadas para el tamaño y el formato de las imágenes en los mensajes MMS.