Ir para o conteúdo

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

Guia Configurações de uma mensagem push com as Opções de alerta, mostrando uma chave do dicionário de alertas 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.

Campos para inserir pares de valores-chave personalizados no criador de mensagem push.

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.

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.

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.

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.

Opções de envio de mensagens do FCM na guia Configurações do criador de mensagem push para Android.

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.

Mensagens no app

Adicione pares de chave-valor a qualquer mensagem no app que você criar na Braze.

  1. Em sua campanha ou Canvas, crie ou edite uma mensagem no app.
  2. No criador de mensagem, selecione a guia Configurações.
  3. 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.
  4. 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.

Guia Informações de envio no criador de mensagens de e-mail da Braze.

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.

Adicionar par de chave-valor ao Content Card

New Stuff!