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

학습 내용

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

빠른 참조

시작하기 전에 알아야 할 것

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

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

• 이메일
• MMS
• RCS
• WhatsApp

모바일 메시지를 사용하려면 계정에 해당 채널이 설정되어 있어야 해요. MMS 바코드 이미지는 발신 번호와 수신자의 국가에서 MMS를 지원하는 경우에만 전송할 수 있어요. 지원되는 국가와 번호 유형은 MMS 이미지 및 GIF 모범 사례 이해하기를 참고해 주세요.

기본 사용법

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

{% barcode 'MyCode' %}

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

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

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

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

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

이메일

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

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

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

{% barcode 'MyCode' mode=html %}

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

옵션 2: URL 모드

URL을 출력하려면 모드를 설정하지 않거나(또는 mode=url로 설정) 두세요. 이미지 스타일을 제어하려면 이미지 블록과 함께 이 옵션을 사용하세요.

{% barcode 'MyCode' %}

1. 이메일 템플릿에 이미지 블록을 추가하고 선택해 주세요.
2. 이미지 선택을 클릭한 다음 동적 이미지 탭을 여세요.
3. 바코드 태그를 동적 변수 또는 동적 URL에 붙여 넣으세요.
4. 저장을 클릭합니다.

MMS

MMS 메시지의 경우 바코드 태그는 텍스트 본문이 아니라 SMS/MMS 편집기의 동적 이미지 탭에 추가해 주세요.

1. 편집기에서 MMS 메시지를 열고 콘텐츠를 선택한 다음 첨부 파일을 켜세요.
2. 이미지를 선택한 다음 이미지 선택을 클릭하세요. 편집기에 미디어가 표시되면 해당 항목을 선택하고 대신 미디어 선택을 클릭하세요.
3. 동적 이미지 탭으로 이동해 주세요.
4. 바코드 태그를 동적 변수 또는 동적 URL에 붙여넣어 주세요(예:).

{% barcode person.LoyaltyId %}

1. 저장을 클릭합니다.

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

RCS

RCS 메시지의 경우 mode=rcs을(를) 사용해 RCS 이미지의 기본 바코드 및 캔버스 크기를 적용하세요. 전송하기 전에 수신자의 기기 유형에서 메시지를 미리 보고 테스트해 보세요.

{% barcode 'MyCode' mode=rcs %}

1. RCS 메시지 편집기에서 카드의 첨부 파일 섹션을 켜세요.
2. 이미지를 선택한 다음 이미지 선택을 클릭하세요. 편집기에 미디어가 표시되면 해당 항목을 선택하고 대신 미디어 선택을 클릭하세요.
3. 동적 이미지를 열고, 바코드 태그를 동적 변수 또는 동적 URL에 붙여 넣은 다음 저장을 클릭하세요.

RCS 기본 설정:

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

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

WhatsApp

1. WhatsApp 메시지 편집기에서 헤더를 켜고 미디어를 선택해 주세요.
2. 미디어 선택을 클릭한 다음 동적 이미지 탭을 열어 주세요.
3. 바코드 태그를 동적 변수 또는 동적 URL에 붙여넣어 주세요(예:).

{% barcode person.MembershipId %}

1. 저장을 클릭합니다.

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을(를) 설정하고 아래 예시의 ShopifyCoupon을(를) Klaviyo에서 쿠폰의 정확한 이름으로 바꿔 주세요. Klaviyo는 수신자에게 쿠폰 코드를 할당하거나 기존의 유효한 코드를 사용한 다음, 해당 코드를 바코드에 인코딩해요. 설정 및 쿠폰 사용 가능 여부 요구 사항은 Klaviyo에서 쿠폰 코드 시작하기를 참고해 주세요.

{% barcode 'ShopifyCoupon' coupon=True %}

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

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

{% barcode person.CouponCode %}

스케일링 및 크기 조정

기본적으로 생성된 바코드 이미지의 너비와 높이는 3x 배율로 조정돼요. 즉,

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

mode=html에서는 이메일 이미지가 태그의 원래 너비와 높이로 표시돼요. 예를 들어, width=100 height=50는 300x150px 이미지를 생성하고 표시 크기를 100x50px로 설정해요.

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

패딩 값은 스케일링되지 않습니다. padded_width 및 padded_height 인수는 픽셀 단위의 전체 캔버스 크기를 나타내요. URL 및 HTML 모드의 경우 각각은 해당 너비 또는 높이의 최소 3배여야 합니다. mode=rcs의 경우 RCS는 1x 스케일링을 사용하므로 각각은 해당 너비 또는 높이 이상이어야 합니다. 예를 들면 다음과 같습니다.

{% 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. 잠재고객에게 발송하기 전에 본인에게 테스트 메시지를 보내세요.

쿠폰 바코드의 경우 앱 내 미리보기에는 사용할 수 있는 쿠폰 코드가 아니라 쿠폰 이름 뒤에 -PREVIEW가 표시돼요. 테스트 메시지를 보내는 경우 사용 가능한 쿠폰 코드를 사용할 수 있어요. 스캔된 값을 확인하고, 실제로 전송할 코드 길이로 테스트해 보세요.

일반적인 문제

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

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

{% barcode person.BarcodeCode %}

수신자에게 BarcodeCode 값이 없으면 생성된 URL에 코드가 누락되어 이미지가 렌더링되지 않아요. 이 문제를 해결하려면 default 필터를 추가해 주세요. 예시 대체값을 스캐너 또는 POS 시스템에서 인식하는 값으로 바꿔 주세요:

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

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

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

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

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

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

추가 자료

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