Notification Payload — qué es, estructura JSON y análisis

Qué es un Notification Payload

Notification Payload es un objeto JSON que el servidor envía a APNS (Apple Push Notification Service) para su entrega a un dispositivo iOS. El payload contiene todos los datos que el sistema necesita para mostrar la notificación: título, texto, sonido, badge y metadatos para procesamiento en segundo plano. La estructura del payload está estrictamente regulada por Apple e incluye claves obligatorias para su correcto procesamiento por el sistema.

Función del Payload en la Entrega Push

Cuando el servidor envía una notificación push a través de la API HTTP/2 de APNS, la solicitud contiene encabezados de autorización y un cuerpo JSON — el payload. APNS valida el payload: si el JSON es incorrecto o supera el límite de tamaño, el servidor de Apple devuelve un error 400 Bad Request. Tras la validación, APNS entrega el payload al dispositivo, donde iOS lo analiza y determina cómo manejar la notificación — mostrar un banner, ejecutar una tarea en segundo plano o reproducir un sonido.

Evolución del Formato del Payload

El formato del payload APNS evolucionó desde un payload de texto simple en iOS 2 hasta una estructura JSON multicomponente en las versiones modernas. iOS 10 introdujo soporte para adjuntos multimedia mediante mutable-content, iOS 12 añadió agrupación de notificaciones mediante thread-id, e iOS 15 incorporó supports-live-activities para Live Activities. Hoy en día, un payload puede contener hasta 15 claves diferentes según el comportamiento deseado de la notificación.

Estructura del Payload APNS: Claves Obligatorias y Opcionales

El objeto raíz del payload contiene un diccionario aps y campos personalizados opcionales en el nivel superior. El diccionario aps es el único elemento obligatorio, pero dentro de él pueden aparecer diversas combinaciones de claves según el tipo de notificación: alert, badge, sound, content-available, mutable-content, interruption-level y otras.

La Clave alert: Formato String y Dictionary

La clave alert puede ser una cadena simple (que se convierte en el cuerpo de la notificación) o un diccionario con los campos title, subtitle y body. El formato de diccionario permite establecer el título y subtítulo por separado del texto principal. Para notificaciones localizadas, se usan las claves title-loc-key, title-loc-args, loc-key y loc-args, que hacen referencia a los Localizable.strings de la aplicación. Esto permite enviar un payload sin texto en un idioma específico — la aplicación sustituye la traducción.

Gestión de Interrupciones: interruption-level y relevance-score

A partir de iOS 15, Apple introdujo el mecanismo Focus Mode, que requiere que el desarrollador especifique el nivel de interrupción de la notificación. interruption-level acepta los valores: passive (sin sonido, sin activar la pantalla), active (comportamiento estándar), time-sensitive (atraviesa Focus, requiere autorización especial) y critical (situaciones médicas/de emergencia). La clave relevance-score (0–1) ayuda al sistema Focus a clasificar notificaciones dentro de una misma categoría.

Agrupación de Notificaciones mediante thread-id

La clave thread-id agrupa notificaciones en el Centro de Notificaciones. Todas las notificaciones con el mismo thread-id se muestran como un único grupo que el usuario puede expandir. Esto es especialmente útil para mensajería, donde los mensajes de un mismo contacto se agrupan, o para aplicaciones que envían muchas notificaciones del mismo tipo.

Campos Personalizados y Transferencia de Datos

Los campos personalizados son claves fuera del diccionario aps que el desarrollador añade para transmitir datos adicionales al dispositivo. El servidor los incluye en el objeto JSON raíz del payload, y la aplicación los obtiene a través de userInfo en UNNotificationContent. Los campos personalizados no deben duplicar nombres de claves de aps para evitar conflictos durante el análisis.

Limitaciones de los Datos Personalizados

La limitación principal es que el tamaño total del payload no debe superar los 4096 bytes. Los campos personalizados compiten por este límite con las claves obligatorias de aps, por lo que es importante minimizar el tamaño de los datos transmitidos. Utilice nombres cortos para las claves (por ejemplo, “uid” en lugar de “user-id”), evite estructuras JSON grandes y transmita solo identificadores en lugar de objetos de datos completos.

Seguridad y Validación de Campos Personalizados

Los campos personalizados provienen del servidor y no deben aceptarse sin verificación. Valide siempre los tipos y valores de los campos personalizados al analizarlos: compruebe la existencia de la clave mediante enlace opcional, convierta al tipo esperado con as? String/Int/Dictionary y maneje el caso de valor ausente. Nunca use force unwrap (!) para datos del payload — el servidor podría enviar datos inválidos y la aplicación se bloquearía.

{
    "aps": {
        "alert": {
            "title": "Nuevo mensaje",
            "body": "¡Hola! ¿Cómo estás?"
        },
        "badge": 5,
        "sound": "default",
        "category": "message",
        "thread-id": "chat_4521",
        "mutable-content": 1
    },
    "sender-id": "user_789",
    "chat-id": "chat_4521",
    "message-type": "text",
    "image-url": "https://cdn.example.com/img.jpg"
}

Recomendaciones para Nombrar Campos Personalizados

