Pares de chave-valor
Esta página aborda como usar pares de chave-valor para enviar cargas úteis de dados extras para dispositivos de usuários. Esse recurso está disponível nos canais de envio de mensagens push, no app, e-mail e Content Cards.
Use pares de chave-valor para adicionar metadados estruturados às mensagens. Essas cargas úteis de dados extras podem enriquecer as mensagens com informações contextuais adicionais, que podem influenciar como uma mensagem é renderizada ou processada.
Como os pares de chave-valor são metadados, esses dados não são necessariamente visíveis para o destinatário. Mas eles podem ser usados pelos seus sistemas ou processos conectados para personalizar o tratamento das mensagens.
Cada par consiste em:
- Chave: O identificador (Exemplo:
utm_source) - Valor: O dado associado (Exemplo:
newsletter)
Casos de uso
Aqui estão alguns exemplos de casos de uso para adicionar metadados com pares de chave-valor:
- Parâmetros de rastreamento: Anexar parâmetros UTM para fins de análise de dados
- Chave:
utm_campaign - Valor:
spring_sale
- Chave:
- Tags personalizadas: Adicionar tags para roteamento interno ou categorização
- Chave:
priority - Valor:
high
- Chave:
- Gatilhos de comportamento: Metadados usados para disparar ou personalizar comportamentos no app
- Chave:
deep_link - Valor:
app://promo-page
- Chave:
Notificações por push
Você pode adicionar pares de valores-chave a notificações por push para Android, iOS e web. Use esses pares para atualizar métricas internas e o conteúdo do app, ou para personalizar propriedades da notificação por push, como priorização de alertas, localização e sons.
No criador de mensagem, selecione a guia Configurações, clique em Adicionar novo par e especifique seus pares de valores-chave.
Os valores dos pares de valores-chave adicionados no criador de mensagem são enviados como strings. No push para iOS, as chaves de alerta reservadas do serviço de Notificações por Push da Apple (APN) que você adiciona em Opções de alerta (como loc-args para argumentos de localização) recebem os tipos JSON corretos na carga útil. Nas chaves personalizadas, seu app recebe valores de string, a menos que sua integração faça a conversão.
iOS
O serviço de Notificações por Push da Apple (APN) permite definir preferências de alerta e enviar dados personalizados com pares de valores-chave. O APN usa a biblioteca aps, reservada pela Apple. Ela inclui chaves e valores predeterminados que controlam as propriedades do alerta.
Biblioteca APS
| Chave | Tipo de valor | Descrição do valor |
|---|---|---|
| alert | string ou objeto de dicionário | Para entradas de string, exibe um alerta com a string como mensagem e os botões Fechar e Visualizar. Para entradas que não são string, exibe um alerta ou banner de acordo com as propriedades filhas da entrada |
| badge | número | Define o número exibido como emblema no ícone do app |
| sound | string | O nome do arquivo de som tocado como alerta. Ele deve estar no bundle do app ou na pasta Library/Sounds |
| content-available | número | O valor 1 sinaliza ao app que há novas informações disponíveis ao abrir ou retomar a sessão |
Biblioteca de propriedades de alerta
| Chave | Tipo de valor | Descrição do valor |
|---|---|---|
| title | string | Uma string curta que o Apple Watch exibe brevemente como parte da notificação |
| body | string | O conteúdo da notificação por push |
| title-loc-key | string ou nulo | Uma chave que define a string do título para a localização atual a partir do arquivo Localizable.strings |
| title-loc-args | array de strings ou nulo | Valores de string que podem substituir os especificadores de formato de localização do título em title-loc-key |
| action-loc-key | array de string ou nulo | Se presente, a string especificada define a localização dos botões Fechar e Visualizar |
| loc-key | string ou nulo | Uma chave que define a mensagem da notificação para a localização atual a partir do arquivo Localizable.strings |
| loc-args | array de strings | Valores de string que podem substituir os especificadores de formato de localização em loc-key |
| launch-image | strings | O nome de um arquivo de imagem no bundle do app que você quer usar como imagem de abertura quando o usuário tocar no botão de ação ou deslizar a ação |
O criador de mensagem da Braze cria automaticamente as seguintes chaves: alert e suas propriedades, content-available, sound e category.
Você pode inserir esses valores na guia Configurações ao criar uma mensagem push. Selecione Opções de alerta e escolha uma chave do dicionário de alertas. A chave será preenchida automaticamente em uma nova entrada de valor-chave.

Quando a Braze envia uma notificação por push ao APN, a carga útil é formatada como JSON.
Carga útil simples
{
"aps" : { "alert" : "Message received from Spencer" },
}
Carga útil complexa
{
"aps" : {
"alert" : {
"body" : "Hi, welcome to our app!",
"loc-key" : "France",
"loc-args" : ["Bonjour", "bienvenue"],
"action-loc-key" : "Button_Type_1",
"launch-image" : "Paris"
},
"content-available" : 1
},
}
Pares de valores-chave personalizados
Além dos valores da carga útil da biblioteca aps, você pode enviar pares de valores-chave personalizados ao dispositivo do usuário. Os valores desses pares são restritos a tipos primitivos: dicionário (objeto), array, string, número e booleano.

Os casos de uso de pares de valores-chave personalizados incluem, entre outros, o registro de métricas internas e a definição do contexto da interface do usuário. A Braze permite enviar pares de valores-chave adicionais junto com uma notificação por push para uso no seu aplicativo dentro da chave extras. Se preferir usar outra chave, confirme que seu app consegue processar essa chave personalizada.

Evite processar uma chave de nível superior ou um dicionário chamado ab no seu aplicativo.
A Apple recomenda que os clientes não incluam informações de clientes nem dados sensíveis como dados de carga útil personalizada. Além disso, a Apple recomenda que nenhuma ação associada a uma mensagem de alerta exclua dados do dispositivo.

Se você usa a API de provedor HTTP/2, nenhuma carga útil individual enviada ao APN pode ultrapassar 4096 bytes. A interface binária legada, que em breve será descontinuada, só aceita cargas úteis de até 2048 bytes.
Campaigns disparadas por API
A Braze permite enviar pares de valores-chave de string definidos por você, conhecidos como extras. Para acessar seus extras em Campaigns disparadas por API e Campaigns agendadas disparadas por API, defina no dashboard uma chave como “example_key” e um valor como "$json:{"foo": 1, "bar": 1}". Isso resulta na seguinte saída no console de desenvolvedor: "extras": { "test": { "foo": 1, "bar": 1 }
Android
A Braze permite enviar cargas úteis de dados adicionais em notificações por push usando pares de valores-chave.
Carga útil de dados
Assim como no push para iOS, você pode enviar pares de valores-chave personalizados ao dispositivo do usuário.
Alguns casos de uso de pares de valores-chave personalizados incluem o registro de métricas internas e a definição do contexto da interface do usuário, mas você pode usá-los para a finalidade que quiser.

O backend do seu app precisa conseguir processar pares de valores-chave personalizados para que a carga útil de dados funcione corretamente.
Campaigns disparadas por API
A Braze permite enviar pares de valores-chave de string definidos por você, conhecidos como extras. Para acessar seus extras em Campaigns disparadas por API e Campaigns agendadas disparadas por API, defina no dashboard uma chave como “example_key” e um valor como "$json:{"foo": 1, "bar": 1}". Isso resulta na seguinte saída no console de desenvolvedor: "extras": { "test": { "foo": 1, "bar": 1 }.
Opções de envio de mensagens do FCM
Você pode personalizar ainda mais as notificações por push para Android com as opções de mensagem do FCM. Elas incluem prioridade da notificação, som, postergação, tempo de vida e agrupamento. Você pode especificar esses valores na guia Configurações ao criar uma mensagem push. Consulte Configurações avançadas de notificação por push para saber como definir essas opções no criador de mensagem da Braze.

Notificações por push silenciosas
Uma notificação por push silenciosa não contém mensagem de alerta nem som. Ela serve para atualizar a interface ou o conteúdo do seu app em segundo plano. Essas notificações usam pares de valores-chave para disparar essas ações do app em segundo plano. As notificações por push silenciosas também viabilizam nosso Uninstall Tracking.
Os profissionais de marketing devem testar se as notificações por push silenciosas disparam o comportamento esperado antes de enviá-las aos usuários do app. Depois de criar sua notificação por push silenciosa para iOS ou Android, direcione-a somente a um usuário teste filtrando por ID de usuário externo ou endereço de e-mail.
Após o lançamento da Campaign, verifique se nenhuma notificação por push visível chegou ao seu dispositivo de teste.

A restrição de notificações silenciosas do iOS pode causar os seguintes sintomas:
- Métricas de Uninstall Tracking abaixo do esperado para usuários de iOS
- Entrega inconsistente ou atrasada de notificações por push silenciosas
- Push Stories que não são exibidas
- Push Stories que chegam sem as imagens, os vídeos ou as páginas esperados
Essa é uma limitação da plataforma da Apple, e não um problema da Braze. O iOS pode atrasar ou descartar notificações em segundo plano de alguns recursos da Braze, incluindo Uninstall Tracking e Push Stories. Para saber o que o iOS restringe e quando, consulte Limitações do iOS.
Mensagens no app
Adicione pares de chave-valor a qualquer mensagem no app que você criar na Braze.
- Em sua campanha ou Canvas, crie ou edite uma mensagem no app.
- No criador de mensagem, selecione a guia Configurações.
- Selecione Adicionar novo par:
- Editor tradicional: Em Pares de chave-valor, selecione Adicionar novo par.
- Editor de arrastar e soltar: Selecione a guia Pares de chave-valor e depois selecione Adicionar novo par.
- Insira uma chave e um valor para cada par. Para adicionar outro par, selecione Adicionar novo par novamente.
Campanhas disparadas por API
A Braze permite que você envie pares de chave-valor de string personalizados, conhecidos como extras. Para acessar seus extras em campanhas disparadas por API e campanhas agendadas disparadas por API, defina no dashboard uma chave como “example_key” e um valor como "$json:{"foo": 1, "bar": 1}". Isso vai gerar a seguinte saída no console de desenvolvedor: "extras": { "test": { "foo": 1, "bar": 1 }.
E-mails
Tanto a SparkPost quanto o SendGrid oferecem suporte a pares de valores-chave em e-mails. Se você usa o SendGrid, os pares de valores-chave serão enviados como argumentos exclusivos. O SendGrid permite anexar um número ilimitado de pares de valores-chave, até 10.000 bytes de dados. Esses pares de valores-chave aparecem nas publicações do Event Webhook do SendGrid.

E-mails com bounce não entregarão pares de valores-chave para a SparkPost nem para o SendGrid.

Content Cards
Para adicionar um par de chave-valor a um Content Card, acesse a guia Settings no criador de mensagens da Braze e selecione Add New Pair.


As variantes de controle não suportam pares de chave-valor. Se você precisa capturar análise de dados para grupos de controle em testes A/B, crie uma variante de mensagem com um par de chave-valor como control=true e oculte-a no código do seu app enquanto registra impressões.