Skip to content
Guia da Central de Ajuda · Atualizações e notificações
4 min de leituraVerificado 2026-11-16

Notificações push

Envie avisos para o ecrã bloqueado em iOS (via changeMessage) e Android sem custo por SMS e com geocercas.

Neste guia

Visão geral: Como funcionam as notificações push no ecrã bloqueado da carteira

A Apple Wallet e a Google Wallet não permitem janelas push arbitrárias sem ligação ao cartão como aplicações nativas autónomas; em vez disso, as notificações no ecrã bloqueado obedecem a protocolos criptográficos estritos das carteiras associados diretamente a alterações de valores de campos num passe instalado. Quando um campo do passe muda, ambas as plataformas exibem um alerta nativo no ecrã bloqueado sem custos por mensagem SMS.

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
PROTOCOLO PUSH APPLE APNs E GOOGLE WALLET
ETAPA 01 FASE 1: REGISTO INICIAL DO DISPOSITIVO (iOS)
iPhone instala .pkpassChama Apple Web Service da Passinstance:POST/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeId/:serial
Header: Authorization: ApplePass <authenticationToken>
Body: { "pushToken": "<apns_device_hex_token>" }
ETAPA 02 FASE 2: GATILHO DE ENVIO DE NOTIFICAÇÃO PUSH
POST/api/v1/push-notifications/passes/:id | /templates/:id/send ou /segmentation
Protocolo Apple APNs HTTP/2
ETAPA 03A
1
Apple Push Delivery abre stream TLS p/ api.push.apple.com:443 assinado com Certificado Pass Type (topic)
2
Envia payload vazio {} (<4096 B)
3
iPhone acorda e consulta alterados:GET/v1/devices/...?passesUpdated
4
iPhone obtém novo .pkpass viaGET/v1/passes/:passTypeId/:serial
5
iOS compara antigo vs novo pass.json e dispara changeMessage: "... %@"
Protocolo API REST Google Wallet
ETAPA 03B P/2 | | 1. Google Wallet Sync envia
PATCH ou addMessage em walletobjects/v1/...
2
Define notifyPreference: NOTIFY_ON_UPDATE
3
Google Play Services apresenta notificação nativa de carteira no ecrã bloqueado Android

Apple Wallet Web Service (/v1) e especificação changeMessage

A Passinstance implementa na íntegra a especificação Apple Wallet Web Service sob o prefixo global de rota /v1:

  1. 1
    Registo do dispositivo: POST /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber guarda o pushToken do dispositivo e associa-o ao serialNumber do passe após validar o cabeçalho ApplePass <authenticationToken>.
  2. 2
    Push silencioso de despertar: Quando uma notificação ou atualização de saldo é acionada, o Apple Push Delivery envia um payload JSON vazio {} via HTTP/2 para a gateway APNs da Apple.
  3. 3
    Consulta de números de série: O dispositivo iOS acorda em segundo plano e chama GET /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier?passesUpdatedSince=<tag>, recebendo uma matriz de serialNumbers atualizados e uma nova etiqueta lastUpdated.
  4. 4
    Obtenção do pacote e alerta no ecrã bloqueado: Para cada número de série atualizado, o iOS pede GET /v1/passes/:passTypeIdentifier/:serialNumber (enviando If-Modified-Since). O iOS compara o pass.json recém-transferido com a versão guardada anteriormente. Qualquer campo cujo value tenha mudado e defina uma string changeMessage contendo o marcador %@ despoleta um aviso no ecrã bloqueado:
JSON
{
  "key": "points_balance",
  "label": "REWARD POINTS",
  "value": "1,450 pts",
  "changeMessage": "Your reward balance was updated to %@!"
}
  1. 5
    Cancelamento de registo e registo de erros: Quando um utilizador elimina um passe da Apple Wallet, o iOS chama DELETE /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber. Eventuais erros de análise no cliente são comunicados pelo iOS a POST /v1/log.

