Kontext

Mit Kontext-Schritten können Sie eine oder mehrere Variablen für Nutzer:innen erstellen und aktualisieren, während diese sich durch einen Canvas bewegen. Wenn Sie beispielsweise einen Canvas haben, der saisonale Rabatte verwaltet, können Sie eine Kontextvariable verwenden, um bei jedem Eintritt in den Canvas einen anderen Rabattcode zu speichern.

Wichtig

Die Verfügbarkeit von Canvas-Kontext variiert je nach Workspace. Wenn Kontext nicht im Canvas-Schrittmenü angezeigt wird und das Personalisierungsmenü Canvas-Entry-Eigenschaften statt Kontextvariablen anzeigt, verwenden Sie canvas_entry_properties für Entry-Daten. Wenden Sie sich an Ihren Account Manager, wenn Sie Zugang zu Canvas-Kontext benötigen.

Funktionsweise

Mit Context-Schritten können Sie temporäre Daten erstellen und verwenden, während Nutzer:innen ein bestimmtes Canvas durchlaufen. Diese Daten existieren nur innerhalb dieser Canvas-Journey und bleiben weder über verschiedene Canvases hinweg noch außerhalb der Sitzung erhalten.

Kontextvariablen existieren nur für die jeweilige Canvas-Journey. Sie ändern das Nutzerprofil nicht dauerhaft und erscheinen nicht in anderen Canvases. Damit eignen sie sich ideal für temporäre Informationen, die nur für eine bestimmte Campaign oder einen bestimmten Workflow relevant sind.

Tipp

Eine vollständige Referenz zu Kontextvariablen, einschließlich Datentypen, Verwendung und Best Practices, finden Sie in der Referenz zu Kontextvariablen.

Innerhalb eines Context-Schritts können Sie bis zu 10 Kontextvariablen definieren oder aktualisieren. Mit diesen Variablen können Sie Verzögerungen personalisieren, Nutzer:innen dynamisch segmentieren und Ihr Messaging im gesamten Canvas anreichern. Sie könnten beispielsweise eine Kontextvariable für die geplante Flugzeit von Nutzer:innen erstellen und damit personalisierte Verzögerungen festlegen und Erinnerungen senden.

Sie können Kontextvariablen auf zwei Arten festlegen:

• Beim Canvas-Entry: Eigenschaften aus dem angepassten Event oder API-Trigger werden automatisch als Kontextvariablen übernommen.
• In einem Context-Schritt: Sie definieren oder aktualisieren Kontextvariablen manuell, indem Sie einen Context-Schritt hinzufügen.

Jede Kontextvariable benötigt einen Namen, einen Datentyp und einen Wert (festgelegt über Liquid oder das Tool „Personalisierung hinzufügen“). Nach der Definition können Sie Kontextvariablen im gesamten Canvas mit Liquid referenzieren, zum Beispiel {{context.${flight_time}}}. Im Feld Name der Kontextvariable können Sie den Namen der Kontextvariable auch eingeben oder ihn im Schritt-Editor aus dem Dropdown-Menü auswählen. Weitere Informationen finden Sie in der Referenz zu Kontextvariablen.

Bei jedem Canvas-Entry werden die Kontextvariablen anhand der neuesten Entry-Daten und der Canvas-Konfiguration neu definiert. So können Nutzer:innen mehrere aktive Journeys mit jeweils eigenem Kontext haben. Hat ein:e Kund:in beispielsweise zwei bevorstehende Flüge, laufen gleichzeitig zwei separate Journey-Zustände—jeweils mit eigenen flugspezifischen Kontextvariablen wie Abflugzeit und Zielort. So können Sie personalisierte Erinnerungen zum Flug um 14 Uhr nach New York senden und gleichzeitig andere Updates zum Flug morgen um 8 Uhr nach Los Angeles verschicken, damit jede Nachricht für die jeweilige Buchung relevant bleibt.

Verarbeitung und Batching von Nutzer:innen

Context-Schritte verarbeiten Nutzer:innen in Batches, um die Performance zu optimieren. Wenn Nutzer:innen einen Context-Schritt erreichen, verarbeitet Braze sie standardmäßig in Batches von 1.000 Nutzer:innen. Diese Batches werden parallel verarbeitet, innerhalb jedes Batches werden die Nutzer:innen jedoch nacheinander verarbeitet.

