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.

So funktioniert es

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

Kontextvariablen existieren nur für diese spezifische Canvas-Journey. Sie verändern das Profil der Nutzer:in 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 Nachrichten im gesamten Canvas anzureichern. Sie könnten beispielsweise eine Kontextvariable für die geplante Flugzeit einer Nutzer:in erstellen und sie dann verwenden, um personalisierte Verzögerungen festzulegen und Erinnerungen zu senden.

Sie können Kontextvariablen auf zwei Arten festlegen:

• Beim Canvas-Entry: Eigenschaften des angepassten Events oder API-Triggers werden automatisch als Kontextvariablen befüllt.
• 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 mithilfe von Liquid referenzieren, z. B. {{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-Entry definiert die Kontextvariablen basierend auf den neuesten Entry-Daten und der Canvas-Konfiguration neu, sodass Nutzer:innen mehrere aktive Journeys mit jeweils eigenem Kontext haben können. Wenn eine Kund:in beispielsweise zwei bevorstehende Flüge hat, 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 versenden, damit jede Nachricht für die jeweilige Buchung relevant bleibt.

Nutzer:innenverarbeitung 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 Nutzer:innen sequenziell verarbeitet.

Das bedeutet:

Beispiel: Wenn 3.500 Nutzer:innen einen Kontextschritt mit Connected-Content erreichen, das 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 Zeiten 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 werden Kontextschritte deutlich schneller verarbeitet, da keine externen API-Aufrufe abgewartet werden müssen.

Überlegungen

• Sie können bis zu 10 Kontextvariablen pro Context-Schritt definieren.
• Jede Variable erfordert 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 Namespace mit denen, die in Context-Schritten erstellt werden. Das Neudefinieren einer Variable in einem Context-Schritt überschreibt den API-Wert.

Weitere Details und erweiterte Nutzungsmöglichkeiten finden Sie unter Referenz zu Kontextvariablen.

Einen Kontextschritt erstellen

Tipp

Sie benötigen 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 mit dem Filter Context Variable 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 Kontext aus.

Schritt 2: Die Variablen definieren

Hinweis

Sie können bis zu 10 Kontextvariablen für jeden Kontextschritt 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 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 aus.

Jetzt können Sie Ihre Kontextvariable überall dort verwenden, wo Sie Liquid einsetzen, z. B. in Nachrichten- und Nutzer:innen-Update-Schritten, indem Sie Personalisierung hinzufügen auswählen. Im Feld Name der Kontextvariable können Sie auch den Namen der Kontextvariable eingeben oder ihn aus dem Dropdown im Schritt-Editor auswählen. Eine vollständige Anleitung finden Sie unter Referenz für Kontextvariablen.

Wichtig

Wenn Sie Kontextvariablen referenzieren, verwenden Sie immer das Format {{context.${variable_name}}}.

Filter für Kontextvariablen

Sie können Filter mit Kontextvariablen in Zielgruppenpfaden 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-Kontext, den Sie mit Kontextvariablen-Filtern 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 Name der Kontextvariable in Punktnotation ein, anstatt nur den Namen der übergeordneten Variable zu verwenden (z. B. intent_agent.persona, wenn persona unter intent_agent verschachtelt ist).

Informationen zur Filtereinrichtung, Vergleichslogik und erweiterten Beispielen finden Sie unter Referenz für 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 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 die erwarteten Ergebnisse liefern.

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 er 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 nachfolgende Schritte in Ihrem Canvas ebenfalls nicht ordnungsgemäß. 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 in einem Kontextschritt 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 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 zum Datentyp passt oder leer (null) ist.

Wenn der Datentyp der Kontextvariable beispielsweise Number ist, der Liquid-Ausdruck jedoch einen String zurückgibt, ist sie ungültig.

In diesen Fällen:

• Die Nutzer:innen werden 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 sicherzustellen, dass Ihre Kontextvariable korrekt aktualisiert wird. Wenn die Kontextvariable ungültig ist, können Ihre Nutzer:innen im Canvas über den Context-Schritt hinaus fortfahren, sich aber möglicherweise nicht für spätere Schritte qualifizieren.

Unter Datentypen finden Sie Beispielkonfigurationen für jeden Datentyp.

Verzögerungen beim Versand mit Connected-Content

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

Wiederholungsverhalten

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

• Context- und User-Update-Schritte: Braze wiederholt den Connected-Content-Aufruf auf Schrittebene (bis zu fünfmal). Wenn jeder Wiederholungsversuch fehlschlägt, verlässt die Nutzer:in den Canvas.
• Nachrichtenschritte: Connected-Content mit :retry verwendet weiterhin die Messaging-Pipeline. Empfänger:innen werden in der Sendewarteschlange verzögert, während Braze den Aufruf bis zu fünfmal wiederholt. Wenn jeder Wiederholungsversuch fehlschlägt, wird die Nachricht abgebrochen und die Nutzer:in wird zum nächsten Schritt weitergeleitet.

Bei Context- und User-Update-Schritten können bestimmte wiederholbare Schrittfehler – wie ein fehlgeschlagener Abruf eines Rabattcodes oder ein unerwarteter Schrittfehler – zusätzliche Wiederholungsversuche auf Schrittebene mit exponentiellem Backoff (ungefähr 13 Mal) auslösen, bevor Braze die Nutzer:in aus dem Canvas entfernt.

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

Die Zeit, die benötigt wird, um alle Nutzer:innen durch einen Context-Schritt zu verarbeiten, 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 Context-Schritte Nutzer:innen innerhalb jedes Batches sequenziell verarbeiten, was auf natürliche Weise bei der Einhaltung von Rate-Limits hilft. Allerdings werden mehrere Batches parallel verarbeitet, stellen Sie also sicher, dass Ihr Endpunkt gleichzeitige Anfragen von mehreren Batches verarbeiten kann.

Standardisierung der Zeitzonenkonsistenz

Da Canvas Context nun allgemein verfügbar ist, werden alle Standard-Zeitstempel-Event-Eigenschaften in aktionsbasierten Canvases in UTC angegeben. Diese Änderung ist Teil eines umfassenderen Bestrebens, ein vorhersehbareres und konsistenteres Erlebnis beim Bearbeiten von Canvas-Schritten und Nachrichten zu gewährleisten. Beachten Sie, dass diese Änderung alle aktionsbasierten Canvases betrifft, unabhängig davon, ob das jeweilige Canvas einen Context-Schritt 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. Sie können diese häufig gestellte Frage als Beispiel heranziehen.

Häufig gestellte Fragen

Was hat sich geändert, seit Canvas Context allgemein verfügbar ist?

Seit Canvas Context allgemein verfügbar ist, gelten folgende Details:

• Alle Zeitstempel mit einem Datetime-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 Context-Schritt verwendet oder nicht.

Was ist der Grund für diese Änderung?

Diese Änderung ist Teil eines umfassenderen Vorhabens, ein besser vorhersagbares und konsistentes Erlebnis beim Bearbeiten von Canvas-Schritten und Nachrichten zu schaffen.

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

Nein.

Betrifft diese Änderung die Canvas-Entry-Eigenschaften?

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 dafür:

Was ist ein praktisches Beispiel dafür, wie sich das neue Zeitstempelverhalten auf meine Nachrichten auswirken 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!

Dies ergibt 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 wird, ist der Zeitstempel hier in UTC.

Um eine Zeitzone eindeutig 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!

Dies ergibt 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 wird, 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 in anderen Schritten darauf verweisen, ähnlich wie bei der Verwendung einer Kontextvariable mit dem Liquid-Snippet.

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

Ja. Alle Variablen in einem Context-Schritt werden sequenziell ausgewertet, sodass Sie die folgenden Kontextvariablen einrichten könnten:

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

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

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