Pares clave-valor

Esta página cubre cómo usar pares clave-valor para enviar cargas útiles de datos adicionales a los dispositivos de los usuarios. Esta característica está disponible en los canales de mensajería push, dentro de la aplicación, correo electrónico y Content Cards.

Usa pares clave-valor para agregar metadatos estructurados a los mensajes. Estas cargas útiles de datos adicionales pueden enriquecer los mensajes con información contextual adicional que puede influir en cómo se renderiza o procesa un mensaje.

Dado que los pares clave-valor son metadatos, estos datos no son necesariamente visibles para el destinatario, pero tus sistemas o procesos conectados pueden usarlos para personalizar el manejo de los mensajes.

Cada par consiste en:

• Clave: El identificador (Ejemplo: utm_source)
• Valor: Los datos asociados (Ejemplo: newsletter)

Ejemplos

Aquí tienes algunos ejemplos de uso para añadir metadatos con pares clave-valor:

1. Parámetros de seguimiento: Adjuntar parámetros UTM con fines de análisis
   • Clave: utm_campaign
   • Valor: spring_sale
2. Etiquetas personalizadas: Añadir etiquetas para el enrutamiento interno o la categorización
   • Clave: priority
   • Valor: high
3. Desencadenantes de comportamiento: Metadatos que se utilizan para desencadenar o personalizar comportamientos dentro de la aplicación
   • Clave: deep_link
   • Valor: app://promo-page

Notificaciones push

Puedes añadir pares clave-valor a las notificaciones push de Android, iOS y web. Puedes usar pares clave-valor para actualizar métricas internas y contenido de la aplicación, o para personalizar propiedades de las notificaciones push, como la prioridad de las alertas, la localización y los sonidos.

En el creador de mensajes, selecciona la pestaña Configuración, selecciona Añadir nuevo par y especifica tus pares clave-valor.

Cuando añades pares clave-valor en el creador de mensajes, los valores se envían como cadenas. En las notificaciones push de iOS, las claves de alerta reservadas del servicio de notificaciones push de Apple (APN) que añades mediante Opciones de alerta (como loc-args para los argumentos de localización) se formatean con los tipos JSON correctos en la carga útil. En el caso de las claves personalizadas, tu aplicación recibe valores de cadena, a menos que los analices en tu integración.

iOS

El servicio de notificaciones push de Apple (APN) permite establecer preferencias de alerta y enviar datos personalizados mediante pares clave-valor. APN utiliza la biblioteca aps reservada por Apple, que incluye claves y valores predeterminados que rigen las propiedades de las alertas.

Biblioteca APS

Biblioteca de propiedades de alerta

El creador de mensajes de Braze gestiona automáticamente la creación de las siguientes claves: alert y sus propiedades, content-available, sound y category.

Puedes introducir estos valores en la pestaña Configuración al crear un mensaje push. Selecciona Opciones de alerta y elige una clave del diccionario de alertas para que la clave se rellene automáticamente en una nueva entrada de par clave-valor.

Cuando Braze envía una notificación push a APN, la carga útil se formatea como JSON.

Carga útil simple

1
2
3

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

Carga útil compleja

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 clave-valor personalizados

Además de los valores de carga útil de la biblioteca aps, puedes enviar pares clave-valor personalizados al dispositivo de un usuario. Los valores de estos pares se limitan a tipos primitivos: diccionario (objeto), matriz, cadena, número y booleano.

Algunos casos de uso de los pares clave-valor personalizados son, entre otros, el registro de métricas internas y el establecimiento del contexto de la interfaz de usuario. Braze te permite enviar pares clave-valor adicionales junto con una notificación push para que tu aplicación los utilice dentro de la clave extras. Si prefieres usar otra clave, confirma que tu aplicación puede gestionar esa clave personalizada.

Advertencia

Debes evitar gestionar en tu aplicación una clave de nivel superior o un diccionario llamado ab.

Apple aconseja a los clientes que no incluyan información de clientes ni datos confidenciales como datos de carga útil personalizados. Además, Apple recomienda que ninguna acción asociada a un mensaje de alerta elimine datos de un dispositivo.

Advertencia

Si utilizas la API de proveedor HTTP/2, ninguna carga útil individual que envíes a APN puede superar los 4096 bytes. La interfaz binaria heredada, que pronto quedará obsoleta, solo admite cargas útiles de 2048 bytes.

Campaigns desencadenadas por API