Das bedeutet:

Beispiel: Wenn 3.500 Nutzer:innen einen Context-Schritt mit Connected-Content erreichen, der 650 ms pro Nutzer:in benötigt:

• Braze erstellt 4 Batches von Nutzer:innen (in diesem Beispiel 1.000, 1.000, 1.000 und 500 Nutzer:innen).
• Jeder Batch verarbeitet die Nutzer:innen nacheinander, sodass ein Batch mit 1.000 Nutzer:innen etwa 10,8 Minuten dauert (650 Sekunden; 1.000 × 650 ms).
• Die Batches werden zu unterschiedlichen Zeitpunkten abgeschlossen, sodass Nutzer:innen nach und nach zum nächsten Schritt gelangen, sobald ihr Batch fertig ist.
• Je nach Batch-Größe und Antwortzeiten von Connected-Content erreichen die ersten Nutzer:innen den nächsten Schritt möglicherweise mehrere Minuten vor den letzten.

Ohne Connected-Content werden Context-Schritte deutlich schneller verarbeitet, da nicht auf externe API-Aufrufe gewartet werden muss.

Überlegungen

• Sie können bis zu 10 Kontextvariablen pro Kontext-Schritt definieren.
• Jede Variable benötigt einen eindeutigen Namen (nur Buchstaben, Zahlen und Unterstriche, bis zu 100 Zeichen).
• Die Gesamtgröße aller Variablen in einem Schritt darf 50 KB nicht überschreiten.
• Variablen, die über API-Trigger übergeben werden, teilen sich denselben Namensraum wie Variablen, die in Kontext-Schritten erstellt werden. Wenn Sie eine Variable in einem Kontext-Schritt neu definieren, wird der API-Wert überschrieben.

Weitere Details und fortgeschrittene Anwendungsfälle finden Sie in der Referenz zu Kontextvariablen.

Einen Kontext-Schritt erstellen

Tipp

Wenn Context Variable als Filter in Ihrem Workspace verfügbar ist, benötigen Sie keinen Kontext-Schritt, um in Zielgruppenpfad- oder Decision-Split-Schritten auf Eigenschaften des auslösenden Events zu verweisen. Sie können die Eigenschaften direkt in den Filtergruppen referenzieren. Achten Sie darauf, den korrekten Datentyp auszuwählen.

Schritt 1: Einen Schritt hinzufügen

Fügen Sie Ihrem Canvas einen Schritt hinzu. Ziehen Sie dann die Komponente aus der Seitenleiste per Drag-and-Drop hinein, oder wählen Sie den Plus-Button und dann Kontext aus.

Schritt 2: Die Variablen definieren

Hinweis

Sie können bis zu 10 Kontextvariablen pro Kontext-Schritt definieren.

So definieren Sie eine Kontextvariable:

1. Geben Sie Ihrer Kontextvariable einen Namen.
2. Wählen Sie einen Datentyp aus.
3. Schreiben Sie einen Liquid-Ausdruck manuell, oder verwenden Sie Personalisierung hinzufügen, um ein Liquid-Snippet aus bereits vorhandenen Attributen zu erstellen.
4. Wählen Sie Vorschau, um den Wert Ihrer Kontextvariable zu überprüfen.
5. (Optional) Um weitere Variablen hinzuzufügen, wählen Sie Kontextvariable hinzufügen und wiederholen Sie die Schritte 1–4.
6. Wenn Sie fertig sind, wählen Sie Fertig.

Jetzt können Sie Ihre Kontextvariable überall dort verwenden, wo Sie Liquid nutzen, etwa in Nachrichten- und Nutzer-Update-Schritten, indem Sie Personalisierung hinzufügen auswählen. Im Feld Name der Kontextvariable können Sie den Namen der Kontextvariable auch eingeben oder ihn im Schritt-Editor aus dem Dropdown-Menü auswählen. Eine ausführliche Anleitung finden Sie in der Referenz zu Kontextvariablen.

Wichtig

Verwenden Sie beim Referenzieren von Kontextvariablen immer das Format {{context.${variable_name}}}.

