Jak dodać kody kreskowe do wiadomości

Czego się dowiesz?

Dowiedz się, jak używać znacznika {% barcode %} do generowania kodów kreskowych Code 128 w wiadomościach e-mail, MMS, RCS i WhatsApp. Wartość kodu kreskowego może być ciągiem statycznym, właściwością profilu, zmienną zdarzenia lub kodem kuponu Klaviyo.

Szybkie informacje

Kilka słów na początek

Znacznik {% barcode %} działa, generując adres URL. Gdy ten adres URL zostanie wczytany (w podglądzie, w skrzynce odbiorczej lub na urządzeniu mobilnym), renderuje obraz PNG kodu kreskowego. Oznacza to, że obraz kodu kreskowego nie jest tworzony, dopóki adres URL nie zostanie faktycznie pobrany.

Znacznik {% barcode %} jest obsługiwany w:

• Adres e-mail
• MMS
• RCS
• WhatsApp

Podstawowe użycie

Najprostszy sposób użycia znacznika kodu kreskowego to:

{% barcode 'MyCode' %}

Powoduje to utworzenie adresu URL, który zwraca obraz PNG kodu kreskowego. Po zeskanowaniu kod kreskowy zawiera wartość MyCode.

Kod kreskowy możesz dostosować, przekazując argumenty do znacznika. Na przykład:

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

W sekcji referencyjnej argumentów poniżej znajdziesz wszystkie dostępne opcje.

Używanie kodów kreskowych w różnych kanałach

Adres e-mail

W przypadku e-maili masz dwie opcje dotyczące sposobu renderowania kodu kreskowego:

Opcja 1: tryb HTML (zalecany w przypadku e-maili)

Ustaw mode=html, aby znacznik zwracał bezpośrednio element HTML <img>. To najprostsze podejście do dodania kodu kreskowego w e-mailu.

{% barcode 'MyCode' mode=html %}

Umieść ten znacznik w bloku tekstowym lub bloku HTML w edytorze szablonów e-maili.

Opcja 2: tryb URL

Pozostaw tryb nieustawiony (lub ustaw mode=url), aby uzyskać URL, a następnie wklej ten URL w polu URL obrazu w bloku obrazu. Daje to większą kontrolę nad stylizacją obrazu.

{% barcode 'MyCode' %}

MMS

W przypadku wiadomości MMS dodaj znacznik kodu kreskowego w sekcji Obraz dynamiczny edytora SMS/MMS, a nie w treści tekstu.

1. Otwórz wiadomość MMS w edytorze.
2. Kliknij ikonę Dodaj obraz w polu wiadomości.
3. Przejdź do karty Obraz dynamiczny.
4. Wklej znacznik kodu kreskowego, na przykład:

{% barcode person.LoyaltyId %}

1. Kliknij Zapisz.

To przebiega według tego samego procesu co dodawanie dowolnego obrazu dynamicznego do MMS-a. Więcej informacji znajdziesz w artykule Jak dodać obraz dynamiczny do wiadomości tekstowej.

RCS

W przypadku wiadomości RCS użyj mode=rcs, aby sformatować kod kreskowy zgodnie z wymaganiami dotyczącymi obrazów RCS. Ten tryb automatycznie ustawia wymiary, które wyświetlają się poprawnie zarówno na Androidzie, jak i na iOS.

{% barcode 'MyCode' mode=rcs %}

Dodaj znacznik kodu kreskowego w sekcji Obraz dynamiczny w edytorze wiadomości RCS, tak samo jak w przypadku MMS.

Ustawienia domyślne RCS:

• Szerokość: 600px
• Wysokość: 300px
• Z wypełnieniem do: 1440x720 px

Te ustawienia domyślne są zgodne z zaleceniami Klaviyo dotyczącymi formatowania obrazów RCS. W razie potrzeby można je zastąpić niestandardowymi wartościami width, height, padded_width i padded_height.

WhatsApp

W przypadku wiadomości WhatsApp dodaj znacznik kodu kreskowego w sekcji Obraz dynamiczny w edytorze wiadomości — tak samo jak w przypadku MMS.

{% barcode person.MembershipId %}

WhatsApp nie wymaga żadnej specjalnej konfiguracji ani trybu. Domyślne mode=url działa poprawnie.

Dokumentacja argumentów znacznika kodu kreskowego

Używanie kodów kreskowych z właściwościami profilu i danymi zdarzeń

Możesz użyć właściwości profilu lub zmiennych zdarzeń jako wartości kodu kreskowego, dzięki czemu każdy odbiorca otrzyma unikalny kod kreskowy.

Przykłady właściwości profilu:

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

Przykłady zmiennych zdarzeń (dla sekwencji uruchamianych metryką):

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

Obsługa brakujących wartości:

Jeśli odbiorca nie ma ustawionej tej właściwości, adres URL kodu kreskowego będzie nieprawidłowy i obraz nie zostanie załadowany. Dostępne są dwie opcje:

Opcja 1: użyj filtra default , aby ustawić sensowną wartość zastępczą:

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

Upewnij się, że domyślna wartość ma sens po zeskanowaniu. Ogólny symbol zastępczy, taki jak "fallback", spowodowałby utworzenie możliwego do zeskanowania, ale bezużytecznego kodu kreskowego.

Opcja 2: Użyj instrukcji warunkowej, aby całkowicie ukryć kod kreskowy, gdy brakuje wartości:

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

Połączony przykład dla e-maila:

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

Używanie kodów kreskowych z kodami kuponu Klaviyo

Jeśli używasz kodów kuponu zarządzanych przez Klaviyo i chcesz renderować je jako kody kreskowe, ustaw coupon=True. To mówi systemowi, aby przypisał kod kuponu do odbiorcy i użył tego kodu jako wartości kodu kreskowego.

