Archivage des messages
L’archivage des messages vous permet d’enregistrer une copie des messages envoyés aux utilisateurs à des fins d’archivage ou de conformité dans votre compartiment AWS S3, votre conteneur Azure Blob Storage ou votre compartiment Google Cloud Storage.
Cet article explique comment configurer l’archivage des messages, les références de payload JSON et les questions fréquemment posées.
L’archivage des messages est disponible en tant que fonctionnalité supplémentaire. Pour commencer à utiliser l’archivage des messages, contactez votre gestionnaire de la satisfaction client Braze.
Fonctionnement
Lorsque cette fonctionnalité est activée, Braze écrit un fichier JSON compressé au format gzip pour chaque message envoyé à un utilisateur via les canaux sélectionnés (e-mail, SMS/MMS, notification push ou message in-app). Braze écrit ces fichiers dans votre destination d’exportation de données par défaut. Cela inclut tous les types de campagnes pour chaque canal, comme les campagnes d’e-mails transactionnels envoyées via l’API d’e-mails transactionnels.
Ce fichier contiendra les champs définis dans la section Références des fichiers et reflétera les messages finaux, une fois le modèle appliqué, envoyés à l’utilisateur. Toutes les valeurs de modèle définies dans votre campagne (par exemple, {{${first_name}}}) afficheront la valeur finale reçue par l’utilisateur en fonction des informations de son profil. Vous pouvez ainsi conserver une copie du message envoyé pour répondre à des exigences de conformité, d’audit ou de support client.
Si vous configurez des identifiants pour plusieurs fournisseurs de stockage cloud, l’archivage des messages exporte uniquement vers celui qui est défini comme destination d’exportation de données par défaut. Si vous ne définissez pas explicitement de destination par défaut et qu’un compartiment AWS S3 est connecté, l’archivage des messages effectue le chargement dans ce compartiment.
L’activation de cette fonctionnalité aura un impact sur la vitesse de distribution de vos messages, car le chargement du fichier est effectué juste avant l’envoi du message afin de garantir l’exactitude des données. La latence introduite par l’archivage des messages dépendra du fournisseur de stockage cloud ainsi que du débit et de la taille des documents enregistrés.
Le fichier JSON sera enregistré dans votre compartiment de stockage selon la structure de clé suivante :
sent_messages/{channel, one of: email, push, sms}/{MD5 digest of downcased: email address, push token, or E.164 phone number}/{campaign or Canvas step API ID}/{dispatch ID}.json.gz
Voici un exemple de fichier :
sent_messages/email/819baa08d8d7e77e19d4666f5fc6050b/ee965cb2-8934-4b0a-acf1-91c899c2f915/651fd10b282850b39e1169c13975234b.json.gz
Le condensé MD5 ne peut être calculé qu’à partir d’une adresse e-mail, d’un jeton push ou d’un numéro de téléphone E.164 connu et converti en minuscules. Un condensé MD5 connu ne permet pas de retrouver l’adresse e-mail, le jeton push ou le numéro de téléphone E.164 en minuscules.
Vous avez du mal à trouver vos jetons push dans vos compartiments ?
Braze convertit vos jetons push en minuscules avant de les hacher. Ainsi, le jeton push Test_Push_Token12345 devient test_push_token12345 dans le chemin de la clé, avec le hachage 32b802170652af2b5624b695f34de089.
Configuration de l’archivage des messages
Cette section vous guide dans la configuration de l’archivage des messages pour votre espace de travail. Avant de commencer, vérifiez que votre entreprise a bien acheté et activé l’archivage des messages.
Étape 1 : Connecter un compartiment de stockage cloud
Si ce n’est pas déjà fait, connectez un compartiment de stockage cloud à Braze. Pour connaître la marche à suivre, consultez notre documentation partenaire sur Amazon S3, Azure Blob Storage ou Google Cloud Storage.
Vous n’avez pas besoin de configurer Currents pour l’archivage des messages : vous pouvez donc ignorer ce prérequis dans la documentation partenaire.
Étape 2 : Sélectionner les canaux pour l’archivage des messages
La page de paramètres Archivage des messages vous permet de choisir les canaux qui enregistreront une copie des messages envoyés dans votre compartiment de stockage cloud.
Pour sélectionner les canaux :
- Allez dans Paramètres > Archivage des messages.
- Sélectionnez vos canaux.
- Sélectionnez Enregistrer les modifications.
Si Archivage des messages n’apparaît pas dans Paramètres, vérifiez que votre entreprise a bien acheté et activé l’archivage des messages.
L’activation de l’archivage des messages pour les messages in-app convertit tous vos messages in-app en messages in-app modélisés. Une requête réseau est donc nécessaire avant que Braze puisse afficher le message. Pour plus d’informations, consultez Que se passe-t-il si j’active l’archivage des messages pour les messages in-app ?.
Liste d’adresses IP autorisées
Lorsque l’archivage des messages téléverse des fichiers dans votre compartiment de stockage cloud, Braze envoie des requêtes réseau depuis ses serveurs vers votre endpoint AWS S3, Azure Blob Storage ou Google Cloud Storage. Grâce à la liste d’adresses IP autorisées, vous pouvez vérifier que ces requêtes proviennent bien de Braze, ce qui ajoute une couche de sécurité supplémentaire.
Braze effectue les téléversements de l’archivage des messages depuis les mêmes adresses IP que celles utilisées pour le contenu connecté et Currents. Pour obtenir la liste complète des adresses IP par instance, consultez la section Liste d’adresses IP autorisées pour le contenu connecté.
Références de fichiers
Voici les références du payload JSON livré dans votre compartiment de stockage cloud à chaque envoi de message. Consultez notre dépôt d’exemples de code pour obtenir des fichiers d’exemple d’archivage des messages.
{
"version": 1, //numerical version of the JSON structure
"to": ToAddress, ("[email protected]")
"subject": SubjectLine ("20% off coupon inside!"),
"from_name": DisplayName ("Braze"),
"from_address": FromAddress ("[email protected]"),
"html_body": HtmlBody,
"plaintext_body": PlainTextBody,
"amp_body": AMPEmailBody,
"extras": Hash of key-value pairs from Email Extras configured in the email editor,
"headers": HashOfHeaders,
"sent_at": UnixTimestamp,
"dispatch_id": DispatchIdFromBraze,
"campaign_id": CampaignApiId, // may not be available
"canvas_id": CanvasApiId, // may not be available
"canvas_step_id": CanvasStepApiId, // may not be available
"canvas_variation_id" : CanvasVariationApiId, // may not be available
"message_variation_id": MessageVariationApiId, // may not be available,
"attachments": Array of JSON Objects containing 'bytes' and 'file_name', // may not be available
"user_id": String,
"campaign_name": String, // will only be available if the message is from a campaign
"canvas_name": String, // will only be available if the message is from a Canvas
"canvas_step_name": String, // will only be available if the message is from a Canvas
"external_id": String
}
Le champ extras contient les paires clé-valeur configurées dans le champ Extras d’e-mail lors de la rédaction d’un e-mail dans l’éditeur HTML. Les extras d’e-mail fonctionnent avec tous les fournisseurs de services d’e-mailing (y compris SendGrid et Sparkpost) et sont inclus dans les messages archivés, quel que soit le fournisseur utilisé. Pour plus d’informations sur la configuration des extras d’e-mail, consultez Créer une campagne par e-mail. Pour renvoyer des données vers Currents, consultez Extras de message.
{
"version": 1 //numerical version of the JSON structure
"to": PhoneNumber, ("+15555555555"),
"body": Body ("Hi there!"),
"subscription_group": SubscriptionGroupExternalId,
"provider": StringOfProviderName,
"media_urls": ArrayOfString, // indicates a message is MMS
"sent_at": UnixTimestamp,
"dispatch_id": DispatchIdFromBraze,
"campaign_id": CampaignApiId, // may not be available
"canvas_id": CanvasApiId, // may not be available
"canvas_step_id": CanvasStepApiId, // may not be available
"canvas_variation_id" : CanvasVariationApiId, // may not be available
"message_variation_id": MessagVariationApiId, // may not be available
"user_id": String,
"campaign_name": String, // will only be available if the message is from a campaign
"canvas_name": String, // will only be available if the message is from a Canvas
"canvas_step_name": String, // will only be available if the message is from a Canvas
"external_id": String
}
{
"version": 1, //numerical version of the JSON structure
"to": PushToken,
"payload": JsonOfEntirePushPayload,
"platform": one of "android_push" | "ios_push" | "kindle_push" | "web_push",
"app_id": ApiKeyOfApp,
"sent_at": UnixTimestamp,
"dispatch_id": DispatchIdFromBraze,
"campaign_id": CampaignApiId, // may not be available
"canvas_id": CanvasApiApiId, // may not be available
"canvas_step_id": CanvasStepApiId, // may not be available
"canvas_variation_id" : CanvasVariationApiId, // may not be available
"message_variation_id": MessagVariationApiId, // may not be available
"user_id": String,
"campaign_name": String, // will only be available if the message is from a campaign
"canvas_name": String, // will only be available if the message is from a Canvas
"canvas_step_name": String, // will only be available if the message is from a Canvas
"external_id": String
}
Variations de structure du payload push
Le champ payload de premier niveau des archives de notifications push contient l’intégralité du payload du fournisseur, tel qu’il a été envoyé à l’appareil. Dans ce JSON, des clés comme aps (pour APNs) ou notification et data (pour FCM) peuvent varier considérablement selon le type de message, la plateforme et la configuration.
L’archivage des messages capture le payload du message lui-même, mais n’inclut pas les métadonnées de distribution envoyées à FCM ou APNs. Ces métadonnées de distribution comprennent :
- Les jetons d’appareil
- Les paramètres de priorité
- La durée de vie (TTL)
- Les ID de regroupement (collapse IDs)
- Les en-têtes APNs
- Les horodatages d’expiration
- D’autres champs de configuration de distribution
Ces champs servent d’instructions de distribution pour le fournisseur de notifications push. Ils ne sont généralement pas considérés comme faisant partie du contenu du message.
Par exemple :
- Les notifications push iOS peuvent avoir des structures différentes selon qu’il s’agit de notifications enrichies (où
aps.alertest un objet contenant des champs commetitleetbody) ou de notifications simples (oùaps.alertest une chaîne de caractères). - Les notifications push Android (par exemple, FCM) utilisent des messages de données avec des clés personnalisées. La structure du payload peut inclure différents champs facultatifs selon la configuration du message, comme des boutons push, des carrousels ou des métadonnées supplémentaires.
Par ailleurs, les envois de test depuis le tableau de bord peuvent produire des structures de payload différentes de celles des messages en production.
Le format du payload JSON peut varier d’un message à l’autre et évoluer au fil du temps. Lorsque vous analysez des payloads push archivés, ne partez pas du principe que la structure est fixe ou que les mêmes champs seront toujours présents. Mettez en place une logique d’analyse flexible, capable de gérer différents formats de payload.
{
"version": 1, //numerical version of the JSON structure
"to": UserId, // the message recipient's identifier, typically matches user_id
"payload": JsonOfEntireInAppMessagePayload,
"platform": StringOfPlatformName, ("web")
"device_identifier": DeviceIdentifier, // may not be available
"app_id": ApiKeyOfApp,
"sent_at": UnixTimestamp,
"dispatch_id": DispatchIdFromBraze,
"campaign_id": CampaignApiId, // may not be available
"canvas_id": CanvasApiId, // may not be available
"canvas_step_id": CanvasStepApiId, // may not be available
"canvas_variation_id" : CanvasVariationApiId, // may not be available
"message_variation_id": MessageVariationApiId, // may not be available
"user_id": String,
"campaign_name": String, // will only be available if the message is from a campaign
"canvas_name": String, // will only be available if the message is from a Canvas
"canvas_step_name": String, // will only be available if the message is from a Canvas
"external_id": String
}
Variations de structure du payload des messages in-app
Le champ payload de premier niveau des archives de messages in-app contient la configuration complète du message in-app, y compris son contenu (comme le texte et l’en-tête du message) et ses paramètres d’affichage (comme le type de message, l’alignement du texte et les couleurs). Les champs présents varient selon le type de message in-app, par exemple Modal, Contextuel, Plein écran ou HTML personnalisé.
Le format du payload JSON peut varier d’un message à l’autre et évoluer au fil du temps. Lorsque vous analysez des payloads de messages in-app archivés, ne partez pas du principe que la structure est fixe ou que les mêmes champs seront toujours présents. Mettez en place une logique d’analyse flexible, capable de gérer différents formats de payload.
Foire aux questions
Que se passe-t-il si j’active l’archivage des messages pour les messages in-app ?
Lorsque vous activez l’archivage des messages pour les messages in-app, tous les messages in-app deviennent des messages in-app modélisés. Une requête réseau est donc nécessaire avant que Braze puisse afficher le message.
Quels éléments de modélisation ne sont pas inclus dans le payload ?
Les modifications apportées après que le message a quitté Braze ne figurent pas dans le fichier enregistré dans votre compartiment de stockage cloud. Cela inclut les modifications effectuées par nos partenaires de distribution d’e-mails, comme l’encapsulation des liens pour le suivi des clics et l’insertion de pixels de suivi.
À quoi correspondent les messages associés à la valeur « unassociated » dans le chemin de la Campaign ?
Lorsqu’un message est envoyé en dehors d’une Campaign ou d’un Canvas, l’ID de Campaign dans le nom du fichier est « unassociated ». C’est le cas lorsque vous envoyez des messages de test depuis le tableau de bord, lorsque Braze envoie des réponses automatiques par SMS/MMS, ou lorsque des messages envoyés via l’API ne précisent pas d’ID de Campaign.
Comment obtenir plus d’informations sur cet envoi ?
Vous pouvez utiliser l’external_id ou le dispatch_id avec le user_id pour croiser le message modélisé avec nos données Currents et obtenir plus d’informations, comme l’horodatage de sa réception, si l’utilisateur a ouvert le message ou cliqué dessus, et plus encore.
Comment les nouvelles tentatives sont-elles gérées ?
Si votre compartiment de stockage cloud est inaccessible, Braze effectue jusqu’à trois nouvelles tentatives avec un backoff jitter. Les nouvelles tentatives liées aux limites de débit d’AWS S3 sont gérées automatiquement par Braze.
Que se passe-t-il si mes identifiants ne sont pas valides ?
Si vos identifiants de stockage cloud deviennent invalides à un moment donné, Braze ne pourra enregistrer aucun message dans votre compartiment de stockage cloud, et ces messages seront perdus. Nous vous recommandons de configurer vos préférences de notification pour Amazon Web Services, Google Cloud Storage ou Azure (Microsoft Cloud Services) afin de recevoir des alertes en cas de problème d’identifiants.
Pourquoi l’horodatage sent_at de mon fichier d’archive diffère-t-il légèrement de l’horodatage d’envoi dans Currents ?
La copie rendue est téléchargée juste avant l’envoi du message à l’utilisateur. En raison des délais de téléchargement vers le stockage cloud, il peut y avoir un décalage de quelques secondes entre l’horodatage sent_at de la copie rendue et l’heure réelle de l’envoi.
Puis-je créer un nouveau compartiment dédié à l’archivage des messages tout en conservant le compartiment actuel utilisé pour les données Currents ?
Non. Si dedicated message archiving buckets while keeping a separate Currents bucket vous intéresse, envoyez un retour produit.
Les données archivées sont-elles écrites dans un dossier dédié au sein d’un compartiment existant, comme pour les exportations de données Currents ?
Les données sont écrites dans une section sent_messages du compartiment. Pour plus de détails, consultez la section Fonctionnement.
Puis-je utiliser l’archivage des messages pour regrouper les fichiers par espace de travail ?
Non. L’archivage des messages ne permet pas de regrouper les fichiers par espace de travail. Vous pouvez toutefois déterminer à quel espace de travail appartient l’ID API de la Campaign ou de l’étape du Canvas, puis regrouper les fichiers en fonction de cette information.