PushKit — o que é, framework de notificações VoIP da iOS

O que é PushKit

PushKit é um framework da Apple, apresentado no iOS 8, que fornece notificações push de baixa latência para aplicativos VoIP. Ao contrário do APNs padrão (Apple Push Notification service), o PushKit permite que o aplicativo acorde em segundo plano ao receber uma chamada recebida, sem exibir uma notificação ao usuário. Isso é crítico para aplicativos de voz e vídeo — o usuário recebe a chamada instantaneamente, mesmo que o aplicativo esteja fechado. De acordo com a Apple WWDC 2024, o PushKit processa mais de 2 bilhões de notificações VoIP diariamente em todo o mundo.

Como funciona o PushKit

O mecanismo é baseado em uma conexão direta entre o dispositivo e o servidor push da Apple, ignorando o canal padrão de notificações. Quando o servidor do aplicativo envia uma notificação VoIP, ela passa por um servidor PushKit dedicado e é entregue ao dispositivo com máxima prioridade. O sistema acorda o aplicativo em segundo plano e chama o método delegado pushRegistry:didReceiveIncomingPushWithPayload:forType:. O aplicativo recebe o payload, processa a chamada e chama o completion handler para confirmação. Todo o ciclo, do envio ao processamento, não leva mais de 5 segundos, conforme especificação da Apple.

PushKit vs APNs

A principal diferença entre PushKit e APNs está no mecanismo de entrega e processamento. O APNs usa o canal padrão de notificações exibindo um banner, som ou badge, enquanto o PushKit entrega dados diretamente ao aplicativo sem notificação visual. Abaixo está uma tabela de comparação das principais características.

PushKit também não suporta anexos de mídia enriquecidos e não pode ser usado para notificações de marketing comuns. A Apple controla rigorosamente o uso do PushKit — o aplicativo deve ter funcionalidade VoIP explícita, caso contrário será rejeitado na revisão. O APNs continua sendo a solução universal para todos os outros cenários.

Registro e recebimento de notificações VoIP

Para usar o PushKit, o aplicativo deve se registrar através do PKPushRegistry com o tipo pushType .voIP. O registro é feito uma vez na primeira inicialização, após o qual o sistema gera um token push único e o transmite através do delegado. Este token é enviado ao servidor do aplicativo para posterior envio de notificações VoIP. Abaixo está um exemplo de registro PushKit e obtenção de token em Swift.

Configurando o registro PushKit

import PushKit

let registry = PKPushRegistry(queue: DispatchQueue.main)
registry.delegate = self
registry.desiredPushTypes = [.voIP]

// MARK: - PKPushRegistryDelegate
func pushRegistry(
    _ registry: PKPushRegistry,
    didUpdate pushCredentials: PKPushCredentials,
    for type: PKPushType
) {
    let deviceToken = pushCredentials.token
        .map { String.format("%02x", $0) }
        .joined()
    sendVoIPTokenToServer(deviceToken)
}

Após chamar desiredPushTypes com PKPushType.voIP, o sistema solicita automaticamente permissão para receber notificações VoIP. No método pushRegistry:didUpdatePushCredentials:forType:, o aplicativo recebe o token do dispositivo como Data, que é convertido em uma string hexadecimal e enviado ao servidor. O token é único para cada dispositivo e muda quando o aplicativo é reinstalado — o servidor deve lidar com atualizações de token.

Recebendo uma notificação recebida

func pushRegistry(
    _ registry: PKPushRegistry,
    didReceiveIncomingPushWith payload: PKPushPayload,
    for type: PKPushType,
    completion: @escaping VoidBlock
) {
    guard let caller = payload.dictionaryPayload["caller"] as? String else {
        completion()
        return
    }

    let update = CXCallUpdate()
    update.remoteHandle = CXHandle(type: .generic, value: caller)

    provider.reportNewIncomingCall(
        with: UUID(),
        update: update,
        completion: { error in
            if let error = error {
                print("Call error: \(error)")
            }
            completion()
        }
    )
}

