Passer au contenu

Cette page a été traduite automatiquement et peut contenir des inexactitudes. Pour signaler une erreur de traduction, utilisez le module de commentaires en bas de la table des matières, à droite de la page.

Associer les requêtes de Canvas déclenchés par API aux événements de messagerie Currents

Suivez une requête de Canvas déclenché par API jusqu’aux résultats de ses messages : transmettez un ID de corrélation comme propriété d’entrée du Canvas, ajoutez-le à l’événement d’envoi avec message_extras, puis joignez les événements d’engagement sur dispatch_id et user_id.

À propos de cet exemple

Pyrite Financial, une marque fictive de services financiers, déclenche un Canvas depuis ses propres systèmes chaque fois qu’une transaction client nécessite une alerte. Elle appelle /canvas/trigger/send pour chaque événement. Son équipe d’analyse souhaite savoir quelle requête de déclenchement a produit quel envoi, quelle distribution et quel clic dans Currents ou Snowflake Data Sharing. Ces deux sources contiennent les mêmes données d’événements de messagerie.

Les événements de messagerie dans Currents et Snowflake Data Sharing ne contiennent pas, à eux seuls, l’identifiant de votre requête de déclenchement. Cet exemple vous montre comment :

Générer un ID de corrélation dans votre système d’envoi et le transmettre comme propriété d’entrée du Canvas dans la requête de déclenchement.
Référencer cette propriété dans le corps du message avec l’étiquette Liquid message_extras, qui l’écrit dans le champ message_extras de l’événement d’envoi.
Joindre l’événement d’envoi aux événements de distribution et de clic sur dispatch_id et user_id.

Utilisez cette approche lorsqu’un système externe gère le déclenchement et que vous devez rendre compte de l’engagement en aval pour chaque requête. Si une Campaign convient mieux qu’un Canvas à votre cas d’usage, utilisez plutôt un identifiant d’envoi. Le champ send_id est pris en charge par les endpoints d’envoi de messages des Campaigns, mais pas par /canvas/trigger/send.

Considérations

dispatch_id seul n’est pas une clé unique pour les Canvas. Braze traite les étapes du canvas comme des événements déclenchés : une étape peut donc générer un dispatch_id unique par utilisateur et par envoi, ou un dispatch_id partagé entre les utilisateurs d’un même envoi. Associez-le toujours à user_id. Pour plus d’informations, consultez la section Comportement de l’ID de dispatch.
Le champ message_extras n’apparaît que sur les événements d’envoi. Les événements de distribution, d’ouverture et de clic ne l’incluent pas : c’est pourquoi l’ID de corrélation transite par l’événement d’envoi avant d’être joint aux autres événements.
Les message extras sont associés au moment de l’envoi, message par message. Un Canvas comportant plusieurs étapes Message nécessite donc l’étiquette dans chaque étape sur laquelle vous souhaitez produire des rapports.
L’ensemble des clés et valeurs de message_extras doit rester inférieur à 1 000 octets (1 Ko), et Braze tronque les valeurs plus longues. Les espaces sont pris en compte dans cette limite.
Le JSON obtenu contient uniquement des valeurs de chaîne de caractères. Vous pouvez utiliser une variable Liquid comme clé ou comme valeur. N’imbriquez pas d’autres étiquettes Liquid dans message_extras.
Les événements Currents stockent l’ID utilisateur Braze dans user_id et votre propre identifiant dans external_user_id. Effectuez la jointure sur user_id, et sélectionnez external_user_id lorsque vous devez rapprocher les lignes de vos systèmes.
Utilisez Currents ou Snowflake Data Sharing pour cette approche. Les deux exposent les mêmes champs d’événements de messagerie, y compris message_extras sur les événements d’envoi.
Les schémas Currents et Snowflake signalent message_extras comme contenant des données d’identification. Utilisez un ID de requête opaque plutôt que des données client.
L’objet context d’une requête de déclenchement de Canvas peut atteindre 50 Ko, répartis entre toutes les propriétés que vous transmettez.

Configuration

Étape 1 : Générer un ID de corrélation par requête

Dans votre système d’envoi, créez un identifiant pour chaque requête de déclenchement (par exemple, un UUID) et stockez-le dans votre propre journal de requêtes. Veillez à ce qu’il reste opaque et suffisamment court pour respecter la limite de taille de message_extras.

Étape 2 : Transmettre l’ID comme propriété d’entrée du Canvas

Incluez l’ID dans l’objet context de votre requête /canvas/trigger/send. Définissez-le par destinataire lorsque chaque utilisateur possède un ID distinct, ou au niveau supérieur lorsqu’un seul ID couvre tous les destinataires de la requête.

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

Les propriétés d’entrée du Canvas sont disponibles sous forme de variables de contexte dans l’ensemble du Canvas.

Étape 3 : Ajouter l’ID à l’événement d’envoi

Dans chaque étape Message sur laquelle vous souhaitez produire des rapports, assignez la variable de contexte et transmettez-la à message_extras.

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

Au moment de l’envoi, Braze associe la paire clé-valeur au champ message_extras de l’événement d’envoi.

Étape 4 : Vérifier avec un envoi test

Faites entrer un utilisateur test dans le Canvas, puis vérifiez que l’événement d’envoi dans Currents ou Snowflake Data Sharing contient message_extras avec votre clé request_id. Si le champ est vide, vérifiez la syntaxe de l’étiquette. Les causes les plus courantes sont des délimiteurs mal saisis et des clés et valeurs dans le mauvais ordre.

Étape 5 : Joindre les envois aux événements de distribution et de clic

Une fois l’ID présent sur l’événement d’envoi, effectuez les jointures sur dispatch_id et user_id. L’exemple suivant du générateur de requêtes présente les résultats de distribution et de clic par requête pour l’e-mail :

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;

Remplacez les tables par celles du canal que vous utilisez, par exemple USERS_MESSAGES_PUSHNOTIFICATION_SEND_SHARED et USERS_MESSAGES_PUSHNOTIFICATION_OPEN_SHARED pour les notifications push. Pour obtenir la liste complète des colonnes de chaque table, consultez la référence des tables SQL.

L’exemple du générateur de requêtes n’est qu’une possibilité parmi d’autres. Appliquez les mêmes jointures dans Snowflake Data Sharing ou sur les exports Currents vers votre propre entrepôt de données : analysez message_extras sur l’événement d’envoi, puis joignez les événements d’engagement sur dispatch_id et user_id.

New Stuff!