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

Kontextschritte ermöglichen es Ihnen, temporäre Daten während der Journey von Nutzer:innen durch ein bestimmtes Canvas zu erstellen und zu verwenden. Diese Daten existieren nur innerhalb dieser Canvas-Journey und bleiben weder in anderen Canvases noch außerhalb der Sitzung erhalten.

Kontextvariablen existieren nur für diese spezifische Canvas-Journey. Sie ändern das Profil der Nutzer:innen nicht dauerhaft und erscheinen nicht in anderen Canvases. Das macht sie 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 Kontextschritts können Sie bis zu 10 Kontextvariablen definieren oder aktualisieren. Diese Variablen können verwendet werden, um Verzögerungen zu personalisieren, Nutzer:innen dynamisch zu segmentieren und das Messaging im gesamten Canvas anzureichern. Sie könnten beispielsweise eine Kontextvariable für die geplante Flugzeit von Nutzer:innen erstellen und diese dann verwenden, um personalisierte Verzögerungen festzulegen und Erinnerungen zu senden.

Sie können Kontextvariablen auf zwei Arten festlegen:

• Beim Canvas-Eintritt: Eigenschaften des angepassten Events oder des API-Triggers werden automatisch als Kontextvariablen übernommen.
• In einem Kontextschritt: Definieren oder aktualisieren Sie Kontextvariablen manuell, indem Sie einen Kontextschritt hinzufügen.

Jede Kontextvariable erfordert einen Namen, einen Datentyp und einen Wert (festgelegt mit Liquid oder dem Personalisierungstool). Nach der Definition können Sie Kontextvariablen im gesamten Canvas mit Liquid referenzieren, zum Beispiel {{context.${flight_time}}}. Im Feld Context variable name können Sie auch den Namen der Kontextvariable eingeben oder ihn aus dem Dropdown im Schritt-Editor auswählen. Details finden Sie in der Referenz zu Kontextvariablen.

Jeder Canvas-Eintritt definiert die Kontextvariablen auf Basis der neuesten Entry-Daten und der Canvas-Konfiguration neu, sodass Nutzer:innen mehrere aktive Journeys mit eigenem Kontext haben können. Wenn beispielsweise Kund:innen zwei bevorstehende Flüge haben, laufen zwei separate Journey-Zustände gleichzeitig – jeder mit eigenen flugspezifischen Kontextvariablen wie Abflugzeit und Zielort. So können Sie personalisierte Erinnerungen über den 14-Uhr-Flug nach New York senden und gleichzeitig andere Updates über den 8-Uhr-Flug nach Los Angeles am nächsten Tag verschicken, sodass jede Nachricht für die jeweilige Buchung relevant bleibt.

Nutzer:innen-Verarbeitung und Batching

Kontextschritte verarbeiten Nutzer:innen in Batches, um die Performance zu optimieren. Wenn Nutzer:innen einen Kontextschritt erreichen, verarbeitet Braze sie standardmäßig in Batches von 1.000 Nutzer:innen. Diese Batches werden parallel verarbeitet, aber innerhalb jedes Batches werden die Nutzer:innen sequenziell verarbeitet.

Das bedeutet:

Beispiel: Wenn 3.500 Nutzer:innen einen Kontextschritt 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 Nutzer:innen sequenziell, sodass ein Batch von 1.000 Nutzer:innen ungefähr 10,8 Minuten dauert (650 Sekunden; 1.000 × 650 ms).
• Batches werden zu unterschiedlichen Zeitpunkten fertig, sodass Nutzer:innen nach und nach in den nächsten Schritt übergehen, sobald ihr Batch abgeschlossen ist.
• Die ersten Nutzer:innen können den nächsten Schritt mehrere Minuten vor den letzten Nutzer:innen erreichen, abhängig von der Batch-Größe und den Antwortzeiten des Connected-Content.

Ohne Connected-Content verarbeiten Kontextschritte deutlich schneller, da keine externen API-Aufrufe abgewartet werden müssen.

Hinweise