{% barcode 'ShopifyCoupon' coupon=True %}

To działa we wszystkich kanałach. Na przykład, aby wysłać kod kreskowy kuponu przez RCS:

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

{% barcode person.CouponCode %}

Skalowanie i zmiana rozmiaru

Domyślnie szerokość i wysokość kodu kreskowego są skalowane współczynnikiem 3x. Oznacza to:

• width ze 100 renderuje się przy rzeczywistej szerokości 300 px
• height z 50 renderów przy rzeczywistej wysokości 150px

Wyjątek: Gdy mode=rcs, współczynnik skalowania wynosi 1x. Umożliwia to bardziej precyzyjną kontrolę wymiarów kodu kreskowego, aby spełnić wymagania formatowania obrazu RCS.

Wartości dopełnienia nie są skalowane. Argumenty padded_width i padded_height zawsze reprezentują rzeczywiste wartości w pikselach. Ponieważ wewnętrzny kod kreskowy jest skalowany 3x, wartości dopełnienia muszą być większe niż 3 razy szerokość i wysokość. Na przykład:

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

Tutaj kod kreskowy renderuje się w rozmiarze 600x300px (200×3, 100×3) w obrębie wypełnionego marginesami obszaru roboczego 700x400px.

Maksymalny rozmiar obrazu: usługa kodów kreskowych nie wygeneruje obrazów większych niż 4096x4096 pikseli. Ten limit dotyczy rozmiaru wynikowego po skalowaniu. W przypadku kodów kreskowych innych niż RCS (skalowanie 3x) oznacza to, że maksymalny argument width wynosi około 1365 (1365 × 3 = 4095px). W przypadku kodów kreskowych RCS (skalowanie 1x) maksymalna wartość to 4096.

Wskazówki dotyczące szerokości w przypadku długich numerów (do wysyłki SMS-ów):

• W przypadku kodów kreskowych innych niż RCS: jeśli kod przekracza 15 znaków, zwiększ szerokość powyżej domyślnej wartości 100 (która renderuje się jako 300 px).
• W przypadku kodów kreskowych RCS: jeśli kod przekracza 30 znaków, zwiększ szerokość powyżej domyślnej wartości 600 px.

Jeśli szerokość będzie zbyt mała, aby zakodować dane, obraz kodu kreskowego nie zostanie wygenerowany.

Rozwiązywanie problemów

Zawsze zrób podgląd przed wysłaniem

Ponieważ znacznik {% barcode %} tworzy adres URL w czasie renderowania, a obraz nie jest generowany, dopóki ten adres URL nie zostanie pobrany, awarie mogą nie być widoczne, dopóki nie wyświetlisz podglądu lub nie wyślesz wiadomości. Wykonaj te kroki, aby wcześnie wychwycić problemy:

1. Wyświetl podgląd wiadomości. Jeśli kod kreskowy nie wczytuje się w podglądzie, nie wczyta się po wysłaniu.
2. Zeskanuj kod kreskowy. Użyj narzędzia do skanowania kodów kreskowych (np. imagetotext.info/barcode-scanner), aby sprawdzić, czy kod kreskowy koduje oczekiwaną wartość.
3. Wyślij do siebie wiadomość testową przed wysłaniem jej do odbiorców.

Typowe problemy

Obraz kodu kreskowego nie wczytuje się

Najczęstszą przyczyną jest pusta wartość kodu kreskowego. Dzieje się tak, gdy znacznik odwołuje się do właściwości profilu lub zmiennej zdarzenia, której odbiorca nie ma. Na przykład:

{% barcode person.BarcodeCode %}

Jeśli odbiorca nie ma wartości BarcodeCode, wygenerowany adres URL nie będzie zawierać kodu, a obraz nie zostanie wyrenderowany. Aby to naprawić, dodaj filtr default:

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

Obraz kodu kreskowego nie generuje się, ale adres URL wygląda poprawnie

Szerokość kodu kreskowego jest prawdopodobnie zbyt mała, aby zakodować wszystkie dane w Twoim kodzie. Spróbuj zwiększyć wartość width. Ogólna zasada:

• Kody dłuższe niż 15 znaków wymagają szerokości większej niż domyślne 100 (po wyrenderowaniu 300 px).
• Kody RCS dłuższe niż 30 znaków wymagają szerokości większej niż domyślne 600px.

Kod kreskowy nie wyświetla się w bloku tekstowym (e-mail)

Sprawdź, czy do bloku tekstowego zastosowano logikę pokazywania/ukrywania. Jeśli warunek ukrywa blok, kod kreskowy nie zostanie wyrenderowany, nawet jeśli znacznik jest poprawny. Otwórz ustawienia bloku, aby to zweryfikować.

Dodatkowe źródła

• Pierwsze kroki z kodami kuponu w Klaviyo — Dowiedz się, jak tworzyć kody kuponu i nimi zarządzać, w tym jak używać starszego znacznika {% barcode_code %} dla kodów kreskowych kuponów w e-mailach.
• Jak dodać obraz dynamiczny do wiadomości tekstowej — Dowiedz się, jak dodawać obrazy dynamiczne do wiadomości MMS, w tym gdzie znaleźć sekcję Obraz dynamiczny w edytorze.
• Informacje referencyjne o personalizacji wiadomości — Informacje referencyjne dotyczące wszystkich znaczników personalizacji dostępnych w Klaviyo, w tym właściwości profilu, zmiennych zdarzeń i filtrów.
• Najlepsze praktyki dotyczące obrazów i plików GIF w MMS — Najlepsze praktyki dotyczące rozmiaru i formatowania obrazów w wiadomościach MMS.