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.
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
Registo do dispositivo:
POST /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumberguarda opushTokendo dispositivo e associa-o aoserialNumberdo passe após validar o cabeçalhoApplePass <authenticationToken>. -
2
Push silencioso de despertar: Quando uma notificação ou atualização de saldo é acionada, o
Apple Push Deliveryenvia um payload JSON vazio{}via HTTP/2 para a gateway APNs da Apple. -
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 deserialNumbersatualizados e uma nova etiquetalastUpdated. -
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(enviandoIf-Modified-Since). O iOS compara opass.jsonrecém-transferido com a versão guardada anteriormente. Qualquer campo cujovaluetenha mudado e defina uma stringchangeMessagecontendo o marcador%@despoleta um aviso no ecrã bloqueado:
{
"key": "points_balance",
"label": "REWARD POINTS",
"value": "1,450 pts",
"changeMessage": "Your reward balance was updated to %@!"
}
-
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 aPOST /v1/log.
Importante: Na Apple Wallet,
changeMessagetem de incluir o especificador de formato%@(que o iOS substitui pelo novovaluedo campo) e ovaluedo 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 comnotifyPreference: "NOTIFY_ON_UPDATE"leva a Google Wallet a notificar o utilizador. -
Objetos de mensagem personalizada (
addMessage): Mensagens em massa acrescentam um objetoMessage(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étodo | Caminho do endpoint | Regras de DTO / Payload | Descrição |
|---|---|---|---|
| POST | /api/v1/push-notifications/passes/:id | request 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/schedule | request 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/send | request 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/:id | request payload | Agenda uma notificação push para todos os passes de um modelo (segmentIds?, savedSearchIds?). |
| POST | /api/v1/push-notifications/segmentation | request 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/batch | request 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)
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)
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.