Filter für Kontextvariablen

Sie können Filter mit Kontextvariablen in Zielgruppenpfad- und Decision-Split-Schritten erstellen.

Um Nutzer:innen anhand der Antwort eines Agent-Schritts weiterzuleiten, fügen Sie den Agent-Schritt vor Ihrem Zielgruppenpfad- oder Decision-Split-Schritt ein. Der Agent-Schritt speichert seine Ausgabe im Canvas-Kontext, den Sie in diesen Verzweigungsschritten mit Filtern für Kontextvariablen auswerten können.

Wenn der Agent ein Objekt zurückgibt und Sie nach einer verschachtelten Eigenschaft filtern möchten, geben Sie im Feld Name der Kontextvariable den Pfad in Punktnotation ein statt nur den Variablennamen der obersten Ebene (zum Beispiel intent_agent.persona, wenn persona unter intent_agent verschachtelt ist).

Hinweis

Die Liste Name der Kontextvariable enthält Variablen aus Kontext-Schritten und Agent-Schritten. Für eine Canvas-Entry-Eigenschaft geben Sie deren Namen ein und wählen „ENTRY_PROPERTY_NAME“ verwenden aus. Ersetzen Sie ENTRY_PROPERTY_NAME durch den Namen der eingegebenen Entry-Eigenschaft. Für eine verschachtelte Eigenschaft verwenden Sie die Punktnotation, z. B. order.total.

Informationen zur Einrichtung von Filtern, zur Vergleichslogik und zu fortgeschrittenen Beispielen finden Sie in der Referenz zu Kontextvariablen.

Wichtig

Auswahl zwischen den Filtertypen „Tag des Jahres“ und „Zeit“: Wenn Sie Kontextvariablen filtern, die Datumsangaben enthalten, wählen Sie den korrekten Vergleichstyp, je nachdem, ob sich das Datum jedes Jahr wiederholt. Verwenden Sie „Tag des Jahres“ nur, wenn der Wert, den die Kontextvariable erzeugt, kein Jahr enthält.

• Verwenden Sie „Tag des Jahres“, wenn sich das Datum jedes Jahr wiederholt (z. B. Geburtstage, Jahrestage oder Feiertage wie Weihnachten). Dieser Vergleichstyp berechnet auf Grundlage des Tages im Jahr (1–365/366) und ignoriert die Jahreskomponente.
• Verwenden Sie „Zeit“, wenn es sich um ein absolutes Datum handelt, das sich nicht wiederholt (z. B. Vertragsende, Terminvereinbarungen oder Abo-Verlängerungsdaten). Dieser Vergleichstyp berechnet auf Grundlage des vollständigen Zeitstempels einschließlich des Jahres.

Die Verwendung von „Tag des Jahres“ für absolute Datumsangaben kann zu falschen oder unerwarteten Ergebnissen führen, da die Berechnung die Jahreskomponente nicht berücksichtigt. Wenn Sie beispielsweise ein zukünftiges Vertragsenddatum im April vergleichen, um festzustellen, ob es innerhalb von 63 Tagen liegt, kann „Tag des Jahres“ zu falschen Übereinstimmungen führen, da nur die Tageszahlen (119 gegenüber 359) verglichen werden, ohne zu berücksichtigen, dass der April tatsächlich 188 Tage entfernt ist.

Vorschau auf Nutzerpfade

Wir empfehlen, Ihre Nutzerpfade zu testen und in der Vorschau anzuzeigen. So stellen Sie sicher, dass Ihre Nachrichten an die richtige Zielgruppe gesendet und Kontextvariablen mit den erwarteten Ergebnissen ausgewertet werden.

Hinweis

Wenn Sie die Vorschau Ihres Canvas im Bereich Vorschau und Testversand des Editors anzeigen, wird der Zeitstempel in der Vorschau der Testnachricht nicht auf UTC standardisiert, da dieses Panel Vorschauen als Strings erzeugt. Wenn ein Canvas also so eingerichtet ist, dass es ein time-Objekt akzeptiert, bildet die Nachrichtenvorschau nicht genau ab, was passiert, wenn das Canvas live ist. Um Ihr Canvas möglichst genau zu testen, empfehlen wir stattdessen eine Vorschau der Nutzerpfade.

