如何将条形码添加到您的消息中

你将会学到

了解如何使用“{% Barcode %}”标签在电子邮件、彩信、RCS 和 WhatsApp 消息中生成 Code 128 条形码。条形码值可以是静态字符串、配置文件属性、事件变量或 Klaviyo 优惠券代码。

快速参考

开始之前

{% Barcode %} 标签通过生成 URL 来工作。当加载该 URL 时（在预览、收件箱或移动设备中），它会呈现条形码的 PNG 图像。这意味着在实际获取 URL 之前不会创建条形码图像。 {% Barcode %} 标签受以下版本支持：

• 电子邮件
• 彩信
• RCS
• WhatsApp

如果您当前使用优惠券代码入门文章中的“{%barcode_code%}”，则建议替换“{%barcode_code%}”标签。它支持所有渠道（不仅仅是电子邮件）并且适用于任何价值，而不仅仅是 Klaviyo 优惠券代码。 “{% Barcode_code %}”标签仍然适用于现有实现，但新条形码应使用“{% Barcode %}”。

基本用法

使用条形码标签最简单的方法是：

{% 条形码 'MyCode' %}

这会生成一个返回条形码 PNG 图像的 URL。扫描时，条形码包含值“MyCode”。条形码值是必需的。标记必须始终包含一个值 – 引号中的静态字符串或变量。没有值的标记（或解析为空的变量）将生成无效的 URL。您可以通过向标签传递参数来自定义条形码。例如：

{% 条形码 'MyCode' 宽度=200 高度=100 %}

有关所有可用选项，请参阅下面的参数参考部分。

使用不同通道的条形码

电子邮件

对于电子邮件，对于条形码的呈现方式，您有两种选择：

选项 1：HTML 模式（推荐用于电子邮件）

设置 mode=html 使标签直接输出 HTML <img> 元素。这是在电子邮件中包含条形码的最简单方法。 ““ {% 条形码 ‘MyCode’ 模式=html %}

将此标签放置在电子邮件模板编辑器的文本块或 HTML 块中。 **选项 2：URL 模式**

保持模式未设置（或设置 `mode=url`）以获取 URL，然后将该 URL 放入图像块的图像 URL 字段中。这使您可以更好地控制图像样式。 ````
{% 条形码 'MyCode' %}

如果条形码没有出现在文本块中，请检查该块是否应用了可能隐藏它的显示/隐藏逻辑。

彩信

对于彩信，请在短信/彩信编辑器的动态图像部分添加条形码标签，而不是在文本正文中。

1. 在编辑器中打开您的彩信。
2. 单击消息框中的添加图像 图标。
3. 转到动态图像选项卡。
4. 粘贴您的条形码标签，例如：

   {% 条码人员.LoyaltyId %}