Importante: Na Apple Wallet, changeMessage tem de incluir o especificador de formato %@ (que o iOS substitui pelo novo value do campo) e o value do campo tem de diferir efetivamente do valor anterior no dispositivo. Enviar exatamente o mesmo texto duas vezes seguidas não despoletará um segundo alerta no ecrã bloqueado do iOS.

Atualizações REST Google Wallet e quotas de notificação

No Android, a Passinstance atualiza o objeto cloud do passe (LoyaltyObject, EventTicketObject, GenericObject, OfferObject ou GiftCardObject) através da API REST walletobjects da Google:

  • Atualizações de campos (PATCH): Atualizar pontos, rótulos de patamar ou módulos de texto com notifyPreference: "NOTIFY_ON_UPDATE" leva a Google Wallet a notificar o utilizador.
  • Objetos de mensagem personalizada (addMessage): Mensagens em massa acrescentam um objeto Message (messageType: "TEXT_AND_NOTIFY") ao passe Google Wallet, sujeito ao limite anti-spam da Google de no máximo 3 mensagens com notificação push por passe num período de 24 horas.

Endpoints da API de notificações push (Push Notifications API)

Todos os endpoints push estão montados em /api/v1/push-notifications (Push Notifications API; Passes API expõe igualmente POST /api/v1/passes/:id/notifications e POST /api/v1/passes/sendpushnotifications):

MétodoCaminho do endpointRegras de DTO / PayloadDescrição
POST/api/v1/push-notifications/passes/:idrequest payload (pushNotificationText, <=85 carateres; aceita id ou externalId do passe)Envia uma atualização imediata ou futura opcional para todos os dispositivos registados de um único passe.
POST/api/v1/push-notifications/passes/:id/schedulerequest payload (pushNotificationText, publicationDate Y-m-d H:i, publicationTimezone?)Agenda uma notificação futura para um único passe (id ou externalId).
POST/api/v1/push-notifications/templates/:id/sendrequest payload (pushNotificationText)Difunde uma atualização imediata por notificação push nos passes ativos de um modelo (204 No Content).
POST/api/v1/push-notifications/templates/:idrequest payloadAgenda uma notificação push para todos os passes de um modelo (segmentIds?, savedSearchIds?).
POST/api/v1/push-notifications/segmentationrequest payload (searchId, message <=85 carateres, priority?)Envia uma notificação push direcionada aos passes correspondentes ao UUID de uma pesquisa guardada.
POST/api/v1/push-notifications/batchrequest payload (passIds[] máx. 500, message, priority?)Envia uma notificação push imediata para até 500 IDs de passe explícitos.

Exemplo: Notificação push direcionada por pesquisa guardada (request payload)

JSON
POST /api/v1/push-notifications/segmentation
{
  "searchId": "7b9e4c12-3f81-4a90-b8d2-19c48a70e112",
  "message": "Double points weekend starts tonight at 6 PM!",
  "priority": "HIGH"
}

Exemplo: Notificação de passe único (externalId ou UUID)

JSON
POST /api/v1/push-notifications/passes/crm_usr_44910
{
  "pushNotificationText": "Hi Marcus, you unlocked Gold Tier status!",
  "pushNotificationHeaderText": "Artisan Roasters VIP"
}

Geofencing, iBeacons e gatilhos de data relevante

Além das atualizações enviadas pelo servidor, os passes suportam apresentação passiva no ecrã bloqueado diretamente no dispositivo, configurada no Editor de Modelos:

  • Localizações GPS (locations): Até 10 coordenadas GPS (latitude, longitude, relevantText, maxDistance) por .pkpass (e matrizes de localização Google Wallet).
  • Bluetooth Low Energy (beacons): Até 10 UUIDs de proximidade iBeacon (proximityUUID, major, minor, relevantText) para gatilhos em lojas interiores no iOS.
  • Datas relevantes (relevantDate): Carimbo temporal ISO 8601 do evento que apresenta automaticamente um Bilhete de Evento ou Cartão de Embarque no ecrã bloqueado à medida que a hora do evento se aproxima.

Explore toda a mecânica de entrega em Notificações de passes Wallet, Capacidades de geofencing e Atualizações agendadas e mensagens.

Documentação de produto e API relacionada

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.