No método didReceiveIncomingPushWith, o aplicativo recebe o payload com os dados da chamada. Após extrair as informações do chamador, um CXCallUpdate do framework CallKit é criado para exibir a tela de chamada recebida. É importante chamar o completion handler após o processamento — caso contrário, o sistema pode encerrar à força o processo do aplicativo por tempo limite. O tempo máximo de processamento é de 30 segundos, após os quais o iOS considera a notificação não processada.

Lidando com chamadas recebidas com CallKit

O PushKit é fortemente integrado com o CallKit — um framework para exibir a interface de chamadas do sistema no iOS. Quando o aplicativo recebe uma notificação VoIP através do PushKit, ele deve criar um CXProvider e CXCallController para gerenciar a chamada. O CallKit mostra automaticamente a tela de chamada recebida na tela de bloqueio, mesmo que o aplicativo esteja minimizado. Abaixo está um exemplo de configuração de um provedor CallKit.

let config = CXProviderConfiguration(localizedName: "MyApp")
config.supportsVideo = true
config.maximumCallGroups = 1
config.maximumCallsPerCallGroup = 1
config.supportedHandleTypes = [.phoneNumber, .generic]

let provider = CXProvider(configuration: config)
provider.setDelegate(self, queue: nil)

CXProviderConfiguration define a aparência e o comportamento da tela de chamada — o nome do aplicativo, suporte a vídeo, número de chamadas simultâneas. A integração do PushKit com o CallKit é obrigatória para aplicativos VoIP: sem ela, o sistema não mostrará a tela de chamada recebida e o usuário perderá a chamada. A Apple exige o uso do CallKit para todos os aplicativos que usam PushKit.

Características e limitações

Usar o PushKit traz uma série de restrições estritas definidas pela Apple. O framework só pode ser usado para funcionalidade VoIP — qualquer tentativa de enviar notificações de marketing através do PushKit resultará no bloqueio do aplicativo. O tamanho do payload não deve exceder 4 KB e só pode conter dados JSON sem anexos. A partir do iOS 13, a Apple introduziu um limite na frequência de envio de notificações VoIP — não mais que uma notificação por minuto por dispositivo. O servidor deve cumprir este limite, caso contrário as notificações serão rejeitadas pelo sistema. O PushKit também não funciona no simulador iOS — o teste só é possível em um dispositivo físico.

Estrutura do payload PushKit

Um payload de notificação VoIP é um dicionário JSON com dados personalizados da chamada. Ao contrário do APNs, o PushKit não suporta os campos padrão alert, badge e sound — todos os dados são definidos pelo desenvolvedor. Uma estrutura típica inclui o identificador do chamador (caller), tipo de chamada (voice ou video), identificador da sala ou sessão e um timestamp. O tamanho de cada campo deve ser mínimo para economizar espaço dentro do limite de 4 KB. A Apple recomenda incluir no payload apenas os dados necessários para exibir a tela de chamada recebida na tela de bloqueio, carregando o restante das informações (avatar, histórico de mensagens) após o usuário atender através de uma requisição de rede separada. Exemplo de um payload mínimo: { "caller": "Ana", "caller_id": "+79161234567", "type": "audio", "room": "uuid-room-1234", "ts": 1718534400 }. Todas as chaves no payload devem ser curtas, inequívocas e documentadas no lado do servidor para compatibilidade entre versões do aplicativo.

Tratamento de erros e novas tentativas

Ao trabalhar com PushKit, é necessário lidar com falhas de entrega e perda de conexão. Se o dispositivo estiver offline ou desconectado da rede, a notificação VoIP não será entregue — o PushKit não suporta armazenamento e reenvio, ao contrário do APNs, que armazena notificações por até 24 horas para nova tentativa. O servidor deve rastrear independentemente as notificações não entregues e tentar novamente quando a conexão for restaurada. O mecanismo push kit feedback service é usado para isso — ele retorna uma lista de notificações não entregues com o motivo da falha. Recomenda-se configurar o monitoramento do sucesso de entrega de notificações VoIP através de análises do servidor e notificar o desenvolvedor se a taxa de entregas bem-sucedidas cair abaixo de 95%. O sistema PushKit garante a entrega apenas quando o dispositivo tem uma conexão de internet ativa — se ausente, a notificação é perdida permanentemente, o que é crítico considerar ao projetar um sistema confiável de chamadas VoIP com entrega garantida.