5. 单击保存。这遵循与将任何动态图像添加到彩信相同的过程。更多详情请参见【如何在短信中添加动态图片】(https://help.klaviyo.com/hc/en-us/articles/1260806102230)。

RCS

对于 RCS 消息，请使用“mode=rcs”来格式化条形码以满足 RCS 图像要求。此模式会自动设置在 Android 和 iOS 上正确显示的尺寸。 ““ {% 条形码 ‘MyCode’ 模式=rcs %}

在 RCS 消息编辑器的动态图像部分添加条形码标签，与彩信的操作方式相同。 **RCS 默认值：**

- 宽度：600 像素
- 高度：300 像素
- 填充至：1440x720px

这些默认值遵循 Klaviyo 的 RCS 图像格式建议。如果需要，您可以使用自定义的“width”、“height”、“padded_width”和“pagged_height”值覆盖它们。如果您的自定义条形码尺寸超过 1440x720 像素，则不会应用默认填充，因为图像不适合标准画布。在这种情况下，请提供您自己的“padded_width”和“pagged_height”值。

### WhatsApp

对于 WhatsApp 消息，请在消息编辑器的动态图像部分中添加条形码标签，与彩信的操作方式相同。 ````
{% 条形码 person.MembershipId %}

WhatsApp 不需要特殊配置或模式。默认的 mode=url 可以正常工作。

条形码标签参数参考

| 宽度 |设置条形码的宽度 |数字（渲染大小不得超过 4096px；请参阅缩放和大小调整）| 100 | 100 | 高度 |设置条形码的高度 |数字（渲染大小不得超过 4096px；请参阅缩放和大小调整）| 50 | 50

将条形码与配置文件属性和事件数据结合使用

您可以使用配置文件属性或事件变量作为条形码值，以便每个收件人获得唯一的条形码。 配置文件属性示例：

{% 条码人员.LoyaltyId %}
{% 条形码 person.email %}
{% 条形码 person.MembershipNumber %}

事件变量示例（对于指标触发的流）：

{% 条形码事件.代码 %}
{% 条码事件.OrderId %}

处理缺失值：

如果收件人未设置该属性，则条形码 URL 将无效，并且不会加载图像。您有两个选择：

选项 1：使用 default filter 设置有意义的后备值：

{% 条形码 person.BarcodeCode|默认值:'STORE-MEMBER' %}

确保默认值在扫描时有意义。像“后备”这样的通用占位符会生成可扫描但无用的条形码。 选项 2：使用条件语句 当值丢失时完全隐藏条形码：

{% if person.BarcodeCode %}
  {% 条形码 person.BarcodeCode mode=html %}
{% 结束 %}

当条形码值来自配置文件属性或事件变量时，始终处理缺失值的情况。如果没有默认值或条件，缺少该属性的收件人将看到损坏的图像。 电子邮件的组合示例：

{% 条形码 person.LoyaltyId width=200 height=75 mode=html %}

使用带有 Klaviyo 优惠券代码的条形码

如果您使用 Klaviyo 管理的优惠券代码并希望将其呈现为条形码，请设置“coupon=True”。这告诉系统向收件人分配优惠券代码并使用该代码作为条形码值。 ““ {% 条形码 ‘ShopifyCoupon’ 优惠券=True %}

这适用于所有渠道。例如，要通过 RCS 发送优惠券条形码：

{% 条形码 ‘ShopifyCoupon’ 优惠券=真实模式=rcs %}

仅在使用 Klaviyo 管理的优惠券代码时设置“coupon=True”。如果您管理自己的优惠券代码并将其存储为配置文件属性，请直接引用该属性，而无需使用“coupon=True”：

{% 条形码 person.CouponCode %}

## 缩放和调整大小

默认情况下，条形码的宽度和高度按系数 **3x** 缩放。这意味着：

- 100 的“宽度”以 **300px** 实际宽度渲染
- 50 的“高度”以 **150px** 实际高度渲染

  **例外：** 当`mode=rcs`时，缩放因子为**1x**。这样可以更精确地控制条形码尺寸，以满足 RCS 图像格式要求。 **填充值不会缩放。** `padded_width` 和 `padded_height` 参数始终表示实际的像素值。由于内部条形码缩放了 3 倍，因此您的填充值必须大于宽度和高度的 3 倍。例如：

{% 条形码’代码’ 宽度=200 高度=100 padded_width=700 padded_height=400 %}

  此处，条形码在 700x400 像素的填充画布中以 600x300 像素（200×3、100×3）渲染。 **最大图像尺寸：** 条形码服务不会生成大于**4096x4096 像素**的图像。此限制适用于缩放后的**渲染**尺寸。对于非 RCS 条形码（3 倍缩放），这意味着最大“宽度”参数约为 1365（1365 × 3 = 4095 像素）。对于 RCS 条形码（1 倍缩放），最大值为 4096。 **长代码的宽度指南：**
- 对于非 RCS 条形码：如果您的代码超过 **15 个字符**，请将宽度增加到默认值 100 之外（以 300 像素呈现）。 - 对于 RCS 条形码：如果您的代码超过 **30 个字符**，请将宽度增加到默认值 600 像素以上。如果宽度太窄而无法编码数据，则条形码图像将无法生成。

## 故障排除

### 发送前始终预览

由于“{% Barcode %}”标记在渲染时生成 URL，并且在获取该 URL 之前不会生成图像，因此在预览或发送消息之前，失败可能不会明显。请按照以下步骤尽早发现问题：

1. **预览消息。** 如果条形码在预览中未加载，则发送时也不会加载。
2. **扫描条形码。** 使用条形码扫描工具（例如 [imagetotext.info/barcode-scanner](https://www.imagetotext.info/barcode-scanner)）验证条形码编码是否为预期值。 3.**在发送给观众之前，先向自己发送一条测试消息**。

### 常见问题

**条形码图像无法加载**

最常见的原因是条形码值为空。当标记引用收件人没有的配置文件属性或事件变量时，就会发生这种情况。例如：

{% 条码人.BarcodeCode %}

如果收件人没有“BarcodeCode”值，则生成的 URL 将缺少代码，并且图像将无法呈现。要解决此问题，请添加“默认”过滤器：

{% 条形码 person.BarcodeCode|default:’defaultCode’ %}

**条形码图像无法生成，但URL看起来正确**

条形码宽度可能太窄，无法对代码中的所有数据进行编码。尝试增加“宽度”值。根据经验：

- 超过 15 个字符的代码需要大于默认 100（呈现 300 像素）的宽度。 - 超过 30 个字符的 RCS 代码需要大于默认 600px 的宽度。 **条形码未出现在文本块（电子邮件）中**

检查文本块是否应用了显示/隐藏逻辑。如果某个条件隐藏了该块，则即使标签正确，条形码也不会呈现。打开块的设置进行验证。

## 其他资源

- [Klaviyo 中的优惠券代码入门](https://help.klaviyo.com/hc/en-us/articles/115005084727) — 了解如何创建和管理优惠券代码，包括如何在电子邮件中使用旧的“{% Barcode_code %}”标签作为优惠券条形码。 - [如何向短信添加动态图像](https://help.klaviyo.com/hc/en-us/articles/1260806102230) — 了解如何向彩信添加动态图像，包括在编辑器中的何处找到“动态图像”部分。 - [消息个性化参考](https://help.klaviyo.com/hc/en-us/articles/4408802648731) — Klaviyo 中可用的所有个性化标签的参考，包括配置文件属性、事件变量和过滤器。 - [了解 MMS 图像和 GIF 最佳实践](https://help.klaviyo.com/hc/en-us/articles/360041074911) — MMS 消息中图像大小和格式的最佳实践。