Achten Sie auf häufige Szenarien, die ungültige Kontextvariablen erzeugen. In der Vorschau Ihres Nutzerpfads sehen Sie die Ergebnisse personalisierter Verzögerungsschritte, die Kontextvariablen verwenden. Außerdem sehen Sie alle Vergleiche in Zielgruppen- oder Entscheidungsschritten, die Nutzer:innen mit Kontextvariablen abgleichen.

Wenn die Kontextvariable gültig ist, können Sie in Ihrem gesamten Canvas auf die Variable verweisen. Wurde die Kontextvariable jedoch nicht korrekt erstellt, funktionieren auch spätere Schritte in Ihrem Canvas nicht korrekt. Wenn Sie beispielsweise einen Kontext-Schritt erstellen, um Nutzer:innen einen Termin zuzuweisen, und den Wert der Terminzeit auf ein vergangenes Datum setzen, wird die Erinnerungs-E-Mail in Ihrem Nachrichtenschritt nicht gesendet.

Connected-Content-Strings in JSON konvertieren

Wenn Sie in einem Kontext-Schritt einen Connected-Content-Aufruf durchführen, wird das vom Aufruf zurückgegebene JSON aus Gründen der Konsistenz und Fehlervermeidung als String-Datentyp ausgewertet. Wenn Sie diesen String in JSON umwandeln möchten, verwenden Sie dafür as_json_string. Zum Beispiel:

1
2

