APNS: o que é, como funciona o Apple Push Notification Service e sua arquitetura

O que é APNS?

O Apple Push Notification Service (APNS) é o serviço proprietário da Apple para rotear notificações push do servidor do aplicativo para os dispositivos dos usuários. Ao contrário do FCM, o APNS não suporta Android ou outras plataformas — ele está totalmente vinculado ao ecossistema Apple.

O serviço opera através de uma conexão TLS persistente que cada dispositivo Apple estabelece com os servidores APNS na inicialização. Esta conexão é mantida em segundo plano e usada para entregar notificações com latência mínima.

O APNS lida com toda a infraestrutura de entrega: criptografia, autenticação, priorização e retransmissão quando o dispositivo está indisponível. O desenvolvedor só precisa fornecer um payload formatado corretamente e um token push válido.

Evolução do APNS

Originalmente, o APNS funcionava através de um protocolo binário nas portas 2195–2196. Desde 2015, a Apple migrou o serviço para o moderno protocolo HTTP/2, que suporta multiplexação, compressão de cabeçalhos e notificações push do servidor. O HTTP/2 tornou-se obrigatório em junho de 2020.

Como funciona o Apple Push Notification Service?

O processo de entrega de notificações push através do APNS consiste em cinco etapas: registro do dispositivo, obtenção do token push, envio da solicitação pelo servidor, roteamento APNS e entrega ao dispositivo.

• Registro — ao iniciar, o app chama registerForRemoteNotifications, o sistema contata o APNS
• Token — o APNS retorna um token push ao dispositivo — uma string única que identifica o app no dispositivo
• Envio — o servidor do app envia uma solicitação POST para https://api.push.apple.com com o token e o payload
• Roteamento — o APNS encontra o dispositivo pelo token e entrega a mensagem através da conexão TLS
• Processamento — iOS/macOS exibe a notificação ou a passa para o app dependendo do estado

Se o dispositivo estiver indisponível (desligado ou sem rede), o APNS armazena a mensagem mais recente para cada app e a entrega quando a conexão é restaurada. A duração máxima de armazenamento é de 4 semanas, após as quais a mensagem é excluída.

Autenticação no APNS: Token e Certificado

A Apple suporta dois métodos para autenticar o servidor do aplicativo ao enviar notificações push. Cada método tem suas próprias características quanto ao período de validade, gerenciamento e facilidade de uso.

A autenticação baseada em Token é o método recomendado pela Apple desde 2019. Você cria uma única chave p8 no Apple Developer Console, a envia para o seu servidor e assina cada solicitação APNS com ela. A chave nunca expira e funciona para todos os apps da sua conta.

Qual método de autenticação escolher

Para novos projetos, a autenticação baseada em Token é claramente preferível: uma chave p8 para toda a conta, indefinida, sem vínculo com ambiente. O método baseado em Certificado (.p12) ainda é usado em projetos legados, mas requer substituição anual e certificados separados para Sandbox e Production. Considere a expiração do certificado ao planejar CI/CD.

Tipos de notificações push do APNS

O APNS suporta três tipos de notificações push, que diferem em comportamento no dispositivo e requisitos de atributos da solicitação. A escolha do tipo depende do cenário de UX e da urgência da mensagem.

• Alert — notificação padrão com título, texto e botões de ação opcionais
• Background — entrega silenciosa de dados (push silencioso) sem mostrar ao usuário, tratado em application:didReceiveRemoteNotification
• VOIP — tipo especial para apps VoIP (PushKit), entregue imediatamente mesmo quando o app está fechado

Para notificações Background, você deve especificar a chave content-available: 1 e definir a prioridade como 5 (entrega eficiente em energia). O sistema pode limitar o número de notificações em segundo plano se o app não as processar pontualmente.

Configuração de prioridade de entrega

O APNS suporta dois valores de prioridade: 10 (entrega imediata) e 5 (eficiente em energia). Para notificações alert, use 10 — o usuário deve recebê-las imediatamente. Para notificações background, use 5 — o sistema pode atrasar a entrega para economizar bateria. Prioridade incorreta para background pode levar à rejeição do APNS.

