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 Cartões de conteúdo.

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 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

Pares de chave-valor podem ser adicionados a notificações por push para Android, iOS e web. Você pode usar pares de chave-valor para atualizar métricas internas e conteúdo do app ou personalizar propriedades de notificações por push, como priorização de alertas, localização e sons.

No criador de mensagens, selecione a guia Settings, selecione Add New Pair e especifique seus pares de chave-valor.

iOS

O serviço de Notificações por Push da Apple (APNs) suporta a definição de preferências de alerta e o envio de dados personalizados usando pares de chave-valor. O APNs utiliza a biblioteca reservada da Apple aps, que inclui chaves e valores predeterminados que governam as propriedades de alerta.

Biblioteca APS

Biblioteca de propriedades de alerta

O criador de mensagens da Braze lida automaticamente com a criação das seguintes chaves: alert e suas propriedades, content-available, sound e category.

Esses valores podem ser inseridos na guia Settings ao criar uma mensagem push. Selecione Alert Options e selecione uma chave de dicionário de alerta para que a chave seja automaticamente preenchida em uma nova entrada de chave-valor.

Quando a Braze envia uma notificação por push para o APNs, a carga útil será 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 chave-valor personalizados

Além dos valores de carga útil da biblioteca aps, você pode enviar pares de chave-valor personalizados para o dispositivo de um usuário. Os valores nesses pares são restritos a tipos primitivos: dicionário (objeto), array, string, número e booleano.

Os casos de uso para pares de chave-valor personalizados incluem, entre outros, manutenção de métricas internas e definição do contexto para a interface do usuário. A Braze permite que você envie pares de chave-valor adicionais junto com uma notificação por push para serem usados pelo seu aplicativo por meio da chave extras. Se você preferir usar outra chave, confirme que seu app pode lidar com essa chave personalizada.

A Apple aconselha os clientes a evitar incluir informações do cliente ou quaisquer dados sensíveis como dados de carga útil personalizada. Além disso, a Apple recomenda que qualquer ação associada a uma mensagem de alerta não exclua dados em um dispositivo.

Campanhas disparadas por API

A Braze permite que você envie pares de chave-valor de string definidos pelo usuário, conhecidos como extras. Para acessar seus extras em campanhas disparadas por API e campanhas agendadas disparadas por API, no dashboard defina uma chave como “example_key” e um valor como "$json:{"foo": 1, "bar": 1}". Isso resultará em uma saída do console de desenvolvedor de "extras": { "test": { "foo": 1, "bar": 1 }.

Android

A Braze permite que você envie cargas úteis de dados adicionais em notificações por push usando pares de chave-valor.

Carga útil de dados

Semelhante ao push para iOS, você pode enviar pares de chave-valor personalizados para o dispositivo de um usuário.

Alguns casos de uso para pares de chave-valor personalizados incluem manutenção de métricas internas e definição do contexto para a interface do usuário, mas eles podem ser usados para qualquer finalidade que você escolher.

Campanhas disparadas por API

A Braze permite que você envie pares de chave-valor de string definidos pelo usuário, conhecidos como extras. Para acessar seus extras em campanhas disparadas por API e campanhas agendadas disparadas por API, no dashboard defina uma chave como “example_key” e um valor como "$json:{"foo": 1, "bar": 1}". Isso resultará em uma saída do console de desenvolvedor de "extras": { "test": { "foo": 1, "bar": 1 }.

Opções de mensagens FCM

As notificações por push para Android podem ser ainda mais personalizadas com opções de mensagens FCM. Essas incluem prioridade de notificação, som, postergação, tempo de vida e capacidade de agrupamento. Esses valores podem ser especificados na guia Settings ao criar uma mensagem push. Consulte Configurações avançadas de notificações por push para mais instruções sobre como definir essas opções no criador de mensagens da Braze.

Notificações por push silenciosas

Uma notificação por push silenciosa é uma notificação por push que não contém mensagem de alerta ou som, usada para atualizar a interface ou o conteúdo do seu app em segundo plano. Essas notificações utilizam pares de chave-valor para disparar essas ações do app em segundo plano. As notificações por push silenciosas também alimentam nosso rastreamento de desinstalação.

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 redigir sua notificação por push silenciosa para iOS ou Android, certifique-se de direcionar apenas um usuário teste filtrando por ID de usuário externo ou endereço de e-mail.

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

Mensagens no app

Você pode adicionar um par de chave-valor a uma mensagem no app no editor tradicional selecionando a guia Settings, selecionando Add New Pair e especificando seus pares de chave-valor.

Campanhas disparadas por API

A Braze permite que você envie pares de chave-valor de string definidos pelo usuário, conhecidos como extras. Para acessar seus extras em campanhas disparadas por API e campanhas agendadas disparadas por API, no dashboard defina uma chave como “example_key” e um valor como "$json:{"foo": 1, "bar": 1}". Isso resultará em uma saída do console de desenvolvedor de "extras": { "test": { "foo": 1, "bar": 1 }.

E-mails

Tanto o SparkPost quanto o SendGrid suportam pares de chave-valor em e-mails. Se você usa o SendGrid, os pares de chave-valor serão enviados como argumentos únicos. O SendGrid permite que você anexe um número ilimitado de pares de chave-valor com até 10.000 bytes de dados. Esses pares de chave-valor podem ser vistos em posts do Event Webhook do SendGrid.

Cartões de conteúdo

Para adicionar um par de chave-valor a um cartão de conteúdo, acesse a guia Settings no criador de mensagens da Braze e selecione Add New Pair.