메시지에 바코드를 추가하는 방법

학습 내용

{% barcode %} 태그를 사용해 이메일, MMS, RCS, WhatsApp 메시지에서 Code 128 바코드를 생성하는 방법을 알아보세요. 바코드 값은 고정 문자열, 프로필 속성, 이벤트 변수 또는 Klaviyo 쿠폰 코드일 수 있어요.

빠른 참조

시작하기 전에 알아야 할 것

{% barcode %} 태그는 URL을 생성하는 방식으로 작동해요. 해당 URL이 로드되면(미리보기, 받은편지함 또는 모바일 기기에서), 바코드의 PNG 이미지가 렌더링돼요. 즉, 바코드 이미지는 URL이 실제로 가져와질 때까지 생성되지 않아요.

{% barcode %} 태그는 다음에서 지원돼요:

• 이메일
• MMS
• RCS
• WhatsApp

기본 사용법

바코드 태그를 사용하는 가장 간단한 방법은 다음과 같아요:

{% barcode 'MyCode' %}

그러면 바코드의 PNG 이미지가 반환되는 URL이 생성됩니다. 스캔하면 바코드에 MyCode 값이 포함됩니다.

태그에 인수를 전달해 바코드를 맞춤 설정할 수 있어요. 예를 들면:

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

사용 가능한 모든 옵션은 아래의 인수 참조 섹션을 확인하세요.

서로 다른 채널에서 바코드 사용하기

이메일

이메일의 경우 바코드가 렌더링되는 방식에 두 가지 옵션이 있어요:

옵션 1: HTML 모드(이메일에 권장)

mode=html 을(를) 설정하면 태그가 HTML <img> 요소를 직접 출력해요. 이 방법은 이메일에 바코드를 포함하는 가장 간단한 방식이에요.

{% barcode 'MyCode' mode=html %}

이메일 템플릿 편집기에서 텍스트 블록 또는 HTML 블록에 이 태그를 넣어 주세요.

옵션 2: URL 모드

모드를 설정하지 않거나(또는 mode=url(으)로 설정) URL을 받은 다음, 해당 URL을 이미지 블록의 이미지 URL 필드에 넣어 주세요. 이렇게 하면 이미지 스타일을 더 세밀하게 제어할 수 있어요.

{% barcode 'MyCode' %}

MMS

MMS 메시지의 경우 SMS/MMS 편집기의 동적 이미지 섹션에 바코드 태그를 추가하고, 텍스트 본문에는 추가하지 마세요.

1. 편집기에서 MMS 메시지를 엽니다.
2. 메시지 상자에서 이미지 추가 아이콘을 클릭해 주세요.
3. 동적 이미지 탭으로 이동해 주세요.
4. 바코드 태그를 붙여넣으세요. 예:

{% barcode person.LoyaltyId %}

1. 저장을 클릭합니다.

이는 MMS에 동적 이미지를 추가하는 것과 동일한 과정을 따릅니다. 자세한 내용은 문자 메시지에 동적 이미지를 추가하는 방법을(를) 참고해 주세요.

RCS

RCS 메시지의 경우 mode=rcs 을(를) 사용해 RCS 이미지 요구 사항에 맞게 바코드를 포맷하세요. 이 모드는 Android와 iOS 모두에서 올바르게 표시되는 크기를 자동으로 설정해요.

{% barcode 'MyCode' mode=rcs %}

MMS에서처럼 RCS 메시지 편집기의 동적 이미지 섹션에 바코드 태그를 추가해 주세요.

RCS 기본 설정:

• 너비: 600px
• 높이: 300px
• 패딩 적용 크기: 1440x720px

이 기본값은 Klaviyo의 RCS 이미지 서식 권장 사항을 따릅니다. 필요한 경우 맞춤 width, height, padded_width, padded_height 값으로 재정의할 수 있어요.

WhatsApp

WhatsApp 메시지의 경우 MMS에서와 동일한 방식으로, 메시지 편집기의 동적 이미지 섹션에 바코드 태그를 추가해 주세요.

{% barcode person.MembershipId %}

WhatsApp에는 특별한 구성이나 모드가 필요하지 않아요. 기본 mode=url 이(가) 올바르게 작동해요.

바코드 태그 인수 참조

프로필 속성과 이벤트 데이터에서 바코드 사용하기

프로필 속성 또는 이벤트 변수를 바코드 값으로 사용할 수 있으므로, 각 수신자에게 고유한 바코드가 제공돼요.

프로필 속성 예시:

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

이벤트 변수 예시(지표 트리거 플로우용):

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

누락 값 처리:

수신자에게 해당 속성이 설정되어 있지 않으면 바코드 URL이 유효하지 않아 이미지가 로드되지 않아요. 두 가지 옵션이 있어요:

옵션 1: 의미 있는 대체 값을 설정하려면 default 필터 를 사용하세요:

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

스캔했을 때 의미가 통하는 값이 기본값인지 확인해 주세요. “fallback” 같은 일반적인 자리표시자는 스캔 가능한 바코드를 만들지만, 쓸모가 없어요.

옵션 2: 조건문을 사용 하여 값이 없을 때 바코드를 완전히 숨기세요:

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

이메일용 결합 예시:

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

바코드를 Klaviyo 쿠폰 코드와 함께 사용하기

