Arquivamento de mensagem
O arquivamento de mensagem permite que você salve uma cópia das mensagens enviadas aos usuários para fins de arquivamento ou conformidade em seu bucket S3 da AWS, contêiner de Blob Storage do Azure ou bucket do Google Cloud Storage.
Este artigo aborda como configurar o arquivamento de mensagem, referências de carga útil JSON e perguntas frequentes.
O arquivamento de mensagem está disponível como um recurso complementar. Para começar a usar o arquivamento de mensagem, entre em contato com seu CSM da Braze.
Como funciona
Quando esse recurso está ativado, a Braze grava um arquivo JSON compactado com gzip para cada mensagem enviada a um usuário pelos canais selecionados (e-mail, SMS/MMS, push ou mensagem no app). A Braze grava esses arquivos no seu destino padrão de exportação de dados. Isso inclui todos os tipos de campanha de cada canal, como as campanhas de e-mail de transação enviadas pela API de e-mail de transação.
Esse arquivo conterá os campos definidos em Referências de arquivo e refletirá as mensagens finais, já com os modelos aplicados, enviadas ao usuário. Todos os valores de modelo definidos na sua campanha (por exemplo, {{${first_name}}}) mostrarão o valor final que o usuário recebeu com base nas informações do perfil dele. Assim, você pode manter uma cópia da mensagem enviada para atender a requisitos de conformidade, auditoria ou suporte ao cliente.
Se você configurar credenciais para vários provedores de armazenamento em nuvem, o arquivamento de mensagens exportará apenas para aquele marcado como destino padrão de exportação de dados. Se você não definir um padrão explícito e houver um bucket do AWS S3 conectado, o arquivamento de mensagens fará o upload para esse bucket.
Ativar esse recurso afetará a velocidade de entrega das suas mensagens, pois o upload do arquivo é feito imediatamente antes do envio da mensagem para manter a precisão. A latência causada pelo arquivamento de mensagens depende do provedor de armazenamento em nuvem e do volume e tamanho dos documentos salvos.
O JSON será salvo no seu bucket de armazenamento usando a seguinte estrutura de chave:
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
Um arquivo de exemplo pode ser assim:
sent_messages/email/819baa08d8d7e77e19d4666f5fc6050b/ee965cb2-8934-4b0a-acf1-91c899c2f915/651fd10b282850b39e1169c13975234b.json.gz
O resumo MD5 só pode ser calculado usando um endereço de e-mail, token por push ou número de telefone E.164 conhecido e em letras minúsculas. Um resumo MD5 conhecido não pode ser revertido para obter o endereço de e-mail, token por push ou número de telefone E.164 em letras minúsculas.
Está com dificuldade para encontrar seus tokens por push nos buckets?
A Braze converte seus tokens por push para letras minúsculas antes de gerar o hash. Assim, o token por push Test_Push_Token12345 é convertido para test_push_token12345 no caminho da chave, com o hash 32b802170652af2b5624b695f34de089.
Configuração do arquivamento de mensagens
Esta seção orienta você na configuração do arquivamento de mensagens para seu espaço de trabalho. Antes de continuar, confirme se a sua empresa adquiriu e ativou o arquivamento de mensagens.
Etapa 1: Conecte um bucket de armazenamento em nuvem
Se ainda não tiver feito isso, conecte um bucket de armazenamento em nuvem à Braze. Para ver as etapas, consulte nossa documentação de parceiros sobre Amazon S3, Azure Blob Storage ou Google Cloud Storage.
Você não precisa configurar o Currents para o arquivamento de mensagens, então pode pular esse pré-requisito na documentação de parceiros.
Etapa 2: Selecione os canais para arquivamento de mensagens
A página de configurações Arquivamento de mensagens controla quais canais salvarão uma cópia das mensagens enviadas no seu bucket de armazenamento em nuvem.
Para selecionar os canais:
- Acesse Configurações > Arquivamento de mensagens.
- Selecione seus canais.
- Selecione Salvar alterações.
Se você não encontrar Arquivamento de mensagens em Configurações, confirme se a sua empresa adquiriu e ativou o arquivamento de mensagens.
Ativar o arquivamento de mensagens para mensagens no app converte todas as suas mensagens no app em mensagens no app com modelo. Isso significa que é necessária uma solicitação de rede antes que a Braze possa exibir a mensagem. Para saber mais, consulte O que acontece se eu ativar o arquivamento de mensagens para mensagens no app?.
Lista de permissões de IP
Quando o arquivamento de mensagens faz upload de arquivos para o seu bucket de armazenamento em nuvem, a Braze faz solicitações de rede dos nossos servidores para o seu endpoint do AWS S3, Azure Blob Storage ou Google Cloud Storage. Com a lista de permissões de IP, você pode verificar se essas solicitações vêm da Braze, o que adiciona uma camada de segurança.
A Braze envia os uploads do arquivamento de mensagens pelos mesmos endereços IP usados para o Conteúdo Conectado e o Currents. Para ver a lista completa de IPs por instância, consulte Lista de permissões de IP do Conteúdo Conectado.
Referências de arquivo
Veja abaixo as referências da carga útil JSON entregue ao seu bucket de armazenamento em nuvem sempre que uma mensagem é enviada. Consulte nosso repositório de exemplos de código para ver arquivos de amostra do arquivamento de mensagens.
{
"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
}
O campo extras contém os pares de chave-valor configurados no campo Extras de e-mail ao criar um e-mail no editor de HTML. Os extras de e-mail funcionam com todos os provedores de serviços de e-mail (incluindo SendGrid e Sparkpost) e são incluídos nas mensagens arquivadas, independentemente do provedor usado. Para saber mais sobre como configurar extras de e-mail, consulte Criação de uma campanha de e-mail. Para enviar dados de volta ao Currents, consulte Extras de mensagem.
{
"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
}
Variações na estrutura da carga útil de push
O campo payload de nível superior nos arquivos de notificações por push contém toda a carga útil do provedor, exatamente como foi enviada ao dispositivo. Dentro desse JSON, chaves como aps (para APNs) ou notification e data (para FCM) podem variar bastante, dependendo do tipo de mensagem, da plataforma e da configuração.
O arquivamento de mensagens captura a carga útil da mensagem em si, mas não inclui os metadados de entrega enviados ao FCM ou ao APNs. Os metadados de entrega incluem:
- Tokens de dispositivo
- Configurações de prioridade
- Tempo de vida (TTL)
- IDs de recolhimento
- Cabeçalhos de APNs
- Registros de data e hora de expiração
- Outros campos de configuração de entrega
Esses campos funcionam como instruções de entrega para o provedor de push. Normalmente, eles não são considerados parte do conteúdo da mensagem.
Por exemplo:
- Notificações por push do iOS podem ter estruturas diferentes para notificações Rich (em que
aps.alerté um objeto com campos comotitleebody) e para notificações simples (em queaps.alerté uma string). - Notificações por push do Android (por exemplo, FCM) usam mensagens de dados com chaves personalizadas. A estrutura da carga útil pode incluir campos opcionais diferentes, dependendo da configuração da mensagem, como botões de push, carrosséis ou metadados adicionais.
Além disso, envios de teste feitos pelo dashboard podem gerar estruturas de carga útil diferentes das mensagens de produção.
O formato da carga útil JSON pode variar entre mensagens e mudar com o tempo. Ao analisar cargas úteis de push arquivadas, não presuma uma estrutura fixa nem espere que os mesmos campos estejam sempre presentes. Implemente uma lógica de análise flexível, que lide com diversos 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
}
Variações na estrutura da carga útil de mensagens no app
O campo payload de nível superior nos arquivos de mensagens no app contém a configuração completa da mensagem no app, incluindo o conteúdo (como o texto e o cabeçalho da mensagem) e as configurações de exibição (como tipo de mensagem, alinhamento do texto e cores). Os campos presentes variam conforme o tipo de mensagem no app, como Modal, Slideup, Tela cheia ou HTML personalizado.
O formato da carga útil JSON pode variar entre mensagens e mudar com o tempo. Ao analisar cargas úteis de mensagens no app arquivadas, não presuma uma estrutura fixa nem espere que os mesmos campos estejam sempre presentes. Implemente uma lógica de análise flexível, que lide com diversos formatos de carga útil.
Perguntas frequentes
O que acontece se eu ativar o arquivamento de mensagens para mensagens no app?
Quando você ativa o arquivamento de mensagens para mensagens no app, todas as mensagens no app se tornam mensagens no app modeladas. Isso significa que é necessária uma solicitação de rede antes que a Braze possa exibir a mensagem.
Que modelagem não está incluída na carga útil?
As modificações feitas depois que a mensagem sai da Braze não aparecem no arquivo salvo no seu bucket de armazenamento em nuvem. Isso inclui modificações feitas pelos nossos parceiros de entrega de e-mail, como o encapsulamento de links para rastreamento de cliques e a inserção de pixels de rastreamento.
O que são as mensagens com o valor “unassociated” na jornada da Campaign?
Quando uma mensagem é enviada fora de uma Campaign ou Canvas, o ID da Campaign no nome do arquivo será “unassociated”. Isso acontece quando você envia mensagens de teste pelo dashboard, quando a Braze envia respostas automáticas de SMS/MMS ou quando as mensagens enviadas pela API não especificam um ID de Campaign.
Como encontro mais informações sobre este envio?
Você pode usar o external_id ou o dispatch_id junto com o user_id para fazer referência cruzada entre a mensagem modelada e os nossos dados do Currents. Assim, você encontra mais informações, como o horário de entrega, se o usuário abriu ou clicou na mensagem, entre outras.
Como as novas tentativas são tratadas?
Se o seu bucket de armazenamento em nuvem estiver inacessível, a Braze fará até três novas tentativas com jitter de backoff. As novas tentativas por limite de frequência do AWS S3 são tratadas automaticamente pela Braze.
O que acontece se minhas credenciais forem inválidas?
Se as suas credenciais de armazenamento em nuvem se tornarem inválidas a qualquer momento, a Braze não conseguirá salvar nenhuma mensagem no seu bucket de armazenamento em nuvem, e essas mensagens serão perdidas. Recomendamos configurar suas preferências de notificação para Amazon Web Services, Google Cloud Services ou Azure (Microsoft Cloud Services) para receber alertas sobre qualquer problema com as credenciais.
Por que o registro de data e hora sent_at do meu arquivo de arquivamento é um pouco diferente do registro de data e hora de envio no Currents?
A cópia renderizada é carregada imediatamente antes do envio da mensagem ao usuário. Por causa do tempo de upload para o armazenamento em nuvem, pode haver uma postergação de alguns segundos entre o registro de data e hora sent_at na cópia renderizada e o horário real do envio.
Posso criar um novo bucket específico para o arquivamento de mensagens e manter o bucket atual usado para os dados do Currents?
Não. Se você tem interesse em dedicated message archiving buckets while keeping a separate Currents bucket, envie feedback de produto.
Os dados arquivados são gravados em uma pasta dedicada em um bucket existente, de forma semelhante à estrutura das exportações de dados do Currents?
Os dados são gravados em uma seção sent_messages do bucket. Consulte Como funciona para saber mais.
Posso usar o arquivamento de mensagens para agrupar arquivos em diferentes espaços de trabalho?
Não. O arquivamento de mensagens não oferece suporte ao agrupamento de arquivos por espaço de trabalho. Em vez disso, você pode identificar a qual espaço de trabalho pertence o ID da API da Campaign ou da etapa do Canvas e, então, agrupar os arquivos com base nessa informação.