Zum Inhalt springen

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_extras im Send-Event und verknüpfen Sie Engagement-Events über dispatch_id und user_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:

  1. In Ihrem sendenden System eine Korrelations-ID generieren und sie in der Trigger-Anfrage als Canvas-Entry-Eigenschaft übergeben.
  2. Diese Eigenschaft im Nachrichtentext mit dem message_extras-Liquid-Tag referenzieren, der sie in das Feld message_extras des Send-Events schreibt.
  3. Das Send-Event über dispatch_id und user_id mit 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_id allein 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 eindeutige dispatch_id erzeugen oder eine gemeinsame dispatch_id für alle Nutzer:innen im selben Versand. Kombinieren Sie sie immer mit user_id. Weitere Informationen finden Sie unter Verhalten der Dispatch-ID.
  • Das Feld message_extras erscheint 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_extras dü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_id und Ihren eigenen Bezeichner in external_user_id. Verknüpfen Sie über user_id und wählen Sie external_user_id aus, 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_extras in Send-Events.
  • Die Schemas von Currents und Snowflake kennzeichnen message_extras als PII. Verwenden Sie eine nicht sprechende Anfrage-ID statt Daten von Verbraucher:innen.
  • Das Objekt context in 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.

New Stuff!