Archivado de mensajes
El archivado de mensajes te permite guardar una copia de los mensajes enviados a los usuarios con fines de archivo o cumplimiento normativo en tu contenedor de AWS S3, contenedor de Azure Blob Storage o contenedor de Google Cloud Storage.
Este artículo trata sobre cómo configurar el archivado de mensajes, las referencias de carga útil JSON y las preguntas frecuentes.
El archivado de mensajes está disponible como característica adicional. Para empezar a archivar mensajes, ponte en contacto con tu CSM de Braze.
Cómo funciona
Cuando activas esta característica, Braze escribe un archivo JSON comprimido con gzip por cada mensaje enviado a un usuario a través de los canales que selecciones (correo electrónico, SMS/MMS, push o mensaje dentro de la aplicación). Braze escribe estos archivos en tu destino predeterminado de exportación de datos. Esto incluye todos los tipos de Campaign de cada canal, como las Campaigns de correo electrónico transaccional enviadas a través de la API de correo electrónico transaccional.
Este archivo contendrá los campos definidos en Referencias de archivos y reflejará los mensajes finales con plantilla enviados al usuario. Cualquier valor con plantilla definido en tu Campaign (por ejemplo, {{${first_name}}}) mostrará el valor final que recibió el usuario según la información de su perfil. Esto te permite conservar una copia del mensaje enviado para cumplir requisitos de conformidad normativa, auditoría o atención al cliente.
Si configuras credenciales para varios proveedores de almacenamiento en el cloud, el archivado de mensajes solo exporta al que esté marcado como destino predeterminado de exportación de datos. Si no estableces un predeterminado explícito y hay un contenedor de AWS S3 conectado, el archivado de mensajes se sube a ese contenedor.
Activar esta característica afectará a la velocidad de entrega de tus mensajes, ya que la subida del archivo se realiza inmediatamente antes de enviar el mensaje para mantener la precisión. La latencia que introduce el archivado de mensajes dependerá del proveedor de almacenamiento en el cloud, así como del rendimiento y el tamaño de los documentos guardados.
El JSON se guardará en tu contenedor de almacenamiento con la siguiente estructura de claves:
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
Un archivo de ejemplo podría tener este aspecto:
sent_messages/email/819baa08d8d7e77e19d4666f5fc6050b/ee965cb2-8934-4b0a-acf1-91c899c2f915/651fd10b282850b39e1169c13975234b.json.gz
El resumen MD5 solo se puede calcular usando una dirección de correo electrónico, un token de notificaciones push o un número de teléfono E.164 conocidos y en minúsculas. Un resumen MD5 conocido no se puede revertir para obtener la dirección de correo electrónico, el token de notificaciones push o el número de teléfono E.164 en minúsculas.
¿Tienes problemas para encontrar tus tokens de notificaciones push en tus contenedores?
Braze convierte tus tokens de notificaciones push a minúsculas antes de aplicarles el hash. Como resultado, el token de notificaciones push Test_Push_Token12345 se convierte a test_push_token12345 en la ruta de la clave, con el hash 32b802170652af2b5624b695f34de089.
Configurar el archivado de mensajes
Esta sección te guía en la configuración del archivado de mensajes para tu espacio de trabajo. Antes de continuar, confirma que tu empresa ha adquirido y activado el archivado de mensajes.
Paso 1: Conecta un contenedor de almacenamiento en el cloud
Si aún no lo has hecho, conecta un contenedor de almacenamiento en el cloud a Braze. Para ver los pasos, consulta nuestra documentación de partners sobre Amazon S3, Azure Blob Storage o Google Cloud Storage.
No necesitas configurar Currents para el archivado de mensajes, así que puedes omitir ese requisito previo en la documentación de partners.
Paso 2: Selecciona los canales para el archivado de mensajes
La página de configuración Archivado de mensajes controla qué canales guardarán una copia de los mensajes enviados en tu contenedor de almacenamiento en el cloud.
Para seleccionar los canales:
- Ve a Configuración > Archivado de mensajes.
- Selecciona tus canales.
- Selecciona Guardar cambios.
Si no ves Archivado de mensajes en Configuración, confirma que tu empresa ha adquirido y activado el archivado de mensajes.
Habilitar el archivado de mensajes para los mensajes dentro de la aplicación convierte todos tus mensajes dentro de la aplicación en mensajes dentro de la aplicación con plantilla. Esto significa que se requiere una solicitud de red antes de que Braze pueda mostrar el mensaje. Para más información, consulta ¿Qué ocurre si activo el archivado de mensajes para los mensajes dentro de la aplicación?.
Lista de IP permitidas
Cuando el archivo de mensajes sube archivos a tu contenedor de almacenamiento en el cloud, Braze realiza solicitudes de red desde nuestros servidores a tu endpoint de AWS S3, Azure Blob Storage o Google Cloud Storage. Con la lista de IP permitidas, puedes verificar que estas solicitudes provienen de Braze, lo que añade una capa de seguridad.
Braze envía las subidas del archivo de mensajes desde las mismas direcciones IP que se utilizan para el contenido conectado y Currents. Para ver la lista completa de IP por instancia, consulta Lista de IP permitidas para el contenido conectado.
Referencias de archivos
A continuación, se muestran referencias de la carga útil JSON que se entrega a tu contenedor de almacenamiento en el cloud cada vez que se envía un mensaje. Consulta nuestro repositorio de ejemplos de código para ver archivos de ejemplo de archivado de mensajes.
{
"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
}
El campo extras contiene los pares clave-valor configurados en el campo Extras de correo electrónico al redactar un correo electrónico en el editor HTML. Los extras de correo electrónico funcionan con todos los proveedores de servicios de correo electrónico (incluidos SendGrid y Sparkpost) y se incluyen en los mensajes archivados independientemente del proveedor que se utilice. Para obtener más información sobre cómo configurar los extras de correo electrónico, consulta Crear una campaña de correo electrónico. Para enviar datos de vuelta a Currents, consulta Extras de mensajes.
{
"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
}
Variaciones en la estructura de la carga útil push
El campo payload de nivel superior en los archivos de notificaciones push contiene toda la carga útil del proveedor tal como se envió al dispositivo. Dentro de este JSON, claves como aps (para APN) o notification y data (para FCM) pueden variar considerablemente según el tipo de mensaje, la plataforma y la configuración.
El archivado de mensajes captura la carga útil del mensaje en sí, pero no incluye los metadatos de entrega que se envían a FCM o APN. Los metadatos de entrega incluyen:
- Tokens de dispositivo
- Configuración de prioridad
- Tiempo de vida (TTL)
- ID de contracción
- Encabezados de APN
- Marcas de tiempo de caducidad
- Otros campos de configuración de entrega
Estos campos funcionan como instrucciones de entrega para el proveedor de notificaciones push. Por lo general, no se consideran parte del contenido del mensaje.
Por ejemplo:
- Las notificaciones push de iOS pueden tener estructuras diferentes para las notificaciones enriquecidas (donde
aps.alertes un objeto que contiene campos comotitleybody) frente a las notificaciones simples (dondeaps.alertes una cadena). - Las notificaciones push de Android (por ejemplo, FCM) utilizan mensajes de datos con claves personalizadas. La estructura de la carga útil puede incluir distintos campos opcionales según la configuración del mensaje, como botones push, carruseles o metadatos adicionales.
Además, los envíos de prueba desde el panel pueden producir estructuras de carga útil diferentes a las de los mensajes en producción.
El formato de la carga útil JSON puede variar entre mensajes y cambiar con el tiempo. Al analizar cargas útiles push archivadas, no supongas una estructura fija ni esperes que los mismos campos estén siempre presentes. Implementa una lógica de análisis flexible que admita distintos formatos de carga útil.
{
"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
}
Variaciones en la estructura de la carga útil de mensajes dentro de la aplicación
El campo payload de nivel superior en los archivos de mensajes dentro de la aplicación contiene la configuración completa del mensaje dentro de la aplicación, incluido su contenido (como el texto y el encabezado del mensaje) y la configuración de visualización (como el tipo de mensaje, la alineación del texto y los colores). Los campos exactos presentes varían según el tipo de mensaje dentro de la aplicación, como Modal, Deslizamiento hacia arriba, Pantalla completa o HTML personalizado.
El formato de la carga útil JSON puede variar entre mensajes y cambiar con el tiempo. Al analizar cargas útiles de mensajes dentro de la aplicación archivadas, no supongas una estructura fija ni esperes que los mismos campos estén siempre presentes. Implementa una lógica de análisis flexible que admita distintos formatos de carga útil.
Preguntas frecuentes
¿Qué ocurre si activo el archivado de mensajes para los mensajes dentro de la aplicación?
Cuando activas el archivado de mensajes para los mensajes dentro de la aplicación, todos los mensajes dentro de la aplicación se convierten en mensajes dentro de la aplicación con plantilla. Esto significa que se necesita una solicitud de red antes de que Braze pueda mostrar el mensaje.
¿Qué plantillas no se incluyen en la carga útil?
Las modificaciones que se hagan después de que el mensaje salga de Braze no se reflejarán en el archivo guardado en tu contenedor de almacenamiento en el cloud. Esto incluye las modificaciones que hacen nuestros partners de entrega de correo, como envolver los enlaces para el seguimiento de clics e insertar píxeles de seguimiento.
¿Qué son los mensajes con el valor “unassociated” en la ruta de la Campaign?
Cuando se envía un mensaje fuera de una Campaign o un Canvas, el ID de campaña en el nombre del archivo será “unassociated”. Esto ocurre cuando envías mensajes de prueba desde el panel, cuando Braze envía respuestas automáticas por SMS/MMS o cuando los mensajes enviados a través de la API no especifican un ID de campaña.
¿Cómo encuentro más información sobre este envío?
Puedes usar external_id o dispatch_id junto con user_id para cruzar el mensaje con plantilla con nuestros datos de Currents y encontrar más información, como la marca de tiempo de entrega, si el usuario abrió el mensaje o hizo clic en él, y mucho más.
¿Cómo se gestionan los reintentos?
Si no se puede acceder a tu contenedor de almacenamiento en el cloud, Braze lo reintentará hasta tres veces con un retroceso con jitter. Braze gestiona automáticamente los reintentos por límite de velocidad de AWS S3.
¿Qué ocurre si mis credenciales no son válidas?
Si tus credenciales de almacenamiento en el cloud dejan de ser válidas en algún momento, Braze no podrá guardar ningún mensaje en tu contenedor de almacenamiento en el cloud, y esos mensajes se perderán. Te recomendamos configurar tus preferencias de notificación para Amazon Web Services, Google Cloud Services o Azure (Microsoft Cloud Services) para que recibas alertas sobre cualquier problema con las credenciales.
¿Por qué la marca de tiempo sent_at de mi archivo de archivado difiere ligeramente de la marca de tiempo de envío en Currents?
La copia renderizada se sube inmediatamente antes de enviar el mensaje al usuario. Debido a los tiempos de carga en el almacenamiento en el cloud, puede haber un retraso de unos segundos entre la marca de tiempo sent_at de la copia renderizada y el momento real en que se produce el envío.
¿Puedo crear un nuevo contenedor específico para el archivado de mensajes y seguir usando el contenedor actual para los datos de Currents?
No. Si te interesa dedicated message archiving buckets while keeping a separate Currents bucket, envía comentarios sobre el producto.
¿Los datos archivados se escriben en una carpeta dedicada dentro de un contenedor existente, de forma similar a como se estructuran las exportaciones de datos de Currents?
Los datos se escriben en una sección sent_messages del contenedor. Consulta Cómo funciona para obtener más información.
¿Puedo usar el archivado de mensajes para agrupar archivos en distintos espacios de trabajo?
No. El archivado de mensajes no admite agrupar archivos por espacios de trabajo. En su lugar, puedes determinar a qué espacio de trabajo pertenece el ID de API de la Campaign o del paso en Canvas y, después, agruparlos en función de esa información.