Pares de valores-chave

Esta página aborda como usar pares de valores-chave para enviar cargas extras de dados para dispositivos de usuários. Esse recurso está disponível nos canais de mensagens push, no aplicativo, por e-mail e Content Card.

Use pares de valores-chave para adicionar metadados estruturados às mensagens. Esses payloads de dados extras podem enriquecer as mensagens com informações contextuais adicionais que podem influenciar a forma como uma mensagem é renderizada ou processada.

Como os pares de valores-chave são metadados, esses dados não são necessariamente visíveis para o destinatário, mas podem ser usados por seus sistemas ou processos conectados para personalizar o tratamento de mensagens.

Cada par é composto por:

• Chave: O identificador (Exemplo: utm_source)
• Valor: Os dados associados (Exemplo: newsletter)

Casos de uso

Aqui estão alguns exemplos de casos de uso para adicionar metadados com pares de valores-chave:

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

Notificações push

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

No compositor de mensagens, selecione a guia Settings (Configurações ), selecione Add New Pair (Adicionar novo par) e especifique seus pares de valores-chave.

iOS

O serviço de notificação por push da Apple (APNs) permite definir preferências de alerta e enviar dados personalizados usando pares de valores-chave. Os APNs usam a biblioteca aps, reservada pela Apple, que inclui chaves e valores predeterminados que controlam as propriedades do alerta.

Biblioteca da APS

Biblioteca de propriedades de alerta

O compositor de mensagens do 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 Configurações ao criar uma mensagem push. Selecione Opções de alerta e selecione uma chave de dicionário de alerta para que a chave seja preenchida automaticamente em uma nova entrada de valor-chave.

!

Quando o Braze envia uma notificação push para APNs, o payload será formatado 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 nesses pares são restritos a tipos primitivos: dicionário (objeto), matriz, cadeia de caracteres, número e booleano.

!

Os casos de uso de pares de valores-chave personalizados incluem, entre outros, a manutenção de métricas internas e a definição do contexto da interface do usuário. O Braze permite que você envie pares de valores-chave adicionais junto com uma notificação push a ser usada por meio do seu aplicativo dentro da chave extra. Se preferir usar outra chave, confirme se seu aplicativo pode lidar com essa chave personalizada.

A Apple aconselha os clientes a evitarem incluir informações de clientes ou quaisquer dados confidenciais como dados de carga 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 acionadas por API

O Braze permite que você envie pares de valores-chave de cadeia de caracteres personalizados, conhecidos como extras. Para acessar seus extras em campanhas acionadas por API e campanhas acionadas por API programadas, no painel, defina uma chave como “example_key”, e um valor como "$json:{"foo": 1, "bar": 1}". Isso resultará em uma saída do console do desenvolvedor de "extras": { "test": { "foo": 1, "bar": 1 }

Android

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

Carga útil de dados

Semelhante ao iOS push, 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 a manutenção de métricas internas e a definição do contexto da interface do usuário, mas eles podem ser usados para qualquer finalidade que você escolher.

Campanhas acionadas por API

O Braze permite que você envie pares de valores-chave de cadeia de caracteres personalizados, conhecidos como extras. Para acessar seus extras em campanhas acionadas por API e campanhas acionadas por API programadas, no painel, defina uma chave como “example_key”, e um valor como "$json:{"foo": 1, "bar": 1}". Isso resultará em uma saída do console do desenvolvedor de "extras": { "test": { "foo": 1, "bar": 1 }.

Opções de mensagens FCM

As notificações push do Android podem ser ainda mais personalizadas com opções de mensagens FCM. Isso inclui prioridade de notificação, som, atraso, vida útil e colapsabilidade. Esses valores podem ser especificados na guia Configurações ao criar uma mensagem push. Consulte Configurações avançadas de notificação por push para obter mais instruções sobre como definir essas opções no compositor de mensagens do Braze.

!

Notificações push silenciosas

Uma notificação push silenciosa é uma notificação push sem mensagem de alerta ou som, usada para atualizar a interface ou o conteúdo do seu aplicativo em segundo plano. Essas notificações usam pares de valores-chave para acionar essas ações do aplicativo em segundo plano. As notificações push silenciosas também alimentam nosso rastreamento de desinstalação.

Os profissionais de marketing devem testar se as notificações push silenciosas acionam o comportamento esperado antes de enviá-las aos usuários do aplicativo. Depois de redigir a notificação por push silenciosa para iOS ou Android, certifique-se de que o alvo seja apenas um usuário de teste, filtrando o ID do usuário externo ou o endereço de e-mail.

Após o lançamento da campanha, você deve verificar se não recebeu nenhuma notificação push visível em seu dispositivo de teste.

Mensagens no aplicativo

Para adicionar um par de valores-chave a uma mensagem in-app, selecione a guia Configurações no compositor de mensagens, selecione Adicionar novo par e especifique seus pares de valores-chave.

!

Campanhas acionadas por API

O Braze permite que você envie pares de valores-chave de cadeia de caracteres personalizados, conhecidos como extras. Para acessar seus extras em campanhas acionadas por API e campanhas acionadas por API programadas, no painel, defina uma chave como “example_key”, e um valor como "$json:{"foo": 1, "bar": 1}". Isso resultará em uma saída do console do desenvolvedor de "extras": { "test": { "foo": 1, "bar": 1 }.

E-mails

Tanto o SparkPost quanto o SendGrid suportam 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 que você anexe um número ilimitado de pares de valores-chave de até 10.000 bytes de dados. Esses pares de valores-chave podem ser vistos nas postagens do Webhook de evento da SendGrid.

!Guia Informações de envio do compositor de mensagens de e-mail no Braze.

Cartões de conteúdo

Para adicionar um par chave-valor a um Content Card, vá para a guia Settings (Configurações ) no compositor de mensagens do Braze e selecione Add New Pair (Adicionar novo par).

!Adicionar par chave-valor ao cartão de conteúdo