Braze te permite enviar pares clave-valor de cadena definidos de forma personalizada, conocidos como extras. Para acceder a tus extras en las Campaigns desencadenadas por API y en las Campaigns programadas desencadenadas por API, en el panel establece una clave como “example_key” y un valor como "$json:{"foo": 1, "bar": 1}". Esto dará como resultado la siguiente salida en la consola para desarrolladores: "extras": { "test": { "foo": 1, "bar": 1 }

Android

Braze te permite enviar cargas útiles de datos adicionales en las notificaciones push mediante pares clave-valor.

Carga útil de datos

Al igual que con las notificaciones push de iOS, puedes enviar pares clave-valor personalizados al dispositivo de un usuario.

Algunos casos de uso de los pares clave-valor personalizados son el registro de métricas internas y el establecimiento del contexto de la interfaz de usuario, pero puedes usarlos para el fin que quieras.

Importante

El backend de tu aplicación debe poder procesar pares clave-valor personalizados para que la carga útil de datos funcione correctamente.

Campaigns desencadenadas por API

Braze te permite enviar pares clave-valor de cadena definidos de forma personalizada, conocidos como extras. Para acceder a tus extras en las Campaigns desencadenadas por API y en las Campaigns programadas desencadenadas por API, en el panel establece una clave como “example_key” y un valor como "$json:{"foo": 1, "bar": 1}". Esto dará como resultado la siguiente salida en la consola para desarrolladores: "extras": { "test": { "foo": 1, "bar": 1 }.

Opciones de mensajería de FCM

Las notificaciones push de Android se pueden personalizar aún más con las opciones de mensajes de FCM. Entre ellas se incluyen la prioridad de la notificación, el sonido, el retraso, la duración y la posibilidad de contraer. Puedes especificar estos valores en la pestaña Configuración al crear un mensaje push. Consulta Configuración avanzada de notificaciones push para obtener más instrucciones sobre cómo establecer estas opciones en el creador de mensajes de Braze.

Notificaciones push silenciosas

Una notificación push silenciosa es una notificación push sin mensaje de alerta ni sonido que se utiliza para actualizar la interfaz o el contenido de tu aplicación en segundo plano. Estas notificaciones utilizan pares clave-valor para desencadenar estas acciones de la aplicación en segundo plano. Las notificaciones push silenciosas también hacen posible nuestro Uninstall Tracking.

Los especialistas en marketing deben comprobar que las notificaciones push silenciosas desencadenan el comportamiento esperado antes de enviarlas a los usuarios de su aplicación. Después de crear tu notificación push silenciosa para iOS o Android, asegúrate de dirigirte solo a un usuario de prueba filtrando por ID de usuario externo o por dirección de correo electrónico.

Al lanzar la Campaign, comprueba que no has recibido ninguna notificación push visible en tu dispositivo de prueba.

Nota

Las restricciones de iOS sobre las notificaciones silenciosas pueden provocar los siguientes síntomas:

• Métricas de Uninstall Tracking más bajas de lo esperado para los usuarios de iOS
• Entrega irregular o retrasada de las notificaciones push silenciosas
• Push Stories que no se muestran
• Push Stories que llegan sin las imágenes, el video o las páginas esperados

Se trata de una limitación de la plataforma de Apple, no de un problema de Braze. iOS puede retrasar o descartar las notificaciones en segundo plano de algunas características de Braze, como Uninstall Tracking y Push Stories. Para obtener más información sobre qué restringe iOS y cuándo, consulta Limitaciones de iOS.

Mensajes dentro de la aplicación

Añade pares clave-valor a cualquier mensaje dentro de la aplicación que crees en el creador.

1. En tu Campaign o Canvas, crea o edita un mensaje dentro de la aplicación.
2. En el creador de mensajes, selecciona la pestaña Configuración.
3. En Pares clave-valor, selecciona Añadir nuevo par.
4. Introduce una clave y un valor para cada par. Para añadir otro par, vuelve a seleccionar Añadir nuevo par.

Campañas desencadenadas por API

Braze te permite enviar pares clave-valor de cadena definidos de forma personalizada, conocidos como extras. Para acceder a tus extras en las campañas desencadenadas por API y en las campañas desencadenadas por API programadas, en el panel establece una clave como “example_key” y un valor como "$json:{"foo": 1, "bar": 1}". Esto dará como resultado una salida en la consola para desarrolladores de "extras": { "test": { "foo": 1, "bar": 1 }.

Correos electrónicos

Tanto SparkPost como SendGrid admiten pares clave-valor en los correos electrónicos. Si utilizas SendGrid, los pares clave-valor se enviarán como argumentos únicos. SendGrid te permite adjuntar un número ilimitado de pares clave-valor hasta 10 000 bytes de datos. Estos pares clave-valor pueden verse en las publicaciones del webhook de eventos de SendGrid.

Nota

Los correos electrónicos rebotados no entregarán pares clave-valor a SparkPost ni a SendGrid.

Content Cards

Para agregar un par clave-valor a una Content Card, ve a la pestaña Settings en el creador de mensajes de Braze y selecciona Add New Pair.

Nota

Las variantes de control no admiten pares clave-valor. Si necesitas capturar análisis para grupos de control en pruebas A/B, crea una variante de mensaje con un par clave-valor como control=true y ocúltala en el código de tu aplicación mientras registras impresiones.