Descripción general: cómo funcionan las notificaciones push en pantalla de bloqueo del monedero
Apple Wallet y Google Wallet no permiten avisos push arbitrarios sin vínculo como las aplicaciones nativas independientes; en su lugar, las notificaciones en pantalla de bloqueo están regidas por estrictos protocolos criptográficos del monedero ligados directamente a modificaciones de valor en campos de un pase ya instalado. Cuando cambia un campo de un pase, ambas plataformas muestran una alerta nativa en la pantalla de bloqueo sin costes por mensaje de pasarela SMS.
Especificación de Apple Wallet Web Service (/v1) y changeMessage
Passinstance implementa la especificación completa de Apple Wallet Web Service bajo el prefijo global de rutas /v1:
-
1
Registro del dispositivo:
POST /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumberalmacena elpushTokendel dispositivo y lo vincula alserialNumberdel pase tras verificar la cabeceraApplePass <authenticationToken>. -
2
Push silencioso de activación: Cuando se dispara una notificación o actualización de saldo,
Apple Push Deliveryenvía un payload JSON vacío{}por HTTP/2 a la pasarela APNs de Apple. -
3
Consulta de números de serie: El dispositivo iOS se despierta en segundo plano y llama a
GET /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier?passesUpdatedSince=<tag>, recibiendo una lista deserialNumbersactualizados y una nueva etiquetalastUpdated. -
4
Descarga del paquete y alerta en pantalla de bloqueo: Para cada número de serie actualizado, iOS solicita
GET /v1/passes/:passTypeIdentifier/:serialNumber(enviandoIf-Modified-Since). iOS compara el nuevopass.jsondescargado con la versión almacenada anteriormente. Cualquier campo cuyovaluehaya cambiado y defina un textochangeMessagecon el marcador%@dispara un aviso en la pantalla de bloqueo:
{
"key": "points_balance",
"label": "REWARD POINTS",
"value": "1,450 pts",
"changeMessage": "Your reward balance was updated to %@!"
}
-
5
Baja del dispositivo y registro de errores: Cuando un usuario elimina un pase de Apple Wallet, iOS llama a
DELETE /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber. Cualquier error de análisis en el cliente iOS es notificado por iOS aPOST /v1/log.
Importante: En Apple Wallet,
changeMessagedebe incluir el especificador de formato%@(que iOS sustituye por el nuevovaluedel campo), y elvaluedel campo debe ser distinto de su valor anterior en el dispositivo. Enviar exactamente el mismo texto dos veces seguidas no activará una segunda alerta en la pantalla de bloqueo de iOS.
Actualizaciones REST de Google Wallet y cuotas de notificación
En Android, Passinstance actualiza el objeto de pase en la nube (LoyaltyObject, EventTicketObject, GenericObject, OfferObject o GiftCardObject) mediante la API REST walletobjects de Google:
-
Actualizaciones de campos (
PATCH): Actualizar puntos, etiquetas de nivel o módulos de texto connotifyPreference: "NOTIFY_ON_UPDATE"indica a Google Wallet que notifique al usuario. -
Objetos de mensaje personalizados (
addMessage): Los mensajes de difusión añaden un objetoMessage(messageType: "TEXT_AND_NOTIFY") al pase de Google Wallet, sujeto al límite antispam de Google de un máximo de 3 mensajes con notificación push por pase en una ventana de 24 horas.
Endpoints de API de notificaciones push (Push Notifications API)
Todos los endpoints push están montados bajo /api/v1/push-notifications (Push Notifications API; Passes API también expone POST /api/v1/passes/:id/notifications y POST /api/v1/passes/sendpushnotifications):
| Método | Ruta del endpoint | Reglas de DTO / Payload | Descripción |
|---|---|---|---|
| POST | /api/v1/push-notifications/passes/:id | request payload (pushNotificationText, <=85 caracteres; acepta id o externalId del pase) | Envía una actualización inmediata o futura opcional a todos los dispositivos registrados de un pase individual. |
| POST | /api/v1/push-notifications/passes/:id/schedule | request payload (pushNotificationText, publicationDate Y-m-d H:i, publicationTimezone?) | Programa una notificación futura para un pase individual (id o externalId). |
| POST | /api/v1/push-notifications/templates/:id/send | request payload (pushNotificationText) | Difunde una actualización inmediata por notificación push a los pases activos de una plantilla (204 No Content). |
| POST | /api/v1/push-notifications/templates/:id | request payload | Programa una notificación push para todos los pases de una plantilla (segmentIds?, savedSearchIds?). |
| POST | /api/v1/push-notifications/segmentation | request payload (searchId, message <=85 caracteres, priority?) | Envía una notificación push dirigida a los pases que coinciden con el UUID de una búsqueda guardada. |
| POST | /api/v1/push-notifications/batch | request payload (passIds[] máx. 500, message, priority?) | Envía una notificación push inmediata a un máximo de 500 identificadores explícitos de pases. |
Ejemplo: notificación push segmentada por búsqueda 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"
}
Ejemplo: notificación de un pase individual (externalId o UUID)
POST /api/v1/push-notifications/passes/crm_usr_44910
{
"pushNotificationText": "Hi Marcus, you unlocked Gold Tier status!",
"pushNotificationHeaderText": "Artisan Roasters VIP"
}
Geocercas, iBeacons y disparadores por fecha relevante
Además de las actualizaciones enviadas desde el servidor, los pases admiten aparición pasiva en la pantalla de bloqueo configurada en el Editor de plantillas:
-
Ubicaciones GPS (
locations): Hasta 10 coordenadas GPS (latitude,longitude,relevantText,maxDistance) por.pkpass(y arrays de ubicación en Google Wallet). -
Bluetooth Low Energy (
beacons): Hasta 10 UUID de proximidad iBeacon (proximityUUID,major,minor,relevantText) para avisos en interior en comercios sobre iOS. -
Fechas relevantes (
relevantDate): Marca de tiempo ISO 8601 del evento que muestra automáticamente una entrada o tarjeta de embarque en la pantalla de bloqueo al aproximarse el evento.
Explore todos los detalles de entrega en Notificaciones de pases Wallet, Capacidades de geocercas y Actualizaciones programadas y mensajería.