Utilice un estilo de nomenclatura coherente para los campos personalizados en todos los payloads del proyecto. kebab-case (message-type) o camelCase (messageType) — ambos enfoques son aceptables, pero la coherencia dentro del proyecto es importante. Evite nombres largos: “uid” en lugar de “user-identifier”, “img” en lugar de “profile-image-url”. Cada carácter en un nombre de clave consume un byte del límite de 4096.

Ejemplos de Payload para Diferentes Tipos de Notificación

Diferentes escenarios de notificaciones push requieren diferentes combinaciones de claves en el payload. Veamos varios ejemplos típicos: una notificación de texto simple, una notificación localizada, un Silent Push y una Notificación Enriquecida con adjunto multimedia.

Notificación de Texto Simple

Un payload básico con texto y sonido — la configuración mínima para mostrar una notificación al usuario. Alert como cadena proporciona un mensaje corto, sound default reproduce el sonido del sistema estándar. Badge es opcional y establece el contador en el icono de la aplicación. category y thread-id se añaden para agrupación e interactividad.

{
    "aps": {
        "alert": "Recordatorio: reunión en 15 minutos",
        "badge": 3,
        "sound": "default"
    }
}

Notificación Localizada

Para enviar notificaciones a dispositivos con diferentes idiomas, utilice claves de localización en lugar de texto fijo. title-loc-key hace referencia a una clave en los Localizable.strings de la aplicación, y title-loc-args proporciona argumentos. Esto permite enviar un único payload a todos los dispositivos, y la aplicación muestra el texto en el idioma correspondiente.

{
    "aps": {
        "alert": {
            "title-loc-key": "NEW_MESSAGE_TITLE",
            "title-loc-args": ["Ana"],
            "loc-key": "NEW_MESSAGE_BODY",
            "loc-args": ["¡Hola!"]
        },
        "sound": "message.caf"
    }
}

Silent Push con Sincronización en Segundo Plano

Para sincronización en segundo plano sin mostrar una notificación, use content-available: 1 sin alert. Los campos personalizados especifican el tipo de operación y los datos para procesar. El sistema activa la aplicación en segundo plano, llama a didReceiveRemoteNotification con fetchCompletionHandler, y la aplicación realiza la sincronización.

{
    "aps": {
        "content-available": 1
    },
    "sync-type": "invalidate-cache",
    "timestamp": "2026-07-03T12:00:00Z"
}

Notificación Enriquecida con Imagen

Para mostrar un adjunto multimedia, se necesita mutable-content: 1 para activar la Service Extension, junto con una URL de imagen en un campo personalizado. mutable-content: 1 señala al sistema que debe lanzar UNNotificationServiceExtension, que descarga la imagen de la URL y la añade como UNNotificationAttachment. La clave category especifica una categoría registrada para mostrar botones de acción.

{
    "aps": {
        "alert": {
            "title": "Nuevo producto",
            "body": "Mira la nueva colección"
        },
        "category": "product",
        "mutable-content": 1
    },
    "media-url": "https://cdn.example.com/product.jpg"
}

Procesamiento y Análisis del Payload en la Aplicación

UNNotificationContent.userInfo contiene el diccionario completo del payload recibido tras el procesamiento del sistema. La aplicación accede al payload en el delegado de UNUserNotificationCenter al recibir una notificación (en primer plano), al tocar una notificación, así como en Service Extension y Content Extension. El análisis correcto es esencial para extraer datos personalizados y determinar las siguientes acciones.

Análisis en AppDelegate al Tocar una Notificación

Cuando el usuario toca una notificación, el sistema llama al método didReceive response en UNUserNotificationCenterDelegate. response.notification.request.content.userInfo contiene el payload completo. El desarrollador extrae los campos personalizados, determina el tipo de acción (por ejemplo, abrir un chat, navegar a un producto) y activa la navegación correspondiente en la aplicación.

func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    didReceive response: UNNotificationResponse,
    withCompletionHandler completionHandler: @escaping () -> Void
) {
    let userInfo = response.notification
        .request.content.userInfo

    guard let chatId = userInfo["chat-id"] as? String
    else {
        completionHandler()
        return
    }

    let messageType = userInfo["message-type"]
        as? String ?? "text"

    NavigationRouter.shared.navigate(
        to: .chat(chatId: chatId,
                  messageType: messageType))
    completionHandler()
}

Validación del Payload en Service Extension

La Service Extension recibe el payload antes de que se muestre la notificación y puede modificarlo. La validación del payload es el primer paso en didReceive: compruebe los campos personalizados obligatorios, valide la URL del adjunto y verifique los tipos de datos. Si el payload no es válido, llame al completion handler con el contenido original inmediatamente para no perder tiempo en procesamiento innecesario.

Registro y Supervisión de Payloads

Para depurar notificaciones push en producción, utilice un registro estructurado de payloads. OSLog permite registrar el payload con la categoría “notifications” y nivel debug. En el lado del servidor, supervise las respuestas de APNS: una respuesta exitosa contiene apns-id para coincidir con el payload enviado, mientras que un error 400 indica JSON mal formado o superación del límite de tamaño.