So fügst du Barcodes zu deinen Nachrichten hinzu
Übersicht
Erfahre, wie du den {% barcode %} -Tag verwendest, um Code 128 -Barcodes in deinen E-Mail-, MMS-, RCS- und WhatsApp-Nachrichten zu generieren. Der Barcode-Wert kann eine statische Zeichenfolge, eine Profileigenschaft, eine Ereignisvariable oder ein Klaviyo-Gutscheincode sein.
Kurzübersicht
Kanal | Modus | Wo fügst du das Tag hinzu? |
|---|---|---|
| Textblock, HTML-Block oder Bildblock-URL-Feld | |
MMS |
| Abschnitt „Dynamisches Bild“ |
RCS |
| Abschnitt „Dynamisches Bild“ |
| Abschnitt „Dynamisches Bild“ |
Bevor du anfängst
Die {% barcode %} funktioniert, indem es eine URL generiert. Wenn diese URL geladen wird (in einer Vorschau, einem Posteingang oder einem mobilen Gerät), wird ein PNG-Bild des Barcodes gerendert. Das bedeutet, dass das Barcode-Bild erst erstellt wird, wenn die URL tatsächlich abgerufen wurde.
Die {% barcode %} Tag wird unterstützt in:
- MMS
- RCS
Wenn du derzeit {% barcode_code %} aus dem Artikel Erste Schritte mit Gutscheincodes verwendest, ist das {% barcode %} -Tag der empfohlene Ersatz. Es unterstützt alle Kanäle (nicht nur E-Mail) und funktioniert mit jedem Wert, nicht nur mit Klaviyo-Gutscheincodes. Das {% barcode_code %} -Tag funktioniert weiterhin für bestehende Implementierungen, aber neue Barcodes sollten {% barcode %} verwenden.
Grundlegende Nutzung
Der einfachste Weg, das Barcode-Tag zu verwenden, ist:
{% barcode 'MyCode' %}Dadurch wird eine URL erstellt, die ein PNG-Bild eines Barcodes zurückgibt. Beim Scannen enthält der Barcode den Wert MyCode.
Der Barcode-Wert ist erforderlich. Das Tag muss immer einen Wert enthalten – entweder eine statische Zeichenfolge in Anführungszeichen oder eine Variable. Ein Tag ohne Wert (oder eine Variable, die leer wird) erzeugt eine ungültige URL.
Du kannst den Barcode anpassen, indem du Argumente an das Tag übergibst. Zum Beispiel:
{% barcode 'MyCode' width=200 height=100 %}Alle verfügbaren Optionen findest du im Abschnitt zum Verweis auf Argumente unten.
Verwendung von Barcodes mit verschiedenen Kanälen
Für die E-Mail hast du zwei Möglichkeiten, wie der Barcode dargestellt wird:
Option 1: HTML-Modus (empfohlen für E-Mail)
Festlegen mode=html um das Tag als HTML-Code auszugeben <img> Element direkt. Dies ist der einfachste Ansatz, um einen Barcode in eine E-Mail einzufügen.
{% barcode 'MyCode' mode=html %}Platziere dieses Tag in einem Textblock oder HTML-Block im E-Mail-Vorlagen-Editor.
Option 2: URL-Modus
Lass den Modus uneingestellt (oder setze mode=url), um eine URL zu erhalten, platzieren Sie diese URL im Feld Bild-URL eines Bildblocks. So hast du mehr Kontrolle über das Bilddesign.
{% barcode 'MyCode' %}Wenn der Barcode nicht in einem Textblock erscheint, überprüfe, ob die Logik zum Ein- und Ausblenden auf den Block angewendet wurde, die ihn möglicherweise ausblendet.
MMS
Bei MMS-Nachrichten fügst du das Barcode-Tag im Abschnitt Dynamic Image des SMS/MMS-Editors und nicht im Textkörper ein.
- Öffne deine MMS-Nachricht im Editor.
- Klicke im Nachrichtenfeld auf das Symbol Bild hinzufügen.
- Gehe zur Registerkarte „Dynamisches Bild“.
- Füge dein Barcode-Tag ein, zum Beispiel:
{% barcode person.LoyaltyId %}- Klicke auf Speichern.
Das folgt demselben Prozess wie das Hinzufügen eines dynamischen Bilds zu einer MMS. Weitere Details findest du unter So fügst du einer Textnachricht ein dynamisches Bild hinzu.
RCS
Für RCS-Nachrichten verwendest du mode=rcs um den Barcode für RCS-Bildanforderungen zu formatieren. Dieser Modus legt automatisch die Abmessungen fest, die sowohl auf Android als auch auf iOS korrekt angezeigt werden.
{% barcode 'MyCode' mode=rcs %}Füge das Barcode-Tag im Abschnitt „Dynamisches Bild“ des RCS-Nachrichten-Editors hinzu, genauso wie du es bei MMS tun würdest.
RCS-Standardwerte:
- Breite: 600 px
- Höhe: 300 px
- Innenabstand: 1440x720px
Diese Standardwerte entsprechen den RCS-Bildformatierungsempfehlungen von Klaviyo. Du kannst sie mit benutzerdefinierten width, height, padded_widthund padded_height Werte, falls erforderlich.
Wenn deine benutzerdefinierten Barcode-Abmessungen 1440x720px überschreiten, wird der Standardabstand nicht angewendet, da das Bild nicht in den Standardbereich passt. Gib in diesem Fall deinen eigenen an padded_width und padded_height Werte.
Füge bei WhatsApp-Nachrichten das Barcode-Tag im Abschnitt „Dynamische Bilder“ des Nachrichten-Editors hinzu, genauso wie bei MMS.
{% barcode person.MembershipId %}Für WhatsApp ist keine spezielle Konfiguration oder ein spezieller Modus erforderlich. Der Standard mode=url richtig funktioniert.
Referenz zu Barcode-Tag-Argumenten
Argument | Nutzung | Werte | Standard |
|---|---|---|---|
| Legt die Breite des Barcodes fest | Eine Zahl (gerenderte Größe darf 4096 px nicht überschreiten; siehe Skalieren und Größe) | 100 |
| Legt die Höhe des Barcodes fest | Eine Zahl (gerenderte Größe darf 4096 px nicht überschreiten; siehe Skalieren und Größe) | 50 |
| Legt das Ausgabeformat fest |
|
|
| Gibt an, dass der Wert ein von Klaviyo verwalteter Gutscheincode ist |
|
|
| Breite des aufgefüllten Bildbereichs in Pixeln. Muss angegeben werden mit | Eine Zahl kleiner als 4096 | Keine (1440 für |
| Höhe des aufgefüllten Bildbereichs in Pixeln. Muss angegeben werden mit | Eine Zahl kleiner als 4096 | Keine (720 für |
Verwendung von Barcodes mit Profileigenschaften und Ereignisdaten
Du kannst Profileigenschaften oder Ereignisvariablen als Barcode-Wert verwenden, damit jeder Empfänger einen eindeutigen Barcode erhält.
Beispiele für Profileigenschaften:
{% barcode person.LoyaltyId %}
{% barcode person.email %}
{% barcode person.MembershipNumber %}Beispiele für Ereignisvariablen (für Flows mit Metrikauslöser):
{% barcode event.Code %}
{% barcode event.OrderId %}Umgang mit fehlenden Werten:
Wenn für Empfänger*innen die Eigenschaft nicht festgelegt ist, ist die Barcode-URL ungültig und das Bild wird nicht geladen. Du hast zwei Möglichkeiten:
Option 1: Verwende eine default Filtere, um einen aussagekräftigen Fallback-Wert festzulegen:
{% barcode person.BarcodeCode|default:'STORE-MEMBER' %}Stelle sicher, dass der Standardwert ein Wert ist, der beim Scannen sinnvoll ist. Ein generischer Platzhalter wie „Fallback“ würde einen scannbaren, aber nutzlosen Barcode erzeugen.
Option 2: Verwende eine bedingte Anweisung, um den Barcode vollständig auszublenden, wenn der Wert fehlt:
{% if person.BarcodeCode %}
{% barcode person.BarcodeCode mode=html %}
{% endif %}Behandle immer den Missing-Value-Fall, wenn der Barcode-Wert aus einer Profileigenschaft oder Ereignisvariablen stammt. Ohne eine standardmäßige oder bedingte Eigenschaft sehen Empfänger, denen diese Eigenschaft fehlt, ein fehlerhaftes Bild.
Kombiniertes Beispiel für E-Mail:
{% barcode person.LoyaltyId width=200 height=75 mode=html %}Verwenden von Barcodes mit Klaviyo-Gutscheincodes
Wenn du von Klaviyo verwaltete Gutscheincodes verwendest und sie als Barcodes darstellen möchtest, setze coupon=True. Das System wird angewiesen, dem Empfänger einen Gutscheincode zuzuweisen und diesen Code als Barcode-Wert zu verwenden.
{% barcode 'ShopifyCoupon' coupon=True %}Das funktioniert auf allen Kanälen. So kannst du z. B. einen Gutschein-Barcode über RCS senden:
{% barcode 'ShopifyCoupon' coupon=True mode=rcs %}Nur eingestellt coupon=True bei Verwendung von Klaviyo-verwalteten Gutscheincodes. Wenn du deine eigenen Gutscheincode verwaltest und als Profileigenschaft speicherst, kannst du direkt auf die Eigenschaft verweisen coupon=True:
{% barcode person.CouponCode %}Skalierung und Dimensionierung
Standardmäßig werden die Breite und Höhe des Barcodes um den Faktor 3x skaliert. Das heißt:
- A
widthvon 100 Rendern bei 300 px tatsächlicher Breite - A
heightvon 50 Rendern bei 150 px tatsächlicher Höhe
Ausnahme: Wenn mode=rcsbeträgt der Skalierungsfaktor das 1-fache. Dies ermöglicht eine präzisere Steuerung der Barcode-Abmessungen, um den Anforderungen an die RCS-Bildformatierung zu entsprechen.
Abstandswerte sind nicht skaliert. Die padded_width und padded_height Die Argumente stellen immer die tatsächlichen Pixelwerte dar. Da der innere Barcode um das 3-fache skaliert wird, müssen deine Abstandswerte größer als das 3-fache der Breite und Höhe sein. Zum Beispiel:
{% barcode 'Code' width=200 height=100 padded_width=700 padded_height=400 %}Hier wird der Barcode mit 600x300px (200×3, 100×3) innerhalb einer 700x400px gepolsterten Leinwand gerendert.
Maximale Bildgröße: Der Barcode-Dienst generiert keine Bilder, die größer als 4096x4096 Pixel sind. Dieses Limit gilt für die gerenderte Größe nach der Skalierung. Bei Nicht-RCS-Barcodes (3-fache Skalierung) bedeutet das: width Das Argument ist ungefähr 1365 (1365 × 3 = 4095 px). Für RCS-Barcodes (1x Skalierung) ist das Maximum 4096.
Breitenrichtlinien für Langwahlnummern:
- Für Nicht-RCS-Barcodes: Wenn dein Code mehr als 15 Zeichen enthält, solltest du die Standardbreite von 100 Zeichen überschreiten (die Darstellung erfolgt mit 300 px).
- Für RCS-Barcodes: Wenn dein Code länger als 30 Zeichen ist, solltest du die Standardbreite von 600 px überschreiten.
Wenn die Breite zu schmal ist, um die Daten zu codieren, kann das Barcode-Bild nicht generiert werden.
Fehlerbehebung
Vor dem Senden immer eine Vorschau anzeigen
Weil die {% barcode %} erzeugt eine URL zum Zeitpunkt des Renderns und das Bild wird erst generiert, wenn diese URL abgerufen wurde. Fehler sind möglicherweise erst sichtbar, wenn du die Nachricht in der Vorschau anzeigst oder sendest. Folge diesen Schritten, um Probleme frühzeitig zu erkennen:
- Vorschau der Nachricht. Wenn der Barcode in der Vorschau nicht geladen wird, wird er beim Senden nicht geladen.
- Scanne den Barcode. Nutze ein Barcode-Scan-Tool (z. B. imagetotext.info/barcode-scanner), um zu überprüfen, ob der Barcode den erwarteten Wert codiert.
- Sende dir eine Testnachricht, bevor du sie an deine Zielgruppe sendest.
Häufige Probleme
Das Barcode-Bild wird nicht geladen
Die häufigste Ursache ist ein leerer Barcode-Wert. Dies geschieht, wenn das Tag auf eine Profileigenschaft oder Ereignisvariable verweist, die der Empfänger nicht hat. Zum Beispiel:
{% barcode person.BarcodeCode %}Wenn der Empfänger keine BarcodeCode wird in der generierten URL der Code fehlen und das Bild nicht gerendert. Um dies zu beheben, füge eine default Filter:
{% barcode person.BarcodeCode|default:'defaultCode' %}Das Barcode-Bild kann nicht generiert werden, aber die URL sieht richtig aus
Die Barcode-Breite ist wahrscheinlich zu schmal, um alle Daten in deinem Code zu codieren. Versuche, die width Wert. Als Faustregel gilt:
- Codes, die länger als 15 Zeichen sind, benötigen eine Breite, die größer ist als die Standardbreite von 100 Zeichen (300 px gerendert).
- RCS-Codes, die länger als 30 Zeichen sind, müssen breiter sein als der Standardwert von 600 px.
Der Barcode erscheint nicht in einem Textblock (E-Mail)
Prüfe, ob die Logik zum Ein- und Ausblenden auf den Textblock angewendet wurde. Wenn eine Bedingung den Block ausblendet, wird der Barcode nicht gerendert, auch wenn das Tag korrekt ist. Öffne die Einstellungen des Blocks, um sie zu überprüfen.
Weitere Ressourcen
- Erste Schritte mit Gutscheincodes in Klaviyo – Erfahre, wie du Gutscheincodes erstellst und verwaltest, einschließlich der Verwendung des älteren
{% barcode_code %}Tags für Gutschein-Barcodes in E-Mails. - So fügst du einer Textnachricht ein dynamisches Bild hinzu – Erfahre, wie du dynamische Bilder zu MMS-Nachrichten hinzufügst, einschließlich wo du im Editor den Bereich „Dynamisches Bild“ findest.
- Referenz zu Nachrichtenpersonalisierung – Referenz für alle in Klaviyo verfügbaren Personalisierungs-Tags, einschließlich Profileigenschaften, Ereignisvariablen und Filtern.
- MMS-Bild- und GIF-Best Practices verstehen – Best Practices zur Bildgröße und Formatierung in MMS-Nachrichten.