API-getriggerte Canvas-Anfragen mit Messaging-Events in Currents verknüpfen
Verfolgen Sie eine API-getriggerte Canvas-Anfrage bis zu ihren Messaging-Ergebnissen: Übergeben Sie eine Korrelations-ID als Canvas-Entry-Eigenschaft, hinterlegen Sie sie mit
message_extrasim Send-Event und verknüpfen Sie Engagement-Events überdispatch_idunduser_id.
Über dieses Beispiel
Pyrite Financial, eine fiktive Marke für Finanzdienstleistungen, triggert jedes Mal ein Canvas aus den eigenen Systemen, wenn für eine Transaktion einer Verbraucherin oder eines Verbrauchers eine Benachrichtigung nötig ist. Dafür ruft das Unternehmen pro Event /canvas/trigger/send auf. Das Analytics-Team möchte wissen, welche Trigger-Anfrage welchen Versand, welche Zustellung und welchen Klick in Currents oder Snowflake Data Sharing erzeugt hat. Beide enthalten dieselben Daten zu Messaging-Events.
Messaging-Events in Currents und Snowflake Data Sharing enthalten den Bezeichner Ihrer Trigger-Anfrage nicht von selbst. Dieses Beispiel zeigt Ihnen, wie Sie:
- In Ihrem sendenden System eine Korrelations-ID generieren und sie in der Trigger-Anfrage als Canvas-Entry-Eigenschaft übergeben.
- Diese Eigenschaft im Nachrichtentext mit dem
message_extras-Liquid-Tag referenzieren, der sie in das Feldmessage_extrasdes Send-Events schreibt. - Das Send-Event über
dispatch_idunduser_idmit Zustellungs- und Klick-Events verknüpfen.
Nutzen Sie dieses Vorgehen, wenn ein externes System den Trigger steuert und Sie das nachgelagerte Engagement pro Anfrage auswerten müssen. Wenn für Ihren Anwendungsfall eher eine Campaign als ein Canvas passt, verwenden Sie stattdessen einen Send-Bezeichner. Das Feld send_id wird von den Messaging-Endpunkten für Campaigns unterstützt, nicht von /canvas/trigger/send.
Zu beachten
dispatch_idallein ist für Canvas kein eindeutiger Schlüssel. Braze behandelt Canvas-Schritte als getriggerte Events. Daher kann ein Schritt pro Nutzer:in und Versand eine eindeutigedispatch_iderzeugen oder eine gemeinsamedispatch_idfür alle Nutzer:innen im selben Versand. Kombinieren Sie sie immer mituser_id. Weitere Informationen finden Sie unter Verhalten der Dispatch-ID.- Das Feld
message_extraserscheint nur in Send-Events. Zustellungs-, Öffnungs- und Klick-Events enthalten es nicht. Deshalb wird die Korrelations-ID über das Send-Event transportiert und von dort aus verknüpft. - Message Extras werden zum Versandzeitpunkt pro Nachricht angehängt. Ein Canvas mit mehreren Nachrichten-Schritten benötigt den Tag daher in jedem Schritt, den Sie auswerten möchten.
- Alle Schlüssel und Werte in
message_extrasdürfen zusammen 1.000 Byte (1 KB) nicht überschreiten. Längere Werte kürzt Braze. Leerzeichen zählen zum Limit. - Das resultierende JSON enthält ausschließlich String-Werte. Verwenden Sie eine Liquid-Variable als Schlüssel oder Wert. Verschachteln Sie keine anderen Liquid-Tags innerhalb von
message_extras. - Currents-Events speichern die Braze-Nutzer-ID in
user_idund Ihren eigenen Bezeichner inexternal_user_id. Verknüpfen Sie überuser_idund wählen Sieexternal_user_idaus, wenn Sie Zeilen Ihren eigenen Systemen zuordnen müssen. - Nutzen Sie für dieses Muster Currents oder Snowflake Data Sharing. Beide stellen dieselben Felder für Messaging-Events bereit, einschließlich
message_extrasin Send-Events. - Die Schemas von Currents und Snowflake kennzeichnen
message_extrasals PII. Verwenden Sie eine nicht sprechende Anfrage-ID statt Daten von Verbraucher:innen. - Das Objekt
contextin einer Canvas-Trigger-Anfrage darf bis zu 50 KB groß sein. Dieses Limit gilt für alle übergebenen Eigenschaften zusammen.
Einrichtung
Schritt 1: Korrelations-ID pro Anfrage generieren
Erstellen Sie in Ihrem sendenden System für jede Trigger-Anfrage einen Bezeichner, zum Beispiel eine UUID, und speichern Sie ihn in Ihrem eigenen Anfrageprotokoll. Der Bezeichner sollte nicht sprechend und kurz genug sein, um in das Größenlimit von message_extras zu passen.
Schritt 2: ID als Canvas-Entry-Eigenschaft übergeben
Fügen Sie die ID in das Objekt context Ihrer Anfrage an /canvas/trigger/send ein. Legen Sie sie pro Empfänger:in fest, wenn jede:r Nutzer:in eine eigene ID hat, oder auf oberster Ebene, wenn eine ID für alle Empfänger:innen der Anfrage gilt.
{
"canvas_id": "canvas_identifier",
"recipients": [
{
"external_user_id": "user_identifier",
"context": {
"request_id": "8f14e45f-ceea-467a-9e30-6b1b1c4a7d20"
}
}
]
}
Canvas-Entry-Eigenschaften stehen im gesamten Canvas als Kontextvariablen zur Verfügung.
Schritt 3: ID im Send-Event hinterlegen
Weisen Sie in jedem Nachrichten-Schritt, den Sie auswerten möchten, die Kontextvariable zu und übergeben Sie sie an message_extras.
{% assign request_id = context.${request_id} %}
{% message_extras :key request_id :value {{request_id}} %}
Braze hängt das Schlüssel-Wert-Paar zum Versandzeitpunkt an das Feld message_extras des Send-Events an.
Schritt 4: Mit einem Testversand überprüfen
Senden Sie einen Test-Entry durch das Canvas und überprüfen Sie anschließend, ob das Send-Event in Currents oder Snowflake Data Sharing message_extras mit Ihrem Schlüssel request_id enthält. Wenn das Feld leer ist, prüfen Sie die Syntax des Tags. Häufige Ursachen sind falsch geschriebene Trennzeichen sowie Schlüssel und Werte in falscher Reihenfolge.
Schritt 5: Send-Events mit Zustellungs- und Klick-Events verknüpfen
Sobald die ID im Send-Event steht, verknüpfen Sie von dort aus über dispatch_id und user_id. Das folgende Beispiel für den Query Builder wertet Zustellungen und Klicks pro Anfrage für E-Mails aus:
WITH sends AS (
SELECT
USER_ID,
EXTERNAL_USER_ID,
DISPATCH_ID,
PARSE_JSON(MESSAGE_EXTRAS):request_id::STRING AS request_id,
TIME AS send_time
FROM USERS_MESSAGES_EMAIL_SEND_SHARED
WHERE MESSAGE_EXTRAS IS NOT NULL
AND PARSE_JSON(MESSAGE_EXTRAS):request_id IS NOT NULL
)
SELECT
s.request_id AS "Request ID",
s.EXTERNAL_USER_ID AS "External User ID",
MIN(s.send_time) AS "Sent",
MIN(d.TIME) AS "Delivered",
MIN(c.TIME) AS "First Click"
FROM sends AS s
LEFT JOIN USERS_MESSAGES_EMAIL_DELIVERY_SHARED AS d
ON d.USER_ID = s.USER_ID
AND d.DISPATCH_ID = s.DISPATCH_ID
LEFT JOIN USERS_MESSAGES_EMAIL_CLICK_SHARED AS c
ON c.USER_ID = s.USER_ID
AND c.DISPATCH_ID = s.DISPATCH_ID
GROUP BY 1, 2
ORDER BY 3 DESC;
Ersetzen Sie die Tabellen durch die Tabellen für den Kanal, über den Sie versenden, zum Beispiel USERS_MESSAGES_PUSHNOTIFICATION_SEND_SHARED und USERS_MESSAGES_PUSHNOTIFICATION_OPEN_SHARED für Push. Die vollständige Spaltenliste pro Tabelle finden Sie in der SQL-Tabellenreferenz.
Das Beispiel für den Query Builder ist nur ein möglicher Weg. Wenden Sie dieselben Verknüpfungen in Snowflake Data Sharing oder auf Currents-Exporte in Ihr eigenes Warehouse an: Parsen Sie message_extras im Send-Event und verknüpfen Sie anschließend Engagement-Events über dispatch_id und user_id.