Notificações push no iOS com o APNs

Como funciona

Quando o usuário aceita receber notificações, o iOS entrega ao app um device token: o endereço daquele app naquele aparelho. Quem envia manda a notificação ao APNs com esse token e uma credencial da sua conta Apple. A Apple entrega ao aparelho.

O que você precisa

• Uma conta no Apple Developer Program.
• O recurso Push Notifications ativado no app, no Xcode.
• Uma chave de autenticação do APNs (arquivo AuthKey_XXXX.p8), criada em Certificates, Identifiers & Profiles → Keys.
• O Team ID da sua conta, o Key ID da chave e o Bundle ID do app.

Conectar o APNs ao vivapush

No painel do vivapush, abra as credenciais do app, envie o arquivo .p8 e informe Team ID, Key ID e Bundle ID. O vivapush abre uma conexão autenticada com o APNs para conferir os dados e mostra o resultado.

O vivapush usa a autenticação por token (.p8), não certificados .p12. Uma chave .p8 não expira todo ano e serve para todos os apps da sua equipe na Apple. O arquivo fica criptografado e nunca aparece por inteiro.

Se o Bundle ID estiver errado, a Apple recusa todos os tokens. O vivapush trata isso como erro de configuração e marca a credencial como inválida, em vez de apagar os aparelhos.

Sandbox e produção

A Apple tem dois ambientes. Apps instalados direto pelo Xcode usam o sandbox; TestFlight e App Store usam produção. Um token de um ambiente não funciona no outro.

No vivapush, a credencial tem um ambiente padrão e cada aparelho pode informar o seu em "apns_environment" no registro. Assim, os aparelhos de teste e os de produção convivem no mesmo app.

Registrar o aparelho

O vivapush não tem um SDK nativo para iOS. O app pede a autorização com UNUserNotificationCenter, chama registerForRemoteNotifications e envia o token à API pública com a chave pública do app (começa com vp_pub_), que só registra aparelhos.

POST /api/v1/devices
X-VivaPush-App-Key: vp_pub_...

{
  "installation_id": "inst-123456",
  "platform": "ios",
  "token": "token do APNs em hexadecimal",
  "apns_environment": "production",
  "external_user_id": "cliente-42",
  "language": "pt-BR", "country": "BR", "timezone": "America/Sao_Paulo",
  "push_opt_in": true
}

O registro é idempotente por installation_id: um token novo substitui o anterior da mesma instalação. Quando o app for aberto, chame POST /api/v1/devices/activity para contar o usuário como ativo no mês.

Imagens, links e prioridade

Quando a notificação tem imagem, o vivapush envia mutable-content e o endereço da imagem em vp_image. Para mostrar a imagem, o app precisa de uma Notification Service Extension que baixe e anexe o arquivo.

Ao tocar, o app recebe vp_url (um link web ou do próprio app) e vp_nid, o ID da notificação. O conteúdo inteiro precisa caber em 4 KB, o limite da Apple; o vivapush não envia notificações maiores que isso.

Prioridade alta entrega na hora e serve para avisos urgentes. A normal deixa o iOS escolher o melhor momento para poupar bateria.

Confirmar entrega e aberturas

Quando a notificação chega (por exemplo, pela Notification Service Extension) ou é aberta, chame POST /api/v1/events com o vp_nid e o tipo ("delivered", "opened" ou "clicked"). Sem essa confirmação, o vivapush mostra só “aceita para entrega”, que quer dizer que a Apple recebeu a mensagem.

Quando a Apple informa que um token deixou de valer (app desinstalado, por exemplo), o aparelho é marcado como sem receber e o webhook subscriptions.invalidated avisa o seu sistema.

Perguntas frequentes