Panoramica: come funzionano le notifiche push nella schermata di blocco Wallet
Apple Wallet e Google Wallet non consentono popup push arbitrari svincolati dal pass come le app native tradizionali; le notifiche nella schermata di blocco sono invece regolate da rigorosi protocolli crittografici Wallet legati direttamente alle variazioni dei valori dei campi su un pass installato. Quando un campo del pass cambia, entrambe le piattaforme mostrano un avviso nativo in schermata di blocco senza alcun costo per singolo messaggio di un gateway SMS.
Apple Wallet Web Service (/v1) e specifica changeMessage
Passinstance implementa l'intera specifica ufficiale Apple Wallet Web Service sotto il prefisso globale /v1:
-
1
Registrazione dispositivo:
POST /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumbersalva ilpushTokendel dispositivo e lo associa alserialNumberdel pass dopo aver verificato l'headerApplePass <authenticationToken>. -
2
Push silenziosa di risveglio: Quando viene attivata una notifica o un aggiornamento saldo,
Apple Push Deliveryinvia un payload JSON vuoto{}su HTTP/2 al gateway APNs di Apple. -
3
Interrogazione seriali: Il dispositivo iOS si risveglia in background e richiama
GET /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier?passesUpdatedSince=<tag>, ricevendo un array diserialNumbersaggiornati e un nuovo taglastUpdated. -
4
Recupero bundle e avviso in schermata di blocco: Per ogni seriale aggiornato, iOS richiede
GET /v1/passes/:passTypeIdentifier/:serialNumber(inviandoIf-Modified-Since). iOS confronta il nuovopass.jsonscaricato con la versione precedentemente salvata. Qualsiasi campo il cuivalueè cambiato e che definisce una stringachangeMessagecon il segnaposto%@genera un banner nella schermata di blocco:
{
"key": "points_balance",
"label": "REWARD POINTS",
"value": "1,450 pts",
"changeMessage": "Your reward balance was updated to %@!"
}
-
5
Annullamento registrazione dispositivo e log errori: Quando un utente rimuove un pass da Apple Wallet, iOS invia
DELETE /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber. Eventuali errori di parsing lato client vengono segnalati da iOS suPOST /v1/log.
Importante: In Apple Wallet,
changeMessagedeve includere lo specificatore di formato%@(che iOS sostituisce con il nuovovaluedel campo) e ilvaluedel campo deve effettivamente differire dal valore precedente presente sul dispositivo. Inviare due volte consecutive lo stesso testo esatto non attiverà un secondo avviso in schermata di blocco su iOS.
Aggiornamenti REST di Google Wallet e quote di notifica
Su Android, Passinstance aggiorna l'oggetto cloud del pass (LoyaltyObject, EventTicketObject, GenericObject, OfferObject o GiftCardObject) tramite le REST API walletobjects di Google:
-
Aggiornamenti campi (
PATCH): L'aggiornamento di punti, etichette di livello o moduli testo connotifyPreference: "NOTIFY_ON_UPDATE"invita Google Wallet a notificare l'utente. -
Oggetti messaggio personalizzati (
addMessage): I messaggi broadcast aggiungono un oggettoMessage(messageType: "TEXT_AND_NOTIFY") al pass Google Wallet, nel rispetto del limite antispam di Google di massimo 3 messaggi con notifica push per pass nell'arco di 24 ore.
Endpoint API per notifiche push (Push Notifications API)
Tutti gli endpoint push sono montati sotto /api/v1/push-notifications (Push Notifications API; Passes API espone inoltre POST /api/v1/passes/:id/notifications e POST /api/v1/passes/sendpushnotifications):
| Metodo | Percorso endpoint | Regole DTO / Payload | Descrizione |
|---|---|---|---|
| POST | /api/v1/push-notifications/passes/:id | request payload (pushNotificationText, <=85 caratteri; accetta id o externalId del pass) | Invia un aggiornamento immediato o futuro opzionale a tutti i dispositivi registrati di un singolo pass. |
| POST | /api/v1/push-notifications/passes/:id/schedule | request payload (pushNotificationText, publicationDate Y-m-d H:i, publicationTimezone?) | Pianifica una notifica futura per un singolo pass (id o externalId). |
| POST | /api/v1/push-notifications/templates/:id/send | request payload (pushNotificationText) | Invia in broadcast una notifica push immediata sui pass attivi di un modello (204 No Content). |
| POST | /api/v1/push-notifications/templates/:id | request payload | Pianifica una notifica push per tutti i pass di un modello (segmentIds?, savedSearchIds?). |
| POST | /api/v1/push-notifications/segmentation | request payload (searchId, message <=85 caratteri, priority?) | Invia una notifica push mirata ai pass corrispondenti all'UUID di una ricerca salvata. |
| POST | /api/v1/push-notifications/batch | request payload (passIds[] max 500, message, priority?) | Invia una notifica push immediata fino a 500 ID pass espliciti. |
Esempio: notifica push mirata su ricerca salvata (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"
}
Esempio: notifica su singolo pass (externalId o UUID)
POST /api/v1/push-notifications/passes/crm_usr_44910
{
"pushNotificationText": "Hi Marcus, you unlocked Gold Tier status!",
"pushNotificationHeaderText": "Artisan Roasters VIP"
}
Geofencing, iBeacon e trigger di data rilevante
Oltre agli aggiornamenti inviati dal server, i pass supportano la visualizzazione passiva locale sulla schermata di blocco configurata nell'Editor modelli:
-
Posizioni GPS (
locations): Fino a 10 coordinate GPS (latitude,longitude,relevantText,maxDistance) per ogni.pkpass(e array di posizioni Google Wallet). -
Bluetooth Low Energy (
beacons): Fino a 10 UUID di prossimità iBeacon (proximityUUID,major,minor,relevantText) per trigger retail indoor su iOS. -
Date rilevanti (
relevantDate): Timestamp ISO 8601 dell'evento che mette automaticamente in risalto un biglietto evento o una carta d'imbarco sulla schermata di blocco all'avvicinarsi dell'evento.
Approfondisca le meccaniche complete di consegna in Notifiche Wallet Pass, Funzionalità di geofencing e Aggiornamenti e messaggistica pianificati.
