Ir al contenido

Vincular solicitudes de Canvas desencadenadas por API con eventos de mensajería de Currents

Rastrea una solicitud de Canvas desencadenada por API hasta sus resultados de mensajería: pasa un ID de correlación como propiedad de entrada al Canvas, añádelo al evento de envío con message_extras y une los eventos de participación por dispatch_id y user_id.

Acerca de este ejemplo

Pyrite Financial, una marca ficticia de servicios financieros, desencadena un Canvas desde sus propios sistemas cada vez que una transacción de un consumidor necesita una alerta. Llama a /canvas/trigger/send por cada evento. Su equipo de análisis quiere saber qué solicitud de desencadenamiento produjo cada envío, entrega y clic en Currents o Snowflake Data Sharing. Ambos incluyen los mismos datos de eventos de mensajería.

Los eventos de mensajería en Currents y Snowflake Data Sharing no incluyen por sí solos el identificador de tu solicitud de desencadenamiento. Este ejemplo muestra cómo:

  1. Generar un ID de correlación en tu sistema de envío y pasarlo como propiedad de entrada al Canvas en la solicitud de desencadenamiento.
  2. Hacer referencia a esa propiedad en el cuerpo del mensaje con la etiqueta de Liquid message_extras, que la escribe en el campo message_extras del evento de envío.
  3. Unir el evento de envío con los eventos de entrega y clic por dispatch_id y user_id.

Usa este patrón cuando un sistema externo controla el desencadenamiento y necesitas informar sobre la participación posterior por solicitud. Si una Campaign se adapta mejor a tu caso de uso que un Canvas, usa en su lugar un identificador de envío. El campo send_id es compatible con los endpoints de mensajería de Campaign, no con /canvas/trigger/send.

Consideraciones

  • dispatch_id por sí solo no es una clave única para Canvas. Braze trata los pasos en Canvas como eventos desencadenados, por lo que un paso puede generar un dispatch_id único por usuario y envío, o un dispatch_id compartido entre usuarios del mismo envío. Combínalo siempre con user_id. Para más información, consulta Comportamiento del ID de envío.
  • El campo message_extras solo aparece en los eventos de envío. Los eventos de entrega, apertura y clic no lo incluyen; por eso, el ID de correlación viaja en el evento de envío y, a partir de ahí, se une con los demás eventos.
  • Los message extras se adjuntan en el momento del envío de cada mensaje, así que un Canvas con varios pasos de Mensaje necesita la etiqueta en cada paso sobre el que quieras informar.
  • El conjunto de claves y valores de message_extras debe ocupar menos de 1000 bytes (1 KB), y Braze trunca los valores más largos. Los espacios en blanco cuentan para el límite.
  • El JSON resultante solo contiene valores de cadena. Usa una variable de Liquid como clave o valor. No anides otras etiquetas de Liquid dentro de message_extras.
  • Los eventos de Currents almacenan el ID de usuario de Braze en user_id y tu propio identificador en external_user_id. Haz la unión por user_id y selecciona external_user_id cuando necesites relacionar las filas con tus sistemas.
  • Usa Currents o Snowflake Data Sharing para este patrón. Ambos exponen los mismos campos de eventos de mensajería, incluido message_extras en los eventos de envío.
  • Los esquemas de Currents y Snowflake marcan message_extras como PII. Usa un ID de solicitud opaco en lugar de datos del consumidor.
  • El objeto context de una solicitud de desencadenamiento de Canvas puede ocupar hasta 50 KB, compartidos entre todas las propiedades que pases.

Configuración

Paso 1: Genera un ID de correlación por solicitud

En tu sistema de envío, crea un identificador para cada solicitud de desencadenamiento (por ejemplo, un UUID) y guárdalo en tu propio registro de solicitudes. Mantenlo opaco y lo bastante corto para respetar el límite de tamaño de message_extras.

Paso 2: Pasa el ID como propiedad de entrada al Canvas

Incluye el ID en el objeto context de tu solicitud a /canvas/trigger/send. Configúralo por destinatario cuando cada usuario tenga un ID distinto, o en el nivel superior cuando un único ID cubra a todos los destinatarios de la solicitud.

{
  "canvas_id": "canvas_identifier",
  "recipients": [
    {
      "external_user_id": "user_identifier",
      "context": {
        "request_id": "8f14e45f-ceea-467a-9e30-6b1b1c4a7d20"
      }
    }
  ]
}

Las propiedades de entrada al Canvas están disponibles como variables de contexto en todo el Canvas.

Paso 3: Añade el ID al evento de envío

En cada paso de Mensaje sobre el que quieras informar, asigna la variable de contexto y pásala a message_extras.

{% assign request_id = context.${request_id} %}
{% message_extras :key request_id :value {{request_id}} %}

Braze adjunta el par clave-valor al campo message_extras del evento de envío en el momento del envío.

Paso 4: Verifica con un envío de prueba

Envía una entrada de prueba a través del Canvas y luego confirma que el evento de envío en Currents o Snowflake Data Sharing contiene message_extras con tu clave request_id. Si el campo está vacío, revisa la sintaxis de la etiqueta. Las causas habituales son delimitadores mal escritos y claves y valores en un orden incorrecto.

Paso 5: Une los envíos con los eventos de entrega y clic

Con el ID en el evento de envío, únelo con los demás eventos por dispatch_id y user_id. El siguiente ejemplo del Generador de consultas muestra los resultados de entrega y clic por solicitud para correo electrónico:

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;

Sustituye las tablas por las del canal que uses para enviar; por ejemplo, USERS_MESSAGES_PUSHNOTIFICATION_SEND_SHARED y USERS_MESSAGES_PUSHNOTIFICATION_OPEN_SHARED para push. Para ver la lista completa de columnas de cada tabla, consulta la referencia de tablas SQL.

El ejemplo del Generador de consultas es solo una opción. Aplica las mismas uniones en Snowflake Data Sharing o en las exportaciones de Currents a tu propio almacén de datos: analiza message_extras en el evento de envío y luego une los eventos de participación por dispatch_id y user_id.

New Stuff!