• Sie können pro Context-Schritt bis zu 10 Kontextvariablen definieren.
• Jede Variable erfordert einen eindeutigen Namen (nur Buchstaben, Zahlen und Unterstriche, maximal 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 Namespace mit denen, die in Context-Schritten erstellt werden. Wird eine Variable in einem Context-Schritt neu definiert, überschreibt sie den API-Wert.

Weitere Details und fortgeschrittene Anwendungsfälle finden Sie unter Referenz für Kontextvariablen.

Einen Context-Schritt erstellen

Tipp

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

Schritt 1: Einen Schritt hinzufügen

Fügen Sie Ihrem Canvas einen Schritt hinzu und ziehen Sie die Komponente per Drag-and-Drop aus der Seitenleiste, oder wählen Sie die Plus-Schaltfläche und dann Context aus.

Schritt 2: Variablen definieren

Hinweis

Sie können bis zu 10 Context-Variablen für jeden Context-Schritt definieren.

So definieren Sie eine Context-Variable:

1. Geben Sie Ihrer Context-Variable 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 vorhandenen Attributen zu erstellen.
4. Wählen Sie Vorschau, um den Wert Ihrer Context-Variable zu überprüfen.
5. (Optional) Um weitere Variablen hinzuzufügen, wählen Sie Context-Variable hinzufügen und wiederholen Sie die Schritte 1–4.
6. Wenn Sie fertig sind, wählen Sie Fertig.

Jetzt können Sie Ihre Context-Variable überall verwenden, wo Sie Liquid nutzen, z. B. in Nachrichten- und Nutzer:innen-Update-Schritten, indem Sie Personalisierung hinzufügen auswählen. Im Feld Context-Variablenname können Sie außerdem den Namen der Context-Variable eingeben oder ihn im Dropdown im Schritt-Editor auswählen. Eine vollständige Anleitung finden Sie unter Referenz für Context-Variablen.

Wichtig

Verwenden Sie beim Referenzieren von Context-Variablen immer das Format {{context.${variable_name}}}.

Filter für Context-Variablen

Sie können Filter mithilfe von Context-Variablen in Zielgruppenpfad- und Decision-Split-Schritten erstellen.

Um Nutzer:innen basierend auf einer Antwort eines Agent-Schritts weiterzuleiten, fügen Sie den Agent-Schritt vor Ihrem Zielgruppenpfad- oder Decision-Split-Schritt hinzu. Der Agent-Schritt speichert seine Ausgabe im Canvas-Context, den Sie mit Context-Variablenfiltern in diesen Verzweigungsschritten auswerten können.

Wenn der Agent ein Objekt zurückgibt und Sie nach einer verschachtelten Eigenschaft filtern möchten, geben Sie den Pfad im Feld Context-Variablenname in Punktnotation ein, anstatt nur den übergeordneten Variablennamen zu verwenden (zum Beispiel intent_agent.persona, wenn persona unter intent_agent verschachtelt ist).

Informationen zur Einrichtung von Filtern, Vergleichslogik und fortgeschrittene Beispiele finden Sie unter Referenz für Context-Variablen.

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 der Nutzerpfade

Wir empfehlen, Ihre Nutzerpfade zu testen und eine Vorschau anzuzeigen, um sicherzustellen, dass Ihre Nachrichten an die richtige Zielgruppe gesendet werden und Kontextvariablen zu den erwarteten Ergebnissen ausgewertet werden.

Hinweis

Wenn Sie eine Vorschau Ihres Canvas im Abschnitt Vorschau & Testversand des Editors anzeigen, wird der Zeitstempel in der Testnachrichtenvorschau nicht auf UTC standardisiert, da dieses Panel Vorschauen als Strings generiert. Das bedeutet: Wenn ein Canvas so eingerichtet ist, dass es ein time-Objekt akzeptiert, zeigt die Nachrichtenvorschau nicht genau an, was passiert, wenn der Canvas live ist. Um Ihren Canvas möglichst genau zu testen, empfehlen wir stattdessen die Vorschau der Nutzerpfade.

Achten Sie auf häufige Szenarien, die ungültige Kontextvariablen erzeugen. Wenn Sie eine Vorschau Ihres Nutzerpfads anzeigen, können Sie die Ergebnisse personalisierter Verzögerungsschritte mit Kontextvariablen sowie alle Zielgruppen- oder Decision-Split-Vergleiche einsehen, die Nutzer:innen mit Kontextvariablen abgleichen.

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

Konvertieren von Connected-Content-Strings in JSON

Wenn Sie einen Connected-Content-Aufruf in einem Context-Schritt ausführen, wird das von dem Aufruf zurückgegebene JSON aus Gründen der Konsistenz und Fehlervermeidung als String-Datentyp ausgewertet. Wenn Sie diesen String in JSON konvertieren möchten, verwenden Sie 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 Number ist, der Liquid-Ausdruck aber einen String zurückgibt, ist sie ungültig.

In diesen Fällen:

• Werden die Nutzer:innen zum nächsten Schritt weitergeführt.
• Zählt die Canvas-Schritt-Analyse dies als Not Updated.

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

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

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

Verwendung von abort_message in einer Kontextvariable

Sie können den abort_message-Liquid-Tag im Wert einer Kontextvariable verwenden, um diese Variable für bestimmte Nutzer:innen zu überspringen. In einem Kontextschritt wirkt sich abort_message nur auf die Variable aus, in der er sich befindet. Er stoppt weder den Schritt noch entfernt er die Nutzer:innen aus dem Canvas.

Wenn der Liquid-Code einer Kontextvariable abort_message für eine:n Nutzer:in aufruft:

• Wird die Variable für diese:n Nutzer:in nicht gesetzt. Wenn ein früherer Kontextschritt diese Variable bereits gesetzt hat, behält die/der Nutzer:in den 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 keinen neuen Wert von dieser Variable.
• Die/Der Nutzer:in wird zum nächsten Schritt weitergeleitet.
• Die Canvas-Schritt-Analyse zählt 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 Nutzerpfade in der Vorschau 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 ein, bei denen sie nicht gesetzt ist. Sie können diese beispielsweise mit einem Zielgruppenpfad-Schritt weiterleiten.

Hinweis

Abbrüche im Kontextschritt werden nicht im Nachrichtenaktivitätsprotokoll aufgezeichnet, 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 weitergeführt 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 auf das Gelingen von Wiederholungsversuchen, bevor sie voranschreiten.

Wiederholungsverhalten

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

• Kontext- und Nutzeraktualisierungsschritte: Braze wiederholt den Connected-Content-Aufruf auf Schrittebene (bis zu fünfmal). Wenn jeder Wiederholungsversuch fehlschlägt, wird die/der Nutzer:in aus dem Canvas entfernt.
• Nachrichtenschritte: Connected-Content mit :retry nutzt weiterhin die Messaging-Pipeline. Empfänger:innen werden in der Sendewarteschlange zurückgehalten, während Braze den Aufruf bis zu fünfmal wiederholt. Wenn jeder Wiederholungsversuch fehlschlägt, wird die Nachricht abgebrochen und die/der Nutzer:in zum nächsten Schritt weitergeleitet.

Bei Kontext- und Nutzeraktualisierungsschritten können bestimmte wiederholbare Schrittfehler – wie ein fehlgeschlagener Rabattcode-Abruf oder ein unerwarteter Schrittfehler – zusätzliche Wiederholungsversuche auf Schrittebene mit exponentiellem Backoff (ungefähr 13-mal) auslösen, bevor Braze die/den Nutzer:in aus dem Canvas entfernt.

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

Die Zeit, die benötigt wird, um alle Nutzer:innen durch einen Kontextschritt zu verarbeiten, hängt ab von:

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

Wenn Ihr Connected-Content-Endpunkt Rate-Limits hat, beachten Sie, dass Kontextschritte Nutzer:innen innerhalb jedes Batches sequenziell verarbeiten, was dazu beiträgt, Rate-Limits auf natürliche Weise einzuhalten. Allerdings werden mehrere Batches parallel verarbeitet. Stellen Sie daher sicher, dass Ihr Endpunkt gleichzeitige Anfragen von mehreren Batches verarbeiten kann.

Zeitzonenkonsistenz

Für Workspaces mit Canvas-Kontext sind alle standardmäßigen Zeitstempel-Event-Eigenschaften in aktionsbasierten Canvases in UTC. Dieses Verhalten gilt unabhängig davon, ob der Canvas einen Kontextschritt verwendet oder nicht.

Wichtig

Unter allen Umständen empfehlen wir dringend, Liquid-time_zone-Filter 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-Kontext auf Zeitstempel aus?

Für Workspaces mit Canvas-Kontext:

• Alle Zeitstempel mit einem Datum/Uhrzeit-Typ aus Trigger-Event-Eigenschaften in aktionsbasierten Canvases sind in UTC.
• Diese Änderung betrifft alle aktionsbasierten Canvases, unabhängig davon, ob das jeweilige Canvas einen Kontextschritt verwendet oder nicht.

Was ist der Grund für diese Änderung?

Diese Änderung ist Teil eines umfassenderen Bestrebens, eine vorhersehbarere und konsistentere Erfahrung beim Bearbeiten von Canvas-Schritten und Nachrichten zu schaffen.

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. In allen Fällen empfehlen wir die Verwendung von Liquid-time_zone-Filtern, damit Zeitstempel in der gewünschten Zeitzone dargestellt werden.

Hier ist ein Beispiel, wie Sie dies umsetzen können:

Was ist ein praktisches Beispiel dafür, wie das neue Zeitstempelverhalten meine Nachrichten beeinflussen könnte?

Nehmen wir an, wir haben ein aktionsbasiertes Canvas mit folgendem Inhalt in einem Nachrichtenschritt:

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 klar anzugeben, können wir Liquid-time_zone-Filter 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 in der Event-Eigenschaften-Payload 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"
}

Wie unterscheiden sich Kontextvariablen von Canvas-Entry-Eigenschaften?

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

Können Variablen einander in einem einzelnen Kontextschritt referenzieren?

Ja. Alle Variablen in einem Kontextschritt werden in einer Reihenfolge ausgewertet, sodass Sie die folgenden Kontextvariablen einrichten könnten:

Dies gilt auch über mehrere Kontextschritte hinweg. Stellen Sie sich zum Beispiel diese Abfolge vor:

1. Ein erster Kontextschritt erstellt eine Variable namens JobInfo mit dem Wert job_title.
2. Ein Nachrichtenschritt referenziert {{context.${JobInfo}}} und zeigt job_title für die Nutzer:innen an.
3. Später aktualisiert ein Kontextschritt die Kontextvariable und ändert den Wert von JobInfo zu job_description.
4. Alle nachfolgenden Schritte, die JobInfo referenzieren, verwenden nun den aktualisierten Wert job_description.

Kontextvariablen verwenden ihren jeweils aktuellsten Wert im gesamten Canvas, wobei jede Aktualisierung alle folgenden Schritte beeinflusst, die diese Variable referenzieren.