Klaviyo에서 관리하는 쿠폰 코드를 사용하며 이를 바코드로 렌더링하려면 coupon=True을(를) 설정하세요. 이렇게 하면 시스템이 수신자에게 쿠폰 코드를 할당하고, 해당 코드를 바코드 값으로 사용해요.

{% barcode 'ShopifyCoupon' coupon=True %}

이 기능은 모든 채널에서 작동해요. 예를 들어 RCS로 쿠폰 바코드를 보내려면:

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

{% barcode person.CouponCode %}

스케일링 및 크기 조정

기본적으로 바코드의 너비와 높이는 3× 배율로 조정됩니다. 이는 다음을 의미합니다:

• 100개 중 width 가 300px 실제 너비로 렌더링됩니다
• 50회 렌더링 중 height 회는 실제 높이가 150px 예요.

예외: mode=rcs인 경우 스케일링 계수는 1x예요. 이렇게 하면 RCS 이미지 포맷 요구사항에 맞게 바코드 크기를 더 정밀하게 제어할 수 있어요.

패딩 값은 스케일링되지 않습니다. padded_width 및 padded_height 인수는 항상 실제 픽셀 값을 나타내요. 내부 바코드는 3×로 스케일링되므로 패딩 값은 너비와 높이의 3배보다 더 커야 해요. 예시:

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

여기에서는 700×400px 패딩 캔버스 안에서 바코드가 600×300px(200×3, 100×3)로 렌더링됩니다.

최대 이미지 크기: 바코드 서비스는 4096×4096픽셀보다 큰 이미지는 생성하지 않아요. 이 제한은 스케일링 후 렌더링된 크기에 적용돼요. RCS가 아닌 바코드(3× 스케일링)의 경우, 최대 width 인수는 약 1,365입니다(1,365×3=4,095px). RCS 바코드(1× 스케일링)의 경우, 최대값은 4,096입니다.

긴 번호에 대한 너비 가이드라인:

• RCS가 아닌 바코드의 경우: 코드가 15자를 초과하면 기본값 100(300px로 렌더링됨)보다 너비를 더 늘리세요.
• RCS 바코드의 경우: 코드가 30자를 초과하면 기본값인 600px보다 너비를 더 넓게 설정해 주세요.

데이터를 인코딩하기에 너비가 너무 좁으면 바코드 이미지가 생성되지 않아요.

문제 해결

보내기 전에 항상 미리보기로 확인해 주세요.

{% barcode %} 태그는 렌더링 시점에 URL을 생성하고 이미지는 해당 URL을 가져올 때까지 생성되지 않기 때문에, 실패가 메시지를 미리 보거나 전송할 때까지 눈에 띄지 않을 수 있어요. 다음 단계에 따라 문제를 조기에 발견하세요:

1. 메시지를 미리보기하세요. 미리보기에서 바코드가 로드되지 않으면, 전송할 때도 로드되지 않아요.
2. 바코드를 스캔해 주세요. 바코드 스캔 도구(예: imagetotext.info/barcode-scanner)를 사용해 바코드가 예상한 값을 인코딩하는지 확인해 주세요.
3. 잠재고객에게 발송하기 전에 본인에게 테스트 메시지를 보내세요.

일반적인 문제

바코드 이미지가 로드되지 않아요

가장 흔한 원인은 바코드 값이 비어 있는 경우예요. 이는 태그가 수신자에게 없는 프로필 속성 또는 이벤트 변수를 참조할 때 발생해요. 예를 들어:

{% barcode person.BarcodeCode %}

수신자에게 BarcodeCode 값이 없으면 생성된 URL에 코드가 누락되어 이미지가 렌더링되지 않아요. 이 문제를 해결하려면 default 필터를 추가해 주세요:

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

바코드 이미지가 생성되지 않지만 URL은 올바른 것 같아요.

바코드 너비가 너무 좁아서 코드의 모든 데이터를 인코딩하지 못할 가능성이 높아요. width 값을 높여보세요. 일반적으로는 다음과 같아요:

• 15자 넘는 코드는 기본값 100보다 더 넓은 너비가 필요해요(렌더링 시 300px).
• 30자를 초과하는 RCS 코드는 기본값인 600px보다 더 큰 너비가 필요해요.

바코드가 텍스트 블록(이메일)에 표시되지 않아요

텍스트 블록에 표시/숨기기 로직이 적용되어 있는지 확인하세요. 조건에 의해 블록이 숨겨져 있으면 태그가 올바르더라도 바코드가 렌더링되지 않습니다. 확인을 위해 블록의 설정을 여세요.

추가 자료

• Klaviyo에서 쿠폰 코드 시작하기 — 이메일에서 쿠폰 바코드에 기존 {% barcode_code %} 태그를 사용하는 방법을 포함해, 쿠폰 코드를 생성하고 관리하는 방법을 알아보세요.
• 문자 메시지에 동적 이미지를 추가하는 방법 ― 편집기에서 동적 이미지 섹션을 찾는 위치를 포함해 MMS 메시지에 동적 이미지를 추가하는 방법을 알아보세요.
• 메시지 맞춤 설정 참조 ― 프로필 속성, 이벤트 변수, 필터를 포함해 Klaviyo에서 사용할 수 있는 모든 맞춤 설정 태그에 대한 참조입니다.
• MMS 이미지 및 GIF 모범 사례 이해하기 — MMS 메시지에서 이미지 크기 및 서식 지정을 위한 모범 사례입니다.