Notificaciones push en iOS: configuración de APNs, payloads enriquecidos y el momento de pedir permiso

Respuesta directa

Configurar bien las notificaciones push en iOS se reduce a tres partes: un token de autenticación de proveedor que confirma tu servidor ante Apple Push Notification service (APNs), un payload JSON construido a partir del diccionario aps y mantenido bajo el límite de tamaño de la plataforma, y una solicitud de permiso que llega como respuesta a una acción real del usuario, no al abrir la app por primera vez. Si resuelves bien esas tres partes, el contenido enriquecido, las acciones interactivas y la entrega confiable vienen por añadidura. Esta guía recorre cada parte en el orden en que realmente las vas a construir: autenticación y configuración de la conexión, el flujo paso a paso desde el registro hasta una notificación enriquecida, y los errores que más a menudo hacen que una función funcione en TestFlight y quede en silencio en producción.

Antes de empezar

APNs acepta dos formas de autenticar un servidor proveedor: un token de autenticación de proveedor basado en JWT o un certificado de proveedor. El enfoque con token es el que Apple documenta como práctica actual. Cada token es un JSON Web Token con un encabezado que especifica el algoritmo de firma, que debe ser ES256, más un identificador de clave (kid), una clave de 10 caracteres obtenida de tu cuenta de Apple Developer. El payload de claims lleva iss, tu Team ID de 10 caracteres, y iat, la marca de tiempo Unix en que se emitió el token.

Los tokens firmados con un algoritmo distinto a ES256 regresan como un error 403 InvalidProviderToken. Y la ventana de validez del token está limitada a una hora: APNs rechaza un token cuyo iat cae fuera de los últimos 60 minutos con 403 ExpiredProviderToken. Así que el patrón práctico es generar un token, reutilizarlo en cada push que envíes durante esa hora, y rotarlo antes de que expire en lugar de generar un token nuevo por cada solicitud. Si una clave de firma llega a verse comprometida, revócala en la cuenta de Developer, cierra toda conexión abierta con APNs, y reconecta usando un token firmado con la clave de reemplazo.

Los device tokens manejan la otra mitad de dirigir una notificación. Son identificadores hexadecimales que tu app recibe después de que el usuario concede el permiso, específicos tanto al entorno (desarrollo frente a producción) como al topic, que APNs interpreta como el bundle ID de tu app. Enviar al entorno equivocado, o a un token que ya fue invalidado, hace que APNs devuelva 400 BadDeviceToken o 410 Unregistered, ambos fallos silenciosos si no estás revisando las respuestas. Las conexiones deben permanecer abiertas a lo largo de muchas notificaciones; APNs exige TLS 1.2 o superior y trata la apertura y cierre rápido de conexiones como trataría un patrón de denegación de servicio, es decir, no lo premia. La disciplina aquí es la misma que aplicamos al lanzar apps SwiftUI con confianza: verificar la plomería poco vistosa antes de construir la función encima.

Paso a paso: de la configuración de APNs a una notificación enriquecida

Registra la app para notificaciones remotas y pide el permiso en el momento correcto. Llama a UNUserNotificationCenter.current().requestAuthorization(options:), y en el completion handler, llama a UIApplication.shared.registerForRemoteNotifications() solo si granted es true. Este mismo canal de registro alimenta las Live Activities impulsadas por push, así que resolver bien el flujo de solicitud una vez se paga sola en cada función basada en notificaciones que agregues después.

Construye el payload aps. La clave alert puede ser un string simple o un diccionario con title, body, y claves de localización (title-loc-key, loc-key, loc-args) si estás localizando desde el servidor o desde el bundle de la app. Agrega badge para el contador del icono, sound para un archivo de audio personalizado, category para referenciar un conjunto de acciones registrado, y content-available: 1 para una notificación silenciosa de actualización en segundo plano. Apple recomienda limitarlas a unas pocas por hora, ya que el sistema las trata como de baja prioridad y puede limitarlas.

Respeta el límite de tamaño. Un payload de notificación remota estándar llega hasta 4KB; los payloads VoIP llegan a 5KB. Elimina espacios en blanco y saltos de línea para quedarte bajo el límite, y nunca pongas datos sensibles directamente en el payload. La guía de Apple es clara: trata la notificación como una señal de que existe contenido, no como un contenedor del contenido mismo, de la misma forma en que una app de correo debería notificar que llegó un mensaje sin poner el cuerpo del mensaje en el push.

Envía con los encabezados correctos. authorization: bearer <JWT> lleva tu token de proveedor, apns-topic lleva el bundle ID (requerido al autenticar con token), y apns-priority controla el comportamiento de entrega: 10 para entrega inmediata que debe activar una alerta, sonido o badge; 5 para entrega eficiente en energía que el sistema puede agrupar, limitar, o en algunos casos no entregar. apns-collapse-id, limitado a 64 bytes, te permite agrupar o reemplazar notificaciones duplicadas en lugar de apilarlas.

