Einleitung zu Feldfunktionen
Dieses Kapitel beschreibt, wie Sie mit Feldfunktionen arbeiten, um Mailing-Inhalte zu personalisieren und anzupassen. Optimizely Campaign verwendet die Template-Engines Dynamic rendering (ODR) und Velocity, mit denen Sie Feldfunktionen definieren können.
ODR ist eine XML-basierte Beschreibung von Feldfunktionen. Velocity ist eine Java-basierte Sprache. Kenntnisse in HTML/XML oder Java sind hilfreich für das Arbeiten mit Feldfunktionen, da diese Dokumentation nur Grundlagen zur Verwendung von ODR und Velocity enthält. Für die häufigsten Anwendungsfälle können Sie außerdem die Feldfunktionsvorlagen verwenden.
Note
Hinweis zu den verwendeten Velocity- und ODR-Klassen und -Operationen
Mit der Spezialfunktion Feldfunktionen bearbeiten stehen Ihnen erweiterte Personalisierungsmöglichkeiten für Ihre Mailings zur Verfügung. Sie dürfen nur die hier dokumentierten Klassen, Operationen und Parameter verwenden. Hier nicht dokumentierter Velocity- oder ODR-Code, fehlerhafte Parameter und Operationen können die Funktion Ihrer Vorlage und den Mailing-Versand beeinträchtigen und erhebliche Störungen verursachen.
Lesen Sie die vorliegende Dokumentation aufmerksam durch.
Testen Sie Mailings mit selbst erstellten Feldfunktionen mit der personalisierten Vorschau. Bei Fragen und Unsicherheiten wenden Sie sich an die Kundenbetreuung
Feldfunktionen in Mailings einfügen
Feldfunktionen werden im Mailing-Kontext (Paragraph, Betreff und so weiter) mittels eines Platzhalters in geschweiften Klammern { } eingefügt. Um beim Bearbeiten eines Mailings den Platzhalter für eine Feldfunktion aufzurufen, führen Sie die folgenden Schritte aus:
- Klicken Sie im Editor auf Feldfunktion einfügen .
- Klicken Sie in der Liste auf die gewünschte Feldfunktion.
- Klicken Sie anschließend auf OK.
Tip
Wenn Sie den Namen des Platzhalters kennen, setzen Sie diesen in geschweifte Klammern und fügen Sie ihn dort ein, wo er im Mailing erscheinen soll. Beim Versenden wird dieser durch den Inhalt des entsprechenden Feldes beziehungsweise durch den von der Feldfunktion generierten Inhalt ersetzt.
Anwendungsbeispiele für Feldfunktionen
Feldfunktionen ersetzen oder personalisieren Inhalte. Beim Versenden der E-Mail wird mittels der Feldfunktion ein Ausdruck (Text) erzeugt und in die E-Mail eingefügt. Es gibt Feldfunktionen, die lediglich eine einfache Ersetzung vornehmen und Algorithmen, die verschiedene Fälle unterscheiden und den Text entsprechend anpassen. Feldfunktionen können auch über Zielgruppen definiert werden und beispielsweise einen Text nur dann ausgeben, wenn der Empfänger zur Zielgruppe gehört. Die folgende Liste enthält einige typische Beispiele für Feldfunktionen:
- Datum. Beim Versenden findet eine Ersetzung durch das aktuelle Datum statt.
- Anrede. Ein Anrede-Algorithmus enthält meist eine Anredeform für Männer, Frauen und eine allgemeine Form für den Fall, dass Name oder Geschlecht nicht bekannt sind.
- Betreffzeile. Eine Feldfunktion kann beispielsweise den Namen in eine Betreffzeile setzen oder andere Personalisierungen vornehmen.
Tip
Personalisierte Links
Mithilfe von Feldfunktionen können Sie auch Links in Ihren Mailings personalisieren. Feldfunktion-Platzhalter können sowohl in der Domain oder im Pfad einer URL als auch in Form von URL-Parametern übergeben werden. Das Tracking personalisierter Links funktioniert wie bei regulären Links.
Feldfunktionen bearbeiten
Um eine Feldfunktion zu bearbeiten, wählen Verwaltung > Feldfunktionen. In der Übersicht finden Sie Feldfunktionen, die Sie bearbeiten können. Wenn Sie in einem Untermandanten arbeiten, werden in der Liste der verfügbaren Feldfunktionen auch vom Hauptmandanten vererbte Feldfunktionen angezeigt. Diese können nicht bearbeitet werden. Wählen Sie eine Funktion aus der Liste aus und klicken Sie auf Bearbeiten…, um die Funktion zu bearbeiten.
Um eine neue Feldfunktion zu erstellen, klicken Sie auf Erstellen…. Wenn Sie Feldfunktionen entfernen, vergewissern Sie sich, dass die Feldfunktion nicht in einem aktiven Mailing verwendet wird.
- Vererbbar. Wählen Sie diese Option, wenn Ihnen die Feldfunktion, die Sie bearbeiten, auch in Untermandanten zur Verfügung stehen soll. Benutzer in den Untermandanten können diese Feldfunktion benutzen, aber nicht bearbeiten.
- Typ. Wählen Sie aus, nach welchen Regeln die Feldfunktion gelesen beziehungsweise validiert wird.
Note
Ändern Sie den Typ nur, wenn Sie sich sicher sind.
- JSPX. Dieser Typ akzeptiert nur validen XML-Code.
- Velocity. Dieser Typ akzeptiert nur validen Velocity-Code.
- Beispiel. Zeigt einen Beispieltext, durch den der Platzhalter beim Versenden des Mailings ersetzt werden soll. Sie können hier ein Beispiel oder auch eine Beschreibung der Feldfunktion einfügen.
- Inhalte. Geben Sie hier die eigentliche Feldfunktion ein. Sie können für den entsprechenden Mailing-Typ, Medientyp (Marketing-Kanal) oder das entsprechende Element eine eigene Feldfunktion definieren. Das kann statischer Text sein, dynamisch erzeugter Text oder eine Mischung aus beidem. Um dynamische Inhalte zu erzeugen, müssen Befehle und Abfragen eingefügt werden, die beim Versenden auf Empfängerdaten zugreifen und diese verarbeiten können:
- Standard-Ersetzung. Dieses Feld enthält ein Fallback, das immer dann greift, wenn eine der unten stehenden spezifischen Feldfunktionen nicht definiert ist. Wenn Sie keine unterschiedlichen Feldfunktionen für jeden E-Mail-Typ, Medientyp und Elementtyp benötigen, nutzen Sie dieses Feld und lassen Sie die anderen leer.
- Text. Schreiben Sie den Code und Text der Feldfunktion in dieses Feld für die Text-Version eines Mailings.
- HTML. Schreiben Sie den Code und Text der Feldfunktion in dieses Feld für die HTML-Version eines Mailings.
- SMS. Schreiben Sie den Code und Text der Feldfunktion in dieses Feld für SMS-Mailings.
- Betreff. Schreiben Sie den Code und Text der Feldfunktion in dieses Feld für die Betreffzeile eines Mailings.
Template-Engines
Template-Engines bearbeiten die im Mailing enthaltenen Feldfunktionen unmittelbar beim Versenden, d.h. sie folgen den in den Feldfunktionen definierten Arbeitsanweisungen und lesen die dort angegebenen Daten aus. In Optimizely Campaign stehen Ihnen die Template-Engines ODR und Velocity zur Verfügung. Der folgende Abschnitt gibt Ihnen eine Einführung in beide und listet die verfügbaren Klassen und Funktionen auf.
ODR – Dynamic rendering
Wenn Ihnen XML und HTML bereits vertraut sind, können Sie Feldfunktionen am einfachsten in der ODR-Sprache beschreiben. Das nachfolgende Beispiel zeigt eine Anredelogik in ODR:
Beispiel-Code
<odr:choose><odr:when test="%{not empty user.data.firstname and not empty user.data.lastname and user.data.salutation == 'Frau'}"><odr:out value="Liebe %{user.data.firstname} %{user.data.lastname}," /> </odr:when><odr:when test="%{not empty user.data.firstname and not empty user.data.lastname and user.data.salutation == 'Herr'}"><odr:out value="Lieber %{user.data.firstname} %{user.data.lastname}," /> </odr:when><odr:otherwise><odr:out value="Sehr geehrte Damen und Herren," /></odr:otherwise>
</odr:choose>Tip
Erläuterungen
- Zeile 1. Der choose-Tag leitet eine Abfrage von Parametern ein. Der Tag selbst enthält keine weiteren Attribute.
- Zeilen 2 und 7. Der when-Tag leitet eine Abfrage ein. Als Attribut enthält er die abgefragten Parameter und Werte, im Beispiel wird abgefragt, ob der Vor- und Nachname des Empfängers vorhanden sind und die Anrede „Frau“ beziehungsweise „Herr“ lautet.
- Zeilen 4 und 9. Der out-Tag enthält den auszugebenden Text. Das kann statischer oder dynamischer Text oder eine Mischung aus beidem sein.
- Zeile 12. Der otherwise-Tag definiert den Ausgabetext für alle übrigen Fälle, die nicht auf die zuvor in den When-Tags definierten Parameter und Werte zutreffen. Der Tag enthält keine weiteren Attribute.
Umbrüche, Leerzeichen und Formatierungen in ODR
Zeilenumbrüche und Leerzeichen zwischen ODR-Tags werden beim Rendern entfernt. Leerzeichen können an den entsprechenden Stellen jedoch eingefügt werden, etwa im Fließtext zwischen den Anführungszeichen. HTML-Tags innerhalb von ODR-Ausdrücken – z. B. Zeilenumbrüche und Schriftformatierungen – müssen als Entities geschrieben werden. Verwenden Sie folgende Entities zur Umschreibung der Tags und Sonderzeichen:
- „<“ wird als „<“ geschrieben.
- „>“ wird als „>“ geschrieben.
- „"“ wird als „"“ geschrieben.
- „&“ wird als „&“ geschrieben.
Velocity
Velocity ist eine Java-basierte Template-Engine. Velocity Algorithmen können direkt in den HTML-Code von Mailings oder Webseiten eingefügt werden. In einem Algorithmus können Bedingungen und Fallbacks enthalten sein, die je nachdem, ob sie erfüllt sind oder nicht, einen anderen Text oder gar keinen Text ausgeben.
Velocity Referenzen werden durch ein Dollarzeichen $ markiert, gefolgt von der entsprechenden Klasse und Funktion. Zwei einfache Beispiele zeigen Ihnen, wie Sie mit Velocity arbeiten.
Beispiel: Vor- und Zunamen des Empfängers in die Anrede einfügen
Liebe(r) ${user.data.firstname} ${user.data.lastname}!Mit dem Ausdruck ${user.data.[feldbezeichnung]} können alle Felder der Empfängerliste angesprochen werden, wobei der in eckigen Klammern stehende Ausdruck durch den Namen des entsprechenden Empfängerlistenfeldes ersetzt werden muss.
Wenn Sie in Ihrer Empfängerliste auch Empfänger haben, deren Vorname nicht bekannt ist, etwa weil das Feld Vorname bei der Anmeldung kein Pflichtfeld ist, dann ist der oben beschriebene Weg nicht ausreichend. Sie werden keinen Ihrer Empfänger mit „Liebe(r) Schmidt!“ anreden wollen. Mit Velocity können Sie für diesen Fall eine Alternative formulieren mit der jeweils richtigen Form für Männer und Frauen.
Beispiel: Vollständige Anrede für Männer und Frauen sowie Fallback:
Um in der Anrede alle Fälle zu berücksichtigen, wird ein Wenn-Dann-Algorithmus formuliert. Ein solcher Algorithmus wird mit einem Rautezeichen # gefolgt von dem Befehl if eingeleitet. Es folgen die Definition der verschiedenen Fälle und einer Alternative (else), falls keiner der Fälle zutrifft. Der Algorithmus wird mit #end abgeschlossen:
#if("$!{user.data.firstname}" != "" && "$!{user.data.lastname}" != "" &&"$!{user.data.salutation}" != "") Liebe #if($!user.data.salutation.startsWith("Herr"))r#end $user.data.firstname $user.data.lastname, #else Sehr$!{null}geehrte Damen und Herren#end$!{null}Tip
Erläuterungen
- Zeile 1. Um eine vollständige Anrede zu formulieren, müssen ein Vorname, ein Nachname und eine Anrede vorhanden sein. Die Anrede (Herr/Frau) wird nur benötigt, um im nächsten Schritt die richtige Form auszuwählen, sie wird nicht selbst ausgegeben. Diese Zeile prüft, ob alle benötigten Angaben für einen Empfänger vorhanden sind. Wird eine Variable benutzt, die nicht definiert ist, dann liest Velocity die Bezeichnung dieser Variablen (nicht den Wert) als String, was bei Vergleichen immer zu unerwarteten Ergebnissen führt. Um dies zu verhindern, wird statt des Operators $ der spezielle Operator $! verwendet. Ist kein Wert gesetzt, wird die Ausgabe unterdrückt. Der gesamte Ausdruck wird zusätzlich in Anführungszeichen gesetzt. Ist das Feld am abgefragten Empfänger nicht definiert, gibt der Operator zunächst ein NULL zurück. Durch die Anführungszeichen, wird ein Leer-String gebildet, auf den bei der Formulierung von Bedingungen vom Typ = "" (ist leer) oder !="" (ist nicht leer) getestet werden kann.
- Zeile 2. Ist die Anrede „Herr“, wird die korrekte Form „Lieber...“ verwendet.
- Zeile 3. Hier werden die Werte für Vor- und Nachnamen per Platzhalter eingefügt.
- Zeile 4. Mit dem Platzhalter #else wird ein Fallback eingegfügt für den Fall, dass die erste Bedingung nicht zutrifft, also Vorname, Nachname und Anrede nicht vorhanden sind. Die Anrede wird dann allgemein formuliert. Wenn Sie Velocity-Befehle direkt in den Text eines Mailings einfügen, werden Leerzeichen nach Velocity-Befehlen ignoriert. Das führt dazu, dass Text, der direkt auf einen Befehl folgt, mit diesem zusammen interpretiert wird, was natürlich eine Syntax-Fehlermeldung verursacht. Um dies zu vermeiden, muss an solchen Stellen ein Null-Objekt eingefügt werden: $!{null}, das keinerlei Ausgabe erzeugt, aber den vorangegangenen Velocity-Befehl korrekt schließt. Beenden Sie Velocity-Code immer mit dem Tag #end. Danach sollte immer ein Umbruch folgen.
Velocity-Klassen und -Funktionen
Optimizely Campaign stellt Ihnen ein Reihe von Klassen und Funktionen zur Verfügung, mit denen Sie Feldfunktionen definieren können:
$user.data
Mit dieser Funktion können Sie alle Felder einer Empfängerliste ansprechen. Die Funktion kann verwendet werden, um den entsprechenden Wert des Feldes in ein Mailing einzufügen (Platzhalter) oder um den Inhalt des Feldes mit einem gesetzten Wert zu vergleichen (Wenn-Dann-Funktion).
Funktion | Velocity-Code |
|---|---|
Wert ist gleich einer Zeichenfolge | ``` |
$user.data.[feldbezeichnung] == "string" | |
| Wert ist gleich einem Zahlenwert | ```
$user.data.[feldbezeichnung] == X
``` |
| Wert ist ungleich einer Zeichenfolge | ```
$user.data.[feldbezeichnung] != "string"
``` |
| Wert beginnt mit einer Zeichenfolge | ```
$user.data.[feldbezeichnung].startsWith ("string")
``` |
| Wert ist ungleich einem Zahlenwert | ```
$user.data.[feldbezeichnung] != X
``` |
| Wert ist kleiner oder gleich einem Zahlenwert | ```
$user.data.[feldbezeichnung] <= X
``` |
| Wert ist größer oder gleich einem Zahlenwert | ```
$user.data.[feldbezeichnung] >= X
``` |
| Wert ist größer als ein Zahlenwert | ```
$user.data.[feldbezeichnung] > X
``` |
| Sonderfunktion: Ist Online-Version | ```
$user.data.bmIsOnlineVersion
``` |
Mit der Funktion **Ist Online-Version** können Sie beispielsweise abfragen, ob die Online-Version eines Newsletters angezeigt wird. Der Rückgabewert ist in diesem Fall `true`. Damit kann der Link zur Online-Version („Klicken Sie auf folgenden Link, wenn die Email nicht korrekt dargestellt wird.“ ausgeblendet werden, wenn diese angezeigt wird. Der entsprechende Code lautet wie folgt:
```velocity
#if($user.data.bmIsOnlineVersion)Bitte <a href="{Online-Version-Link}" target="_blank">hier</a> klicken, um eine Online-Version dieses Newsletters zu lesen.$bmFormat
Diese Klasse formatiert den eingeschlossenen Ausdruck. Sie können nur Datumsfelder oder Zahlenwerte formatieren. Optional können Sie eine Formatvorlage (pattern) und die Anzahl der Nachkommastellen (precision) angeben. Der folgende Code zeigt ein Beispiel mit $bmFormat:
Sie sind seit dem $bmFormat.formatDate($user.data.created) bei uns registriert.Formatierung | Velocity-Code |
|---|---|
Zahlen als Prozentwerte formatieren | ``` |
$bmFormat.formatPercentage | |
| Zahlen als Währungsbetrag formatieren. Wird der Parameter **includeCurrencySymbol** auf `true` gesetzt, wird zusätzlich das entsprechende Währungszeichen ausgegeben. | ```
$bmFormat.formatCurrency
``` |
| Datum formatieren | ```
$bmFormat.formatDate
``` |
| Datum und Uhrzeit formatieren | ```
$bmFormat.formatDateTime
``` |
| Uhrzeit formatieren | ```
$bmFormat.formatTime
``` |
##### Attribute zur Formatierung von Zahlenwerten
| Attribute | Beschreibung |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pattern | * **Zahlenwerte**: Verwenden Sie das Schema **###,###,###.##** oder **000000.000**.
# steht für eine Ziffer, 0 für führende oder folgende Nullen.
Der Punkt wird als Dezimaltrennzeichen verwendet und darf im Pattern nur einmal vorkommen. Das Komma wird als Gruppierungszeichen verwendet und darf beliebig oft vorkommen – jedoch niemals nach dem Punkt.
:::hint{style="info"}
**Note**
In der späteren Ausgabe wird der Zahlenwert deutsch formatiert. Das Gruppierungszeichen (im Pattern das Komma) wird als Punkt und das Dezimaltrennzeichen (im Pattern der Punkt) als Komma dargestellt, zum Beispiel 1.000,00. Die englische Formatierung (z. B. 1,000.00) wird nicht unterstützt.
:::
Beispiele für den Wert 1000:
Schema Ausgabe###,###,###.## 1.000
000,000,000.00 000.001.000,00
##,##.0### 10.00,0
###.###.###.## ✘ ungültig, da mehrere Punkte vorkommen
###.###,## ✘ ungültig, da das Komma nach dem Punkt kommt
* **Datumsangaben**. Verwenden Sie das Schema `dd.MM.yyyy`.
* **Uhrzeitangaben**. Verwenden Sie das Schema `hh:mm:ss`.
Weitere Informationen zu den Schemata für Zahlenwerte und Datumsangaben erhalten Sie in der [Java-Dokumentation](https://docs.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html) von Oracle. |
| precision | Ganzzahliger Wert, der die Anzahl der Nachkommastellen angibt, auf die ein Ausgabewert gerundet werden soll. |
#### []()$bmMimeType
Mit dieser Klasse können Sie den Mime-Type abfragen, der gerade gerendert wird.
| MIME-Type | Velocity-Code |
| ------------ | ----------------------------------- |
| Text-E-Mails | ```
$bmMimeType == "text/plain"
``` |
| HTML-E-Mails | ```
$bmMimeType == "text/html"
``` |
#### []()$filter
Diese Klasse ermöglicht es, Zielgruppen aufzurufen. Der übergebene String muss einer Zielgruppen-ID Ihres Optimizely Campaign Mandanten entsprechen. Um die IDs für Ihre Zielgruppen zu erhalten, wenden Sie sich an die [Kundenbetreuung](https://support.optimizely.com/hc/de/articles/4413200618253) Verwenden Sie keine IDs, bei denen Sie sich nicht sicher sind, dass sie den Zielgruppen in Ihrem Mandanten entsprechen, andernfalls könnte das die Funktion Ihrer Vorlage und Ihres Mailing-Versandes beeinträchtigen. Der Velocity-Code dieser Funktion lautet:
```velocity
$filter.filterByRevisionedFilterFeldfunktionsvorlagen
In den folgenden Kapiteln finden Sie Velocity- und ODR-Vorlagen, mit denen Sie Ihre eigenen Feldfunktionen erstellen können: