Toda integração de notificação push do iOS começa no mesmo ponto: provar ao serviço de Notificação Push da Apple que você tem permissão para enviar mensagens aos usuários do seu aplicativo. A Apple oferece duas maneiras de fazer isso — uma chave de autenticação APNs (.p8) ou um certificado APNs (.p12) — e a diferença entre eles é a diferença entre uma credencial que você configura uma vez e outra que você renovará anualmente, muitas vezes no pior momento possível.
Este guia explica como a autenticação APNs realmente funciona, quando usar uma chave .p8 em vez de um certificado .p12, e o punhado de erros que remontam a fazer isso incorretamente.
Como a autenticação APNs funciona
Quando seu provedor de push — PushEngage, ou seu próprio servidor — envia uma notificação, ele se conecta à API do provedor APNs da Apple e deve provar duas coisas: que está autorizado a enviar em seu nome e que tem permissão para direcionar o ID do pacote do seu aplicativo (o "tópico" em termos APNs). A chave .p8 e o certificado .p12 são apenas duas maneiras diferentes de provar isso.
O lado do dispositivo é separado. Seu aplicativo se registra com o APNs e recebe um token de dispositivo — essa parte nunca muda, independentemente de qual credencial seu provedor usa. A autenticação é puramente uma preocupação do servidor para a Apple, e é por isso que você pode alternar métodos sem tocar no binário do seu aplicativo.
A chave de autenticação .p8 (use esta)
O .p8 é uma chave de assinatura de token. Seu provedor a usa para gerar tokens JSON Web de curta duração que autenticam cada conexão com o APNs. Suas propriedades a tornam a escolha padrão para quase todos:
- Nunca expira. Sem renovação anual, sem interrupção de push em uma data esquecida.
- Uma chave cobre todos os aplicativos em sua conta de desenvolvedor. Lance um segundo aplicativo e a mesma chave o autenticará.
- Funciona para ambientes de desenvolvimento e produção — sem pares de certificados sandbox/produção.
- Viaja como três valores: o próprio arquivo .p8, o Key ID de 10 caracteres e seu Team ID.
Duas coisas para saber antes de criar uma. A Apple limita você a duas chaves APNs ativas por conta, portanto, organizações grandes devem tratar a criação de chaves como um ato deliberado, não um hábito por projeto. E o arquivo .p8 só pode ser baixado uma vez, no momento da criação — armazene-o em um local onde sua equipe possa encontrá-lo, porque a Apple não o fornecerá novamente.
O certificado .p12 (o caminho legado)
O .p12 é um certificado de cliente TLS, exportado do Acesso às Chaves após a Apple emiti-lo. Ele autentica a própria conexão em vez de assinar tokens. Ele ainda funciona, e algumas políticas de segurança corporativa ainda o exigem, mas suas restrições são o motivo pelo qual a Apple direciona novas integrações para a chave:
- Expira a cada ano. A causa mais comum de falha súbita e total de push é um certificado APNs que expirou silenciosamente.
- É limitado a um único app. Cada ID de bundle precisa de seu próprio certificado, e cada certificado precisa de seu próprio calendário de renovação.
- Requer um Mac. A dança de exportação de solicitação de assinatura e Keychain não tem um caminho apenas pelo navegador.
Qual você deve usar?
| Chave de autenticação .p8 | Certificado .p12 | |
|---|---|---|
| Expira | Nunca | A cada 12 meses |
| Escopo | Todos os apps na conta | Um ID de bundle |
| Ambientes | Desenvolvimento + produção | Separado ou combinado por certificado |
| Criado a partir de | Qualquer navegador | Mac com Acesso ao Keychain |
| Limite da conta | 2 chaves ativas | Pares por app |
| Use quando | Quase sempre | A política exige certificados |
A resposta honesta: use a chave .p8, a menos que uma política de segurança force o caminho do certificado. Menos partes móveis, nada para renovar, uma credencial para todo o seu portfólio.
Criando uma chave .p8 em três minutos
- Na sua conta de Desenvolvedor Apple, vá para Certificados, Identificadores e Perfis → Chaves e registre uma nova chave.
- Nomeie-a, ative a caixa de seleção Serviço de Notificações Push da Apple (APNs) e continue.
- Baixe o arquivo .p8 (lembre-se: uma chance), e anote o ID da Chave mostrado na tela de confirmação e o seu ID da Equipe na página de associação da conta.
- Faça o upload dos três valores para seu provedor de push. No PushEngage, esta é uma única tela nas configurações do seu app — o guia de credenciais APNs o percorre com capturas de tela.
Os erros que isso explica
Uma parcela surpreendente dos tickets de “push está quebrado” são problemas de credenciais disfarçados. Os suspeitos usuais:
- BadDeviceToken — você está enviando o token de um app criado em sandbox para o ambiente de produção, ou vice-versa. Builds de depuração do Xcode se comunicam com o sandbox; builds do TestFlight e da App Store se comunicam com a produção.
- TopicDisallowed — a credencial não cobre o ID do pacote que você está direcionando. Típico com certificados .p12 por app e uma configuração copiada e colada.
- Falha súbita de entrega de 100% — um .p12 expirado. Verifique a data de validade do certificado antes de verificar qualquer outra coisa.
- InvalidProviderToken — uma chave .p8 revogada, ou o par errado de Key ID/Team ID ao lado de um arquivo válido.
Onde isso se encaixa na sua integração
A credencial APNs é o primeiro passo de exatamente uma sessão de configuração. Faça o upload do .p8 para o PushEngage uma vez, e tudo o que vier depois — a integração com o SDK iOS 1.0, mídia rica através da sua extensão de notificação, campanhas acionadas e a própria entrega — funcionará com base nela sem mais cerimônias. Se você está vindo do Firebase, a mesma chave que você deu ao FCM funciona aqui, que é parte do motivo pelo qual migrar do FCM no iOS é um projeto de uma tarde.
Para a camada de estratégia que vem após a configuração, comece com o guia de marketing de push para aplicativos. E quando estiver pronto para enviar, o guia completo de configuração do iOS leva você da credencial à primeira campanha em menos de uma hora.
