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 pueden ser utilizados por tus sistemas o procesos conectados para personalizar el manejo de mensajes.

Cada par consiste en:

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

Ejemplos

Estos son 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 enrutamiento interno o categorización
   • Clave: priority
   • Valor: high
3. Desencadenantes de comportamiento: Metadatos utilizados para desencadenar o personalizar comportamientos dentro de la aplicación
   • Clave: deep_link
   • Valor: app://promo-page

Notificaciones push

Se pueden añadir pares clave-valor a las notificaciones push de Android, iOS y web. Puedes utilizar los pares clave-valor para actualizar métricas internas y el contenido de la aplicación, o para personalizar las propiedades de las notificaciones push, como la priorización de 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. Para las notificaciones push de iOS, las claves de alerta reservadas del servicio de notificaciones push de Apple (APN) que añadas a través de Opciones de alerta (como loc-args para argumentos de localización) se formatean con los tipos JSON correctos en la carga útil. Para 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 configurar preferencias de alerta y enviar datos personalizados mediante pares clave-valor. APN utiliza la biblioteca reservada de Apple aps, que incluye claves y valores predeterminados que gobiernan 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.

Estos valores se pueden introducir en la pestaña Configuración al crear un mensaje push. Selecciona Opciones de alerta y selecciona una clave del diccionario de alertas para que 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 un 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 en estos pares están restringidos a tipos primitivos: diccionario (objeto), matriz, cadena, número y booleano.

Los ejemplos de uso de los pares clave-valor personalizados incluyen, entre otros, el mantenimiento de métricas internas y la configuración del contexto para la interfaz de usuario. Braze te permite enviar pares clave-valor adicionales junto con una notificación push para utilizarlos a través de tu aplicación dentro de la clave extras. Si prefieres utilizar otra clave, confirma que tu aplicación puede gestionar esta clave personalizada.

Advertencia

Deberías evitar gestionar una clave o diccionario de nivel superior llamado ab en tu aplicación.

Apple aconseja a los clientes evitar incluir información del cliente o cualquier dato sensible como datos de carga útil personalizados. Además, Apple recomienda que cualquier acción asociada con un mensaje de alerta no elimine datos del dispositivo.

Advertencia

Si utilizas la API del proveedor HTTP/2, cualquier carga útil individual que envíes a APN no puede superar un tamaño de 4096 bytes. La interfaz binaria heredada, que pronto quedará obsoleta, solo admite un tamaño de carga útil 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 Campaigns desencadenadas por API y 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 una salida en la consola para desarrolladores de "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

De forma similar a las notificaciones push de iOS, puedes enviar pares clave-valor personalizados al dispositivo de un usuario.

Algunos ejemplos de uso de los pares clave-valor personalizados incluyen el mantenimiento de métricas internas y la configuración del contexto para la interfaz de usuario, pero se pueden utilizar para cualquier propósito que elijas.

Importante

El backend de tu aplicación debe ser capaz de 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 Campaigns desencadenadas por API y 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 una salida en la consola para desarrolladores de "extras": { "test": { "foo": 1, "bar": 1 }.

Opciones de mensajería FCM

Las notificaciones push de Android se pueden personalizar aún más con las opciones de mensajes FCM. Estas incluyen prioridad de notificación, sonido, retraso, duración y capacidad de colapso. Estos valores se pueden especificar 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 configurar estas opciones en el creador de mensajes de Braze.

Notificaciones push silenciosas

Una notificación push silenciosa es una notificación push que no contiene ningún mensaje de alerta ni sonido, y 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 potencian nuestro seguimiento de desinstalaciones.

Los especialistas en marketing deben probar 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 de iOS o Android, asegúrate de dirigirte únicamente a un usuario de prueba filtrando por ID de usuario externo o dirección de correo electrónico.

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

Nota

La limitación de notificaciones silenciosas de iOS puede causar los siguientes síntomas:

• Métricas de seguimiento de desinstalaciones más bajas de lo esperado para usuarios de iOS
• Entrega inconsistente o retrasada de notificaciones push silenciosas
• Push Stories que no se muestran
• Push Stories que llegan sin sus imágenes, videos o páginas esperadas

Esta es una limitación de la plataforma de Apple, no un problema de Braze. iOS puede retrasar o descartar notificaciones en segundo plano para algunas características de Braze, incluido el seguimiento de desinstalaciones y Push Stories. Para obtener detalles sobre qué limita iOS y cuándo, consulta Limitaciones de iOS.

Mensajes dentro de la aplicación

Añade pares clave-valor a los mensajes dentro de la aplicación que crees con el editor tradicional.

1. En tu Campaign o Canvas, crea o edita un mensaje dentro de la aplicación y selecciona el editor tradicional (no el de arrastrar y soltar).
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, selecciona Añadir nuevo par de nuevo.

Nota

Los pares clave-valor no están disponibles en el editor de arrastrar y soltar para mensajes dentro de la aplicación. Usa el editor tradicional para añadirlos.

Campaigns desencadenadas por API

Braze te permite enviar pares clave-valor de cadena personalizados, conocidos como extras. Para acceder a tus extras en Campaigns desencadenadas por API y 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 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 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 de hasta 10.000 bytes de datos. Estos pares clave-valor se pueden ver en las publicaciones del Event Webhook 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.