Device Token: cómo funciona, obtención del token APNS y actualización

Qué es un Device Token

Device Token (token de dispositivo) es un identificador único en forma de cadena hex que APNS (Apple Push Notification Service) genera para cada aplicación en un dispositivo iOS. El token es la clave mediante la cual el servidor envía notificaciones push a un dispositivo específico. Sin un Device Token válido, el servidor no puede entregar notificaciones push — APNS rechaza la solicitud con un error 400 BadRequest.

Cómo se forma el token

Device Token es creado por el sistema iOS cuando la aplicación contacta por primera vez a APNS después de la instalación. El proceso de generación incluye una vinculación criptográfica con el bundle ID de la aplicación y el identificador único del dispositivo (UID), después APNS devuelve a la aplicación un token de 32 bytes en formato hex (64 caracteres). El token no es permanente — el sistema puede generar uno nuevo bajo ciertas condiciones.

Rol del token en la entrega de notificaciones push

Cuando el servidor envía una notificación push, incluye el Device Token en la solicitud HTTP/2 a APNS. APNS valida el token: si el token pertenece a otro entorno (sandbox en lugar de production), ha expirado o ha sido revocado, el servidor de Apple devuelve un error 410 Gone o 400 BadRequest. Solo después de una validación exitosa del token, APNS comienza a entregar la notificación al dispositivo.

Diferencia entre Device Token y otros identificadores

Device Token no debe confundirse con IDFA (Identifier for Advertisers), IDFV (Identifier for Vendor) ni UID (Unique Device Identifier). IDFA e IDFV se usan para publicidad y analítica, UID es un número de serie del hardware. Device Token existe exclusivamente para notificaciones push y no revela información sobre el usuario o el dispositivo fuera de APNS.

Cómo obtiene y registra el token el dispositivo

El proceso de obtención de Device Token consta de varios pasos obligatorios, desde solicitar permiso al usuario hasta enviar el token al servidor. Cada paso es crítico — saltarse cualquiera de ellos imposibilita el envío de notificaciones push al dispositivo.

Solicitud de permiso de notificaciones

El primer paso es que la aplicación solicite al usuario permiso para enviar notificaciones a través de UNUserNotificationCenter.current().requestAuthorization. El usuario puede aceptar, denegar o seleccionar opciones opcionales (alert, badge, sound). Sin el consentimiento explícito del usuario, el sistema no emitirá un Device Token, incluso si la aplicación llama a registerForRemoteNotifications. Después de obtener el permiso, la aplicación llama a UIApplication.shared.registerForRemoteNotifications(), lo que inicia el proceso de registro en APNS.

Obtención del token de APNS

Después del registro, APNS devuelve el token a través del delegado AppDelegate: application(_:didRegisterForRemoteNotificationsWithDeviceToken:). Una llamada exitosa contiene un objeto Data con el token, que debe convertirse a una cadena hex para transmitirlo al servidor. En caso de error, el sistema llama a application(_:didFailToRegisterForRemoteNotificationsWithError:) con una descripción del problema: configuración incorrecta de certificados, falta de red o configuración incorrecta del proyecto.

Envío del token a su servidor

Después de recibir el token, la aplicación debe enviarlo inmediatamente a su servidor para almacenarlo en la base de datos. La solicitud API incluye el token, el identificador del dispositivo (para mapeo), el entorno (sandbox/production) y opcionalmente datos adicionales: versión del SO, modelo del dispositivo, idioma. Se recomienda reenviar el token en cada inicio de la aplicación para que el servidor siempre tenga un token actualizado.

// Solicitar permiso y registrarse en APNS
func registerForPushNotifications() {
    UNUserNotificationCenter.current()
        .requestAuthorization(options: [.alert, .sound, .badge]) {
        [weak self] granted, error in
        guard granted else {
            print("Permiso no concedido")
            return
        }
        DispatchQueue.main.async {
            UIApplication.shared
                .registerForRemoteNotifications()
        }
    }
}

// Obtener Device Token de APNS
func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    let tokenString = deviceToken
        .map { String(format: "%02.2hhx", $0) }
        .joined()
    print("Device Token: \(tokenString)")

    // Enviar token al servidor
    PushTokenService.shared
        .sendTokenToServer(tokenString) { success in
        if success {
            UserDefaults.standard.set(tokenString,
                forKey: "lastDeviceToken")
        }
    }
}

Gestión de tokens en el servidor

La parte del servidor del sistema push debe almacenar el Device Token en la base de datos, asociado con el usuario y el entorno. Al enviar una notificación, el servidor forma una solicitud a APNS, incluyendo el token en la URL y un token JWT (o certificado) para autorización. La gestión correcta de tokens afecta críticamente la tasa de entrega de notificaciones push.

Estructura de la base de datos de tokens

La tabla de tokens en el servidor debe contener al menos: Device Token (único), ID de usuario, entorno (sandbox/production), fecha de última actualización y estado (activo/inactivo). Se recomienda agregar un índice en el token para búsqueda rápida al enviar y en el usuario para obtener la lista de todos los dispositivos de un usuario. Muchas aplicaciones permiten que un usuario tenga múltiples dispositivos — cada uno con su propio token.

Autorización de solicitudes a APNS

Para enviar una notificación push, el servidor debe autorizar la solicitud a APNS de dos maneras. Basado en certificados usa un certificado SSL generado en Apple Developer Console. Basado en token usa un JWT (JSON Web Token) con una clave .p8 que es válida hasta 30 días sin necesidad de renovar el certificado. La autorización basada en token se considera más moderna y es recomendada por Apple para nuevos proyectos.

Formación de una solicitud HTTP/2 APNS

La solicitud a APNS incluye el método HTTP/2 POST, URL con la ruta /3/device/{device_token}, encabezados de autorización y un cuerpo JSON con el payload. El encabezado apns-topic debe contener el bundle ID de la aplicación. apns-priority indica la prioridad de entrega (5 — inmediatamente, 10 — con ahorro de batería). apns-expiration establece el tiempo en segundos desde la época hasta el cual APNS intentará entregar la notificación.

// Ejemplo de envío de push en Node.js mediante APNS HTTP/2
const http2 = require('http2');
const client = http2.connect('https://api.push.apple.com');

const deviceToken = 'abcdef0123456789...';
const payload = JSON.stringify({
    "aps": { "alert": "Hello!", "sound": "default" }
});

const req = client.request({
    ':method': 'POST',
    ':path': `/3/device/${deviceToken}`,
    'apns-topic': 'com.example.app',
    'apns-priority': '10',
    'apns-expiration': '0',
    'authorization': `bearer ${jwtToken}`
});
req.write(payload);
req.end();
req.on('response', (headers) => {
    if (headers[':status'] === '200') {
        console.log('Push enviado exitosamente');
    }
});

Envío por lotes y limitación de velocidad

Al enviar notificaciones push a un gran número de dispositivos, use el envío por lotes con control de velocidad. APNS recomienda no exceder 1500 solicitudes por segundo por conexión. Si se excede el límite, el servidor de Apple devuelve un error 429 Too Many Requests. Para campañas a gran escala, use múltiples conexiones y distribuya la carga uniformemente entre los dispositivos.

Actualización e invalidación de tokens

Device Token no es permanente y puede cambiar en varios escenarios, lo que requiere un mecanismo de actualización en el servidor. Si el servidor continúa enviando push a un token desactualizado, APNS devuelve un error 410 Gone, indicando que el token ya no es válido para el entorno dado.

Cuándo cambia el token

Apple documenta varios escenarios en los que Device Token cambia: el usuario reinstala la aplicación, restaura el dispositivo desde una copia de seguridad de iCloud, instala una nueva versión de iOS, o restablece la configuración de red o privacidad. En cada caso, la aplicación recibirá un nuevo token de APNS en su próximo inicio. El servidor debe actualizar el token en la base de datos, eliminando el antiguo y guardando el nuevo.

Manejo del error 410 Gone de APNS

Cuando el servidor envía un push a un token desactualizado, APNS devuelve HTTP 410 con el encabezado apns-unless-timestamp. Este encabezado indica la hora después de la cual el token se volvió inválido. El servidor debe eliminar o desactivar inmediatamente este token en la base de datos para evitar enviar a él nuevamente. Ignorar el error 410 desperdicia recursos y reduce la tasa de entregabilidad.

Limpieza periódica de tokens inactivos

Para mantener la base de datos de tokens actualizada, se recomienda ejecutar una limpieza periódica. El script de limpieza analiza los registros de APNS de los últimos N días, encuentra todos los tokens que recibieron un error 410 y los desactiva en la base de datos. Adicionalmente, se pueden eliminar tokens sin actividad del usuario durante más de 90 días — son registros inútiles que solo aumentan el tamaño de la base de datos.

Validación de tokens antes del envío masivo

Antes del envío masivo de notificaciones push (boletines, campañas promocionales), se recomienda validar previamente los tokens. APNS no proporciona una API directa para validación por lotes de tokens, por lo que se usa la estrategia de enviar un push de prueba con baja prioridad y analizar los errores. Los tokens que devuelvan un error 410 se excluyen del envío principal.

Ejemplo de código para obtener Device Token

Veamos el ciclo completo de obtención de un Device Token en Swift, incluyendo manejo de errores y envío al servidor. El código cubre la solicitud de permiso, registro en APNS, conversión de Data a cadena hex, manejo de errores y envío del token a su propio servidor con reintentos en caso de fallo.

import UIKit
import UserNotifications

final class PushNotificationManager: NSObject {

    static let shared = PushNotificationManager()
    private let apiClient = APIClient()
    private var currentToken: String?

    func register() {
        UNUserNotificationCenter.current()
            .requestAuthorization(
                options: [.alert, .badge, .sound]) {
            [weak self] granted, error in
            guard granted else {
                Analytics.log(
                    "Push permission denied")
                return
            }
            DispatchQueue.main.async {
                UIApplication.shared
                    .registerForRemoteNotifications()
            }
        }
    }

    func handleDeviceToken(_ tokenData: Data) {
        let token = tokenData
            .map { String(format: "%02.2hhx", $0) }
            .joined()

        guard token != currentToken else { return }
        currentToken = token
        sendTokenToServer(token)
    }

    func handleRegistrationError(_ error: Error) {
        Analytics.log(
            "Push registration failed: \(error)")

        // Reintentar después de retardo en errores de red
        if let urlError = error as? URLError,
            urlError.code == .notConnectedToInternet {
            DispatchQueue.main.asyncAfter(
                deadline: .now() + 10) { [weak self] in
                self?.register()
            }
        }
    }

    private func sendTokenToServer(_ token: String) {
        let body = PushTokenRequest(
            token: token,
            environment: Environment.current == .debug
                ? "sandbox" : "production",
            osVersion: UIDevice.current.systemVersion,
            locale: Locale.current.identifier
        )
        apiClient.sendToken(body) { [weak self] result in
            if case .success = result {
                self?.currentToken = token
            }
        }
    }
}

Manejo de errores durante el registro

Los errores durante el registro en APNS pueden deberse a varias razones. Los más comunes incluyen falta de red, configuración incorrecta de certificados en Xcode (por ejemplo, la capacidad Push Notifications desactivada), uso del simulador (que no soporta push) o un perfil de aprovisionamiento incorrecto. En producción, es importante registrar los errores y, si es posible, reintentar el registro en el próximo inicio de la aplicación.

Prueba de Device Token en el simulador

El simulador de iOS no soporta la recepción de un Device Token real. Para probar el registro en el simulador, use comprobaciones de arquitectura i386: en una compilación de depuración, se puede simular la obtención del token o usar pruebas de UI con objetos mock. Las pruebas reales de notificaciones push siempre se realizan en un dispositivo físico conectado a Xcode.