Formato do payload do APNS

O APNS aceita payload no formato JSON com tamanho máximo de 4 KB para notificações regulares e 5 KB para VOIP. O payload contém o dicionário aps obrigatório com configurações de exibição e campos personalizados opcionais.

{
    "aps": {
        "alert": {
            "title": "Nova mensagem",
            "body": "Você tem 3 chats não lidos"
        },
        "badge": 3,
        "sound": "default",
        "category": "message_category",
        "thread-id": "chat_room_42"
    },
    "customData": {
        "chatId": "42"
    }
}

A chave thread-id agrupa notificações na Central de Notificações do iOS. A chave category vincula a notificação a uma UNNotificationCategory para exibir botões de ação. Sem essas chaves, todas as notificações são exibidas individualmente.

Campos personalizados no payload do APNS

Além do dicionário aps obrigatório, o payload do APNS pode conter qualquer campo personalizado no nível superior. Esses campos são acessíveis ao aplicativo através do dicionário userInfo ao processar a notificação. Dados personalizados são convenientes para passar identificadores de entidades, telas ou links. O tamanho máximo do payload é de 4 KB, portanto evite transferir grandes volumes de dados via push; carregue-os via API após abrir a notificação.

Exemplo de envio via API HTTP/2

Para enviar uma notificação push do servidor, você precisa executar uma solicitação POST ao endpoint APNS com os cabeçalhos de autenticação corretos. Abaixo está um exemplo em Node.js usando autenticação baseada em Token.

const http2 = require("http2")
const fs = require("fs")
const jwt = require("jsonwebtoken")

const token = jwt.sign(
    { iss: "TEAM_ID", iat: Math.floor(Date.now() / 1000) },
    fs.readFileSync("AuthKey.p8"),
    { algorithm: "ES256", keyid: "KEY_ID" }
)

const payload = JSON.stringify({
    aps: { alert: { title: "Olá!", body: "Push de teste" } }
})

const client = http2.connect(
    "https://api.push.apple.com"
)

const req = client.request({
    ":method": "POST",
    ":path": "/3/device/DEVICE_PUSH_TOKEN",
    "authorization": "bearer " + token,
    "apns-push-type": "alert",
    "apns-topic": "com.example.app",
    "apns-priority": "10"
})
req.end(payload)

req.on("response", (headers) => {
    if (headers[":status"] === 200) {
        console.log("Push enviado com sucesso")
    }
})

Após o envio, o APNS retorna o status HTTP 200 em caso de entrega bem-sucedida ou um código de erro com descrição no corpo da resposta. É importante tratar erros token-unregistered (410) — esses tokens devem ser removidos do servidor, pois o aplicativo foi deletado do dispositivo.

Erros do APNS e seu tratamento

O APNS retorna códigos de status HTTP para cada solicitação de envio. A entrega bem-sucedida retorna o status 200. Erros exigem diferentes estratégias de tratamento. BadDeviceToken (400) ou Unregistered (410) — o token do dispositivo está desatualizado e deve ser removido do servidor. PayloadTooLarge (413) — o limite de 4 KB foi excedido, reduza o payload.

TooManyRequests (429) — limite de solicitações excedido. O APNS estabelece uma cota no número de envios por segundo. Ao receber 429, implemente um backoff exponencial (exponential backoff) e tente novamente. Recomenda-se não exceder 100 solicitações por segundo por conexão HTTP/2.

Erros do lado do APNS — 500 e 503 (Erro Interno do Servidor / Serviço Indisponível). São falhas temporárias na infraestrutura da Apple. Nesses casos, tente novamente com um atraso de 1 a 5 segundos, no máximo 3 tentativas. Erros 5xx persistentes com um servidor totalmente operacional são raros e geralmente relacionados a problemas de conexão TLS.

Para ambientes de Production, certifique-se de implementar o log de todos os erros do APNS com o token, código de erro e hora. Isso ajudará a identificar rapidamente problemas com certificados, cotas ou tokens de dispositivos específicos. Verifique regularmente as datas de expiração dos certificados se estiver usando autenticação baseada em Certificado.