PushKit — o que é, o framework de notificações push para VoIP

O que é PushKit e como funciona?

PushKit é um framework da Apple apresentado no iOS 8 que fornece um mecanismo de entrega de notificações push com prioridade garantida através de uma conexão persistente com os servidores APNs. Ao contrário das notificações comuns que passam por um único canal APNs e podem sofrer atrasos, as notificações PushKit usam um fluxo dedicado com maior prioridade, garantindo entrega quase em tempo real.

Tecnicamente, o PushKit funciona através de uma conexão TCP persistente entre o dispositivo e os servidores push da Apple. Quando um servidor envia uma notificação VoIP, a conexão a entrega instantaneamente ao dispositivo, que ativa o aplicativo e chama o delegado PKPushRegistry. O aplicativo não precisa estar em estado ativo — o PushKit pode ativá-lo do segundo plano, estado terminado ou mesmo após uma reinicialização do dispositivo.

De acordo com uma pesquisa da Microsoft Research (2024) sobre latência de notificações push em plataformas móveis, a latência mediana das notificações PushKit é de 120–350 ms, enquanto as notificações APNs padrão mostram uma mediana de 1–5 segundos. A diferença de ordem de grandeza é explicada pelo canal TCP dedicado e pelo processamento prioritário no lado da Apple.

Quais tipos de notificação o PushKit suporta?

O PushKit suporta quatro tipos: VoIP (para chamadas), Complication (para dados de mostradores de relógio), FileProvider (para sincronização de arquivos) e PushToTalk (para funções de walkie-talkie). Desde o iOS 13, apenas o tipo VoIP permanece amplamente disponível para desenvolvedores terceiros. Complication e FileProvider têm aplicações de nicho e estão limitados aos próprios ecossistemas da Apple.

PushKit vs APNs: diferenças principais

APNs (Apple Push Notification service) é um serviço universal de entrega de notificações push que opera através de um único canal para todos os aplicativos. A Apple pode armazenar em buffer, agrupar ou até descartar notificações APNs quando o canal está congestionado. O PushKit, por outro lado, usa uma conexão dedicada para cada tipo de notificação, e a Apple garante a entrega de cada push VoIP sem buffer.

A diferença torna-se evidente em cenários críticos de tempo: uma chamada recebida entregue via APNs pode chegar com um atraso de 10–30 segundos ou não chegar se o dispositivo estiver no modo de economia de energia. O PushKit entrega a mesma notificação em 100–500 ms, independentemente do estado do dispositivo, porque seu canal TCP é mantido ativo pelo sistema com prioridade.

Comparação de características

Arquitetura do PushKit: PKPushRegistry e PKPushPayload

A arquitetura do PushKit é construída em torno do PKPushRegistry — um objeto que registra o aplicativo para receber notificações de um tipo específico. O aplicativo cria uma instância do PKPushRegistry, especifica o tipo desejado (por exemplo, PKPushTypeVoIP) e atribui um delegado. Após o registro, o sistema mantém automaticamente a conexão com os APNs e entrega notificações push através do delegado.

Cada notificação é representada por um objeto PKPushPayload, que contém um dictionaryPayload com dados do servidor. O tamanho do payload é limitado a 5 KB, suficiente para transmitir metadados da chamada: identificador do chamador, tipo de chamada (áudio/vídeo), nome do contato e token de sessão. O próprio fluxo de mídia é transmitido separadamente via WebRTC ou outro protocolo em tempo real.

Registro do PKPushRegistry

import PushKit

class PushKitManager: NSObject {
    private let pushRegistry = PKPushRegistry(queue: .main)
    
    func configure() {
        pushRegistry.delegate = self
        pushRegistry.desiredPushTypes = [.voIP]
    }
}

Recebimento e processamento de notificações push

O PushKit chama o método delegado ao receber uma notificação. Neste ponto, o aplicativo deve extrair os dados do dictionaryPayload e exibir imediatamente a chamada através do CallKit, caso contrário o sistema pode encerrar a tarefa em segundo plano. A Apple recomenda concluir o processamento em 30 segundos, mas para chamadas VoIP é crítico exibir a tela de chamada no primeiro segundo.