{% connected_content http://example.com :save product %}
{{ product | as_json_string }}

Fehlerbehebung

Ungültige Kontextvariablen

Eine Kontextvariable gilt als ungültig, wenn:

• Ein Aufruf eines eingebetteten Connected-Content fehlschlägt.
• Der Liquid-Ausdruck zur Laufzeit einen Wert zurückgibt, der nicht dem Datentyp entspricht oder leer (null) ist.
• Der Liquid-Ausdruck {% abort_message() %} aufruft.

Wenn der Datentyp der Kontextvariable beispielsweise Zahl ist, der Liquid-Ausdruck aber einen String zurückgibt, ist die Variable ungültig.

In diesen Fällen gilt:

• Die Nutzer:in wird zum nächsten Schritt weitergeleitet.
• Die Analytics des Canvas-Schritts zählen dies als Not Updated.

Überwachen Sie bei der Fehlerbehebung die Metrik Not Updated, um zu prüfen, ob Ihre Kontextvariable korrekt aktualisiert wird. Ist die Kontextvariable ungültig, können Ihre Nutzer:innen in Ihrem Canvas über den Kontext-Schritt hinaus fortfahren, qualifizieren sich aber möglicherweise nicht für spätere Schritte.

Unter Datentypen finden Sie Beispiel-Setups für jeden Datentyp.

Eine Kontextvariable kann auch absichtlich mit abort_message übersprungen werden. Siehe abort_message in einer Kontextvariable verwenden.

abort_message in einer Kontextvariable verwenden

Sie können den Liquid-Tag abort_message im Wert einer Kontextvariable verwenden, um diese Variable für bestimmte Nutzer:innen zu überspringen. In einem Kontext-Schritt wirkt sich abort_message nur auf die Variable aus, in der es steht. Der Schritt wird dadurch nicht angehalten, und die Nutzer:in verlässt das Canvas nicht.

Wenn das Liquid einer Kontextvariable für eine Nutzer:in abort_message aufruft:

• Die Variable wird für diese Nutzer:in nicht gesetzt. Hat ein früherer Kontext-Schritt diese Variable bereits gesetzt, behält die Nutzer:in diesen früheren Wert.
• Die anderen Variablen im Schritt werden weiterhin ausgewertet und gesetzt.
• Spätere Variablen im selben Schritt, die auf diese Variable verweisen, erhalten von dieser Variable keinen neuen Wert.
• Die Nutzer:in wird zum nächsten Schritt weitergeleitet.
• Die Analytics des Canvas-Schritts zählen die Variable als Not Updated.

Diese Variable wird beispielsweise für Nutzer:innen in Frankreich auf true gesetzt und für alle anderen übersprungen:

1
2
3
4
5

{% if ${country} == "France" %}
  true
{% else %}
  {% abort_message("Not in France") %}
{% endif %}

Wenn Sie eine Vorschau der Nutzerpfade anzeigen, erscheint eine übersprungene Variable als „variable_name was not updated because the Liquid logic triggered an abort“.

Wenn spätere Schritte von dieser Variable abhängen, planen Sie für Nutzer:innen, bei denen sie nicht gesetzt ist. Sie können diese Nutzer:innen beispielsweise mit einem Zielgruppenpfad-Schritt weiterleiten.

Hinweis

Abbrüche in Kontext-Schritten werden nicht im Message Activity Log erfasst, und der Grund, den Sie an abort_message übergeben, wird nicht angezeigt.

Verzögerungen beim Senden mit Connected-Content

Alle Nutzer:innen in einem Batch werden verarbeitet, bevor Nutzer:innen weitergeleitet werden. Nach Abschluss der Batch-Verarbeitung gehen erfolgreiche Nutzer:innen zum nächsten Schritt über, während fehlgeschlagene Nutzer:innen separat erneut versucht werden – erfolgreiche Nutzer:innen warten nicht darauf, dass Wiederholungsversuche erfolgreich sind, bevor sie weitergeleitet werden.

Wiederholungsverhalten

Connected-Content-Aufrufe in einem Canvas werden nur dann wiederholt, wenn der Aufruf :retry enthält.

• Kontext- und Nutzer-Update-Schritte: Braze wiederholt den Connected-Content-Aufruf auf Schrittebene (bis zu fünfmal). Schlagen alle Wiederholungen fehl, verlässt die Nutzer:in das Canvas.
• Nachrichten-Schritte: Connected-Content mit :retry nutzt weiterhin die Messaging-Pipeline. Empfänger:innen werden in der Sende-Warteschlange verzögert, während Braze den Aufruf bis zu fünfmal wiederholt. Schlagen alle Wiederholungen fehl, wird die Nachricht abgebrochen und die Nutzer:in zum nächsten Schritt weitergeleitet.

Bei Kontext- und Nutzer-Update-Schritten können bestimmte wiederholbare Schrittfehler – etwa ein fehlgeschlagener Abruf eines Aktionscodes oder ein unerwarteter Schrittfehler – zusätzliche Wiederholungen auf Schrittebene mit exponentiellem Backoff auslösen (etwa 13-mal), bevor Braze die Nutzer:in aus dem Canvas entfernt.

Weitere Informationen zum Tag :retry finden Sie unter Connected-Content-Wiederholungen.

Wie lange die Verarbeitung aller Nutzer:innen durch einen Kontext-Schritt dauert, hängt ab von:

• Der Anzahl der Nutzer:innen, die in den Schritt eintreten
• Ob Connected-Content verwendet wird (und dessen Antwortzeit)
• Der Batch-Größe (standardmäßig 1.000 Nutzer:innen pro Batch)

Wenn Ihr Connected-Content-Endpunkt Rate-Limits hat, beachten Sie, dass Kontext-Schritte Nutzer:innen innerhalb jedes Batches sequenziell verarbeiten, was die Einhaltung von Rate-Limits auf natürliche Weise unterstützt. Mehrere Batches werden jedoch parallel verarbeitet. Stellen Sie daher sicher, dass Ihr Endpunkt gleichzeitige Anfragen aus mehreren Batches verarbeiten kann.

Zeitzonenkonsistenz

In Workspaces mit Canvas Context liegen alle standardmäßigen Zeitstempel-Event-Eigenschaften in aktionsbasierten Canvases in UTC vor. Dieses Verhalten gilt unabhängig davon, ob das Canvas einen Context-Schritt verwendet oder nicht.

Wichtig

Wir empfehlen dringend, in allen Fällen Liquid-Filter für time_zone zu verwenden, damit Zeitstempel in der gewünschten Zeitzone dargestellt werden. Ein Beispiel finden Sie in dieser häufig gestellten Frage.

Häufig gestellte Fragen

Wie wirkt sich Canvas Context auf Zeitstempel aus?

Für Workspaces mit Canvas Context gilt:

• Alle Zeitstempel mit einem Datetime-Typ aus Eigenschaften von Trigger-Events in aktionsbasierten Canvases sind in UTC angegeben.
• Diese Änderung betrifft alle aktionsbasierten Canvases, unabhängig davon, ob das jeweilige Canvas einen Kontext-Schritt verwendet oder nicht.

Was ist der Grund für diese Änderung?

Diese Änderung ist Teil einer umfassenderen Initiative, die das Bearbeiten von Canvas-Schritten und Nachrichten vorhersehbarer und konsistenter machen soll.

Sind API-getriggerte oder geplante Canvases von dieser Änderung betroffen?

Nein.

Wirkt sich diese Änderung auf Canvas-Entry-Eigenschaften aus?

Ja, dies betrifft canvas_entry_properties, wenn die canvas_entry_property in einem aktionsbasierten Canvas verwendet wird und der Eigenschaftstyp time ist. Wir empfehlen in jedem Fall, Liquid-Filter vom Typ time_zone zu verwenden, damit Zeitstempel in der gewünschten Zeitzone dargestellt werden.

Hier sehen Sie ein Beispiel dafür:

Wie könnte sich das neue Zeitstempelverhalten in der Praxis auf meine Nachrichten auswirken?

Angenommen, wir haben ein aktionsbasiertes Canvas mit folgendem Inhalt in einem Nachrichten-Schritt:

1

Your appointment is scheduled for {{canvas_entry_properties.${appointment_time} | date: "%Y-%m-%d %l:%M %p"}}, we'll see you then!

Daraus ergibt sich folgende Nachricht:

1

Your appointment is scheduled for 2025-08-05 4:15 PM, we’ll see you then!

Da mit Liquid keine Zeitzone angegeben ist, ist der Zeitstempel hier in UTC.

Um eine Zeitzone eindeutig anzugeben, können wir Liquid-Filter vom Typ time_zone wie folgt verwenden:

1

Your appointment is scheduled for {{canvas_entry_properties.${appointment_time} | time_zone: "America/Los_Angeles" | date: "%Y-%m-%d %l:%M %p"}}, we'll see you then!

Daraus ergibt sich folgende Nachricht:

1

Your appointment is scheduled for 2025-08-05 8:15 AM, we'll see you then!

Da die Zeitzone America/Los Angeles mit Liquid angegeben ist, ist der Zeitstempel hier in PST.

Die bevorzugte Zeitzone kann auch im Payload der Event-Eigenschaften gesendet und in der Liquid-Logik verwendet werden:

1
2
3
4

{
  "appointment_time": "2025-08-05T08:15:30:250-0800"
  "user_timezone": "America/Los_Angeles"
}

Worin unterscheiden sich Kontextvariablen von Canvas-Entry-Eigenschaften?

Canvas-Entry-Eigenschaften sind als Canvas-Kontextvariablen enthalten. Das bedeutet, dass Sie Canvas-Entry-Eigenschaften über die Braze API senden und in anderen Schritten referenzieren können – ähnlich wie bei der Verwendung einer Kontextvariablen mit dem Liquid-Snippet.

Können Variablen in einem einzelnen Kontext-Schritt aufeinander verweisen?

Ja. Alle Variablen in einem Kontext-Schritt werden nacheinander ausgewertet. Sie könnten also beispielsweise folgende Kontextvariablen einrichten:

Dies gilt auch über mehrere Kontext-Schritte hinweg. Stellen Sie sich beispielsweise folgende Abfolge vor:

1. Ein erster Kontext-Schritt erstellt eine Variable namens JobInfo mit dem Wert job_title.
2. Ein Nachrichten-Schritt referenziert {{context.${JobInfo}}} und zeigt den Nutzer:innen job_title an.
3. Später aktualisiert ein Kontext-Schritt die Kontextvariable und ändert den Wert von JobInfo in job_description.
4. Alle nachfolgenden Schritte, die auf JobInfo verweisen, verwenden nun den aktualisierten Wert job_description.

Kontextvariablen verwenden im gesamten Canvas jeweils ihren aktuellsten Wert. Jedes Update wirkt sich auf alle nachfolgenden Schritte aus, die auf diese Variable verweisen.