Agrega contenido enriquecido con una Notification Service Extension. El payload en sí se mantiene pequeño, así que imágenes, video y audio llegan por referencia, no por valor. Una Notification Service Extension intercepta la notificación antes de que se muestre, descarga el contenido al que apunta el payload, y lo adjunta al contenido de la notificación. Una Notification Content Extension va más allá, reemplazando el diseño predeterminado del sistema con una interfaz completamente personalizada. Ambas corren en la ventana de aproximadamente 30 segundos que iOS le da a las extensiones antes de volver a la notificación sin modificar.

Registra categorías y acciones. UNNotificationCategory combinado con uno o más objetos UNNotificationAction permite que un usuario responda, descarte, o actúe directamente desde la notificación sin abrir la app. Vale el pequeño esfuerzo adicional de registro para cualquier tipo de notificación con la que la gente interactúa con frecuencia.

Errores comunes que rompen las notificaciones push

El error más común, y el más evitable, es pedir el permiso de notificaciones al abrir la app por primera vez, antes de que el usuario tenga algún contexto sobre por qué tu app quiere enviarle algo. La propia guía de Apple es explícita en esto: el aviso del sistema solo aparece una vez por instalación, la respuesta del usuario queda guardada, y cada llamada posterior a requestAuthorization simplemente devuelve esa respuesta guardada en silencio. No existe un reenvío programático del aviso. Si pides el permiso demasiado pronto y te lo niegan, la única forma de recuperarlo es enviar al usuario a Configuración manualmente. Programa la solicitud para un momento en que el usuario ya haya mostrado interés: al terminar el onboarding, al activar una función que depende de alertas, al tocar un control de "notificarme".

El segundo fallo más común es un desajuste de device token: enviar un token de producción al endpoint de desarrollo o viceversa, o enviar a un bundle ID que no coincide con el topic del token. Ambos regresan como 400 BadDeviceToken; un token que el sistema ya invalidó regresa como 410 Unregistered. Ninguno de los dos fallos es visible para el usuario, que es exactamente por qué revisar los códigos de respuesta de APNs en tu servidor proveedor importa más de lo que parece.

Tercero, algunos equipos generan un nuevo token de proveedor en cada push en lugar de reutilizar un JWT durante toda su hora de validez. Eso agrega sobrecarga de firma sin necesidad y, en volumen, carga innecesaria sobre la conexión. Cuarto, algunos servidores abren y cierran una conexión por cada notificación en lugar de mantener una abierta, algo que APNs trata como abusivo en vez de eficiente.

Finalmente, revisa tu código de delegados y extensiones contra tu modelo de concurrencia. Si estás en medio de la migración a Swift 6 strict concurrency, los callbacks del delegado de notificaciones y los puntos de entrada de las extensiones de servicio son exactamente el tipo de código provisto por el sistema, sin aislamiento de actor, que activa las nuevas verificaciones de aislamiento del compilador, por lo general como un error de compilación en lugar de un error en tiempo de ejecución. Ese es el mejor de los dos resultados.

Kallos Labs integra esta secuencia de autenticación, payload y permiso en la revisión de preparación para producción que ejecutamos antes de cada envío a la App Store en el trabajo de desarrollo iOS que entregamos a clientes, porque una función push que pasa el control de calidad en el teléfono de un desarrollador con entitlements de depuración y falla en silencio en producción es una de las regresiones más difíciles de detectar después del hecho.

Preguntas frecuentes

¿Cuándo debe una app de iOS pedir el permiso de notificaciones?

Como respuesta a una acción específica del usuario que explique por qué las notificaciones ayudan, como terminar el onboarding o activar una función que depende de alertas, no al abrir la app por primera vez antes de que el usuario tenga contexto alguno.

¿Cuál es el tamaño máximo de un payload de push de APNs?

4KB para una notificación remota estándar y 5KB para VoIP; cualquier cosa más grande se rechaza con un error PayloadTooLarge, así que el contenido enriquecido debe obtenerse después de la entrega, no incrustarse en el payload.

¿Cuánto tiempo es válido un token de autenticación de proveedor de APNs?

Una hora. El mismo JWT debe reutilizarse en cada solicitud durante esa ventana y rotarse antes de que expire en lugar de generarse por cada push.

¿Cómo se agregan imágenes o video a una notificación push de iOS?

Usando una Notification Service Extension que intercepta la notificación antes de que se muestre, descarga el contenido al que hace referencia un payload pequeño, y lo adjunta al contenido de la notificación.

¿Por qué algunas notificaciones push nunca llegan en iOS?

Las causas comunes son un device token que no coincide con el entorno o el bundle ID correcto (BadDeviceToken), un token que el sistema ya invalidó (Unregistered), o el envío con apns-priority 5, que Apple puede agrupar, limitar o descartar según restricciones de energía.