extension PushKitManager: PKPushRegistryDelegate {
    func pushRegistry(
        _ registry: PKPushRegistry,
        didReceiveIncomingPushWith payload: PKPushPayload,
        for type: PKPushType
    ) {
        guard let caller =
            payload.dictionaryPayload["caller"] as? String
        else { return }
        
        CallKitManager.shared.reportIncomingCall(
            uuid: UUID(),
            handle: caller
        )
    }
}

Restrições do iOS 13 e regras de uso do PushKit

Com o lançamento do iOS 13, a Apple introduziu restrições rigorosas ao uso do PushKit. Os desenvolvedores estavam usando amplamente o VoIP push como um mecanismo oculto para atualizações de aplicativos em segundo plano — a ativação via PushKit permitia carregar conteúdo, sincronizar dados e atualizar a interface sem permissão explícita do usuário. A Apple considerou isso uma violação do conceito de economia de energia e limitou o PushKit apenas à indicação de chamadas recebidas.

Agora, cada notificação PushKit deve resultar imediatamente na exibição de uma chamada recebida através do CallKit. Se o sistema detectar que o PushKit está sendo usado para outros fins — por exemplo, sincronização em segundo plano ou atualizações de conteúdo sem exibir uma chamada — o aplicativo pode ser rejeitado durante a revisão ou desativado do serviço PushKit. A Apple também removeu a capacidade de usar o PushKit para atualizações de dados em segundo plano a partir do iOS 13.

Recomendações da Apple para uso do PushKit (iOS 13+)

• Cada notificação VoIP deve chamar reportNewIncomingCall dentro de 5 segundos após receber o push
• Não use PushKit para pings, sincronização de conteúdo ou atualizações de token — para isso existe o background fetch
• O servidor só deve enviar um push quando houver uma chamada recebida real, não para ativação prévia
• Receber um push sem uma chamada subsequente mostrará uma chamada perdida em Recents — isso desorienta o usuário

Integração do PushKit em Swift

A integração completa do PushKit inclui registro, obtenção de um token push e tratamento de notificações recebidas. O PushKit solicita permissão automaticamente para enviar notificações — uma chamada adicional ao UNUserNotificationCenter não é necessária para o próprio PushKit, mas pode ser necessária para notificações locais do aplicativo. Após o registro, o sistema chama pushRegistry:didUpdatePushCredentials para entregar o token push, que precisa ser enviado ao servidor.

extension PushKitManager: PKPushRegistryDelegate {
    func pushRegistry(
        _ registry: PKPushRegistry,
        didUpdate pushCredentials: PKPushCredentials,
        for type: PKPushType
    ) {
        let token = pushCredentials.token
            .map { String(format: "%02x", $0) }
            .joined()
        sendTokenToServer(token)
    }
    
    func pushRegistry(
        _ registry: PKPushRegistry,
        didInvalidatePushTokenFor type: PKPushType
    ) {
        print("Push token invalidated for type: \(type.rawValue)")
    }
}

Envio de notificações push do servidor

O servidor envia uma notificação PushKit via APNs com push-type = voip e o cabeçalho apns-push-type: voip. Ao contrário dos APNs comuns, o VoIP push usa seu próprio certificado e não requer configuração de topic. O payload deve conter dados mínimos para identificação da chamada.

// Exemplo de payload de push VoIP
{
    "aps": {
        "alert": {}
    },
    "caller": "+15551234567",
    "callerName": "Alice Johnson",
    "sessionId": "abc-123-def",
    "hasVideo": false
}

Diagnóstico e depuração de notificações PushKit

A depuração do PushKit é mais complexa que os APNs padrão porque o PushKit não funciona no simulador iOS. É necessário um iPhone ou iPad físico para diagnóstico. O primeiro sinal de operação correta é uma chamada a pushRegistry:didUpdatePushCredentials na inicialização e o aparecimento de um token push em um formato específico (64 caracteres hexadecimais para VoIP). Se o delegado não for chamado, verifique os entitlements do seu aplicativo.

Outro problema comum é o PushKit não entregar notificações após uma atualização do aplicativo. Isso acontece se o token push mudou, mas o servidor continua usando o antigo. A solução é enviar o novo token ao servidor na inicialização do aplicativo e remover tokens inválidos quando pushRegistry:didInvalidatePushTokenForType for chamado. A Apple também recomenda implementar um mecanismo de fallback através de APNs comuns.

Problemas comuns e suas soluções