Device Token: como funciona, obtenção do token APNS e atualização

O que é um Device Token

Device Token (token de dispositivo) é um identificador único em forma de string hex que o APNS (Apple Push Notification Service) gera para cada aplicativo em um dispositivo iOS. O token é a chave pela qual o servidor envia notificações push para um dispositivo específico. Sem um Device Token válido, o servidor não pode entregar notificações push — o APNS rejeita a solicitação com um erro 400 BadRequest.

Como o token é formado

O Device Token é criado pelo sistema iOS quando o aplicativo contata o APNS pela primeira vez após a instalação. O processo de geração envolve a ligação criptográfica ao bundle ID do aplicativo e ao identificador único do dispositivo (UID), após o que o APNS retorna ao aplicativo um token de 32 bytes em formato hex (64 caracteres). O token não é permanente — o sistema pode gerar um novo sob certas condições.

Papel do token na entrega de notificações push

Quando o servidor envia uma notificação push, ele inclui o Device Token na solicitação HTTP/2 ao APNS. O APNS valida o token: se o token pertencer a outro ambiente (sandbox em vez de production), expirou ou foi revogado, o servidor da Apple retorna um erro 410 Gone ou 400 BadRequest. Somente após a validação bem-sucedida do token, o APNS começa a entregar a notificação ao dispositivo.

Diferença entre Device Token e outros identificadores

O Device Token não deve ser confundido com IDFA (Identifier for Advertisers), IDFV (Identifier for Vendor) ou UID (Unique Device Identifier). IDFA e IDFV são usados para publicidade e análise, UID é um número de série do hardware. O Device Token existe exclusivamente para notificações push e não revela informações sobre o usuário ou dispositivo fora do APNS.

Como o dispositivo obtém e registra o token

O processo de obtenção do Device Token consiste em várias etapas obrigatórias, desde solicitar permissão ao usuário até enviar o token ao servidor. Cada etapa é crítica — pular qualquer uma delas resulta na impossibilidade de enviar notificações push ao dispositivo.

Solicitação de permissão de notificação

O primeiro passo é o aplicativo solicitar permissão do usuário para enviar notificações através de UNUserNotificationCenter.current().requestAuthorization. O usuário pode concordar, negar ou selecionar opções opcionais (alert, badge, sound). Sem o consentimento explícito do usuário, o sistema não emitirá um Device Token, mesmo que o aplicativo chame registerForRemoteNotifications. Após obter a permissão, o aplicativo chama UIApplication.shared.registerForRemoteNotifications(), o que inicia o processo de registro no APNS.

Obtendo o token do APNS

Após o registro, o APNS retorna o token através do delegado AppDelegate: application(_:didRegisterForRemoteNotificationsWithDeviceToken:). Uma chamada bem-sucedida contém um objeto Data com o token, que deve ser convertido em uma string hex para transmissão ao servidor. Em caso de erro, o sistema chama application(_:didFailToRegisterForRemoteNotificationsWithError:) com uma descrição do problema: configuração incorreta de certificados, indisponibilidade de rede ou configuração incorreta do projeto.

Enviando o token para seu servidor

Após receber o token, o aplicativo deve enviá-lo imediatamente ao seu servidor para armazenamento no banco de dados. A solicitação de API inclui o token, o identificador do dispositivo (para mapeamento), o ambiente (sandbox/production) e opcionalmente dados adicionais: versão do SO, modelo do dispositivo, idioma. Recomenda-se reenviar o token a cada inicialização do aplicativo para que o servidor tenha sempre um token atualizado.

// Solicitar permissão e registrar no APNS
func registerForPushNotifications() {
    UNUserNotificationCenter.current()
        .requestAuthorization(options: [.alert, .sound, .badge]) {
        [weak self] granted, error in
        guard granted else {
            print("Permissão não concedida")
            return
        }
        DispatchQueue.main.async {
            UIApplication.shared
                .registerForRemoteNotifications()
        }
    }
}

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

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

Gerenciamento de tokens no servidor

O lado do servidor do sistema push deve armazenar o Device Token no banco de dados, associado ao usuário e ao ambiente. Ao enviar uma notificação, o servidor forma uma solicitação ao APNS, incluindo o token na URL e um token JWT (ou certificado) para autorização. O gerenciamento correto de tokens afeta criticamente a taxa de entrega de notificações push.

Estrutura do banco de dados de tokens

A tabela de tokens no servidor deve conter no mínimo: Device Token (único), ID do usuário, ambiente (sandbox/production), data da última atualização e status (ativo/inativo). Recomenda-se adicionar um índice no token para pesquisa rápida ao enviar e no usuário para obter a lista de todos os dispositivos de um usuário. Muitos aplicativos permitem que um usuário tenha vários dispositivos — cada um com seu próprio token.

Autorizando solicitações ao APNS

Para enviar uma notificação push, o servidor deve autorizar a solicitação ao APNS de duas maneiras. Baseado em certificado usa um certificado SSL gerado no Apple Developer Console. Baseado em token usa um JWT (JSON Web Token) com uma chave .p8 válida por até 30 dias sem necessidade de renovar o certificado. A autorização baseada em token é considerada mais moderna e recomendada pela Apple para novos projetos.

Formando uma solicitação HTTP/2 APNS

A solicitação ao APNS inclui o método HTTP/2 POST, URL com o caminho /3/device/{device_token}, cabeçalhos de autorização e um corpo JSON com o payload. O cabeçalho apns-topic deve conter o bundle ID do aplicativo. apns-priority indica a prioridade de entrega (5 — imediatamente, 10 — com economia de bateria). apns-expiration define o tempo em segundos desde a época até o qual o APNS tentará entregar a notificação.

// Exemplo de envio de push no Node.js via 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 com sucesso');
    }
});

Envio em lote e limitação de taxa

Ao enviar notificações push para um grande número de dispositivos, use o envio em lote com controle de taxa. O APNS recomenda não exceder 1500 solicitações por segundo por conexão. Se o limite for excedido, o servidor da Apple retorna um erro 429 Too Many Requests. Para campanhas em grande escala, use várias conexões e distribua a carga uniformemente entre os dispositivos.

Atualização e invalidação de tokens

Device Token não é permanente e pode mudar em vários cenários, exigindo um mecanismo de atualização no servidor. Se o servidor continuar enviando push para um token desatualizado, o APNS retorna um erro 410 Gone, indicando que o token não é mais válido para o ambiente fornecido.

Quando o token muda

A Apple documenta vários cenários em que o Device Token muda: o usuário reinstala o aplicativo, restaura o dispositivo a partir de um backup do iCloud, instala uma nova versão do iOS ou redefine as configurações de rede ou privacidade. Em cada caso, o aplicativo receberá um novo token do APNS em sua próxima inicialização. O servidor deve atualizar o token no banco de dados, removendo o antigo e salvando o novo.

Lidando com o erro 410 Gone do APNS

Quando o servidor envia um push para um token desatualizado, o APNS retorna HTTP 410 com o cabeçalho apns-unless-timestamp. Este cabeçalho indica a hora após a qual o token se tornou inválido. O servidor deve remover ou desativar imediatamente este token no banco de dados para evitar enviar para ele novamente. Ignorar o erro 410 desperdiça recursos e reduz a taxa de entregabilidade.

Limpeza periódica de tokens inativos

Para manter o banco de dados de tokens atualizado, recomenda-se executar uma limpeza periódica. O script de limpeza analisa os logs do APNS dos últimos N dias, encontra todos os tokens que receberam um erro 410 e os desativa no banco de dados. Adicionalmente, tokens sem atividade do usuário por mais de 90 dias podem ser removidos — são registros inúteis que apenas aumentam o tamanho do banco de dados.

Validação de tokens antes do envio em massa

Antes do envio em massa de notificações push (newsletters, campanhas promocionais), recomenda-se pré-validar os tokens. O APNS não fornece uma API direta para validação em lote de tokens, portanto, utiliza-se a estratégia de enviar um push de teste com baixa prioridade e analisar os erros. Tokens que retornam um erro 410 são excluídos do envio principal.

Exemplo de código para obter Device Token

Vamos percorrer o ciclo completo de obtenção de um Device Token em Swift, incluindo tratamento de erros e envio ao servidor. O código cobre a solicitação de permissão, registro no APNS, conversão de Data em string hex, tratamento de erros e envio do token ao seu próprio servidor com tentativas de repetição em caso de falha.

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)")

        // Tentar novamente após atraso em erros de rede
        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
            }
        }
    }
}

Tratamento de erros durante o registro

Erros durante o registro no APNS podem ser causados por vários motivos. Os mais comuns incluem indisponibilidade de rede, configuração incorreta de certificados no Xcode (por exemplo, a capacidade Push Notifications desativada), uso do simulador (que não suporta push) ou um perfil de provisionamento incorreto. Em produção, é importante registrar os erros e, se possível, repetir o registro na próxima inicialização do aplicativo.

Testando Device Token no simulador

O simulador do iOS não suporta receber um Device Token real. Para testar o registro no simulador, use verificações de arquitetura i386: em uma compilação de depuração, é possível simular a obtenção do token ou usar testes de UI com objetos mock. O teste real de notificações push é sempre feito em um dispositivo físico conectado ao Xcode.