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:

1. Parâmetros de rastreamento: Anexar parâmetros UTM para fins de análise de dados
   • Chave: utm_campaign
   • Valor: spring_sale
2. Tags personalizadas: Adicionar tags para roteamento interno ou categorização
   • Chave: priority
   • Valor: high
3. Gatilhos de comportamento: Metadados usados para disparar ou personalizar comportamentos no app
   • Chave: deep_link
   • Valor: app://promo-page

Notificações por push

Você pode adicionar pares de valores-chave às notificações por push para Android, iOS e web. Use esses pares para atualizar métricas internas e conteúdo do app, ou para personalizar propriedades das notificações 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.

Quando você adiciona pares de valores-chave no criador de mensagem, os valores 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) são formatadas com os tipos JSON corretos na carga útil. Para chaves personalizadas, seu app recebe valores de string, a menos que você faça o parsing deles na sua integração.

iOS

O serviço de Notificações por Push da Apple (APN) permite definir preferências de alerta e enviar dados personalizados usando pares de valores-chave. O APN usa a biblioteca aps, reservada pela Apple, que inclui chaves e valores predeterminados que controlam as propriedades do alerta.

Biblioteca APS

Biblioteca de propriedades de alerta

O criador de mensagem da Braze cuida automaticamente da criação das 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 para que ela seja preenchida automaticamente em uma nova entrada de par de valores-chave.

Quando a Braze envia uma notificação por push ao APN, a carga útil é formatada como JSON.

Carga útil simples

1
2
3

{
    "aps" : { "alert" : "Message received from Spencer" },
}

Carga útil complexa

1
2
3
4
5
6
7
8
9
10
11
12

{
    "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 de carga útil da biblioteca aps, você pode enviar pares de valores-chave personalizados para o dispositivo de um 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 lidar com essa chave personalizada.

Aviso

Evite lidar com uma chave ou um dicionário de nível superior 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 de um dispositivo.

Aviso

Se você usa a API de provedor HTTP/2, cada carga útil enviada ao APN não pode ultrapassar 4096 bytes. A interface binária legada, que será descontinuada em breve, só aceita cargas úteis de até 2048 bytes.

Campaigns acionadas por API

A Braze permite enviar pares de valores-chave de string definidos de forma personalizada, conhecidos como extras. Para acessar seus extras em Campaigns acionadas por API e Campaigns agendadas acionadas por API, defina no dashboard uma chave como “example_key” e um valor como "$json:{"foo": 1, "bar": 1}". O resultado no console de desenvolvedor será "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 para o dispositivo de um 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.

Importante

O backend do seu app precisa conseguir processar pares de valores-chave personalizados para que a carga útil de dados funcione corretamente.

Campaigns acionadas por API

A Braze permite enviar pares de valores-chave de string definidos de forma personalizada, conhecidos como extras. Para acessar seus extras em Campaigns acionadas por API e Campaigns agendadas acionadas por API, defina no dashboard uma chave como “example_key” e um valor como "$json:{"foo": 1, "bar": 1}". O resultado no console de desenvolvedor será "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 de notificação, som, postergação, tempo de vida e capacidade de recolhimento. 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 ver mais instruções sobre como definir essas opções no criador de mensagem da Braze.

Notificações por push silenciosas

Uma notificação por push silenciosa é uma notificação por push sem mensagem de alerta nem som, usada para atualizar a interface ou o conteúdo do seu app em segundo plano. Essas notificações usam pares de valores-chave para disparar ações do app em segundo plano. As notificações por push silenciosas também são a base do 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 apenas para um usuário teste, filtrando por ID de usuário externo ou endereço de e-mail.

Ao lançar a Campaign, verifique se você não recebeu nenhuma notificação por push visível no seu dispositivo de teste.

Nota

O controle 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 controla e quando, consulte Limitações do iOS.

Mensagens no app

Adicione pares de valores-chave a qualquer mensagem no app que você criar no criador.

1. Na sua Campaign ou Canvas, crie ou edite uma mensagem no app.
2. No criador de mensagem, selecione a guia Configurações.
3. Em Pares de valores-chave, selecione Adicionar novo par.
4. Insira uma chave e um valor para cada par. Para adicionar outro par, selecione Adicionar novo par novamente.

Campaigns acionadas por API

A Braze permite que você envie pares de valores-chave de string personalizados, conhecidos como extras. Para acessar seus extras em Campaigns acionadas por API e Campaigns agendadas acionadas por API, defina no dashboard uma chave como “example_key” e um valor como "$json:{"foo": 1, "bar": 1}". Isso vai gerar no console de desenvolvedor a saída "extras": { "test": { "foo": 1, "bar": 1 }.

E-mails

O SparkPost e o SendGrid são compatíveis com pares de valores-chave em e-mails. Se você usar 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, com até 10.000 bytes de dados. Esses pares de valores-chave aparecem nas publicações do Event Webhook do SendGrid.

Nota

E-mails com bounce não entregarão pares de valores-chave ao SparkPost ou ao 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.

Nota

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.