Skip to content
Guida del Centro assistenza · Aggiornamenti e notifiche Wallet
4 min di letturaVerificato 2026-11-16

Notifiche push

Invia avvisi su schermata di blocco su iOS (con changeMessage) e Android senza costi per singolo SMS.

In questa guida

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.

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
PROTOCOLLO PUSH APPLE APNs E GOOGLE WALLET
FASE 01 FASE 1: REGISTRAZIONE INIZIALE DISPOSITIVO (iOS)
iPhone installa .pkpassRichiama Apple Web Service di Passinstance:POST/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeId/:serial
Header: Authorization: ApplePass <authenticationToken>
Body: { "pushToken": "<apns_device_hex_token>" }
FASE 02 FASE 2: TRIGGER INVIO NOTIFICA PUSH
POST/api/v1/push-notifications/passes/:id | /templates/:id/send | /segmentation
Protocollo HTTP/2 Apple APNs
FASE 03A
1
Apple Push Delivery apre stream HTTP verso api.push.apple.com:443 firm. con Certificato Pass Type (topic)
2
Invia payload vuoto {} (<4096 B)
3
iPhone si risveglia e chiede lista:GET/v1/devices/...?passesUpdated
4
iPhone scarica nuovo .pkpass tramiteGET/v1/passes/:passTypeId/:serial
5
iOS confronta pass.json vecchio vs nuovo e lancia `changeMessage: "...%@"
Protocollo REST API Google Wallet
FASE 03B TLS | | 1. Google Wallet Sync invia
PATCH o addMessage su walletobjects/v1/...
2
Imposta notifyPreference: NOTIFY_ON_UPDATE
3
Google Play Services mostra notifica Wallet nativa in schermata di blocco Android

Apple Wallet Web Service (/v1) e specifica changeMessage

Passinstance implementa l'intera specifica ufficiale Apple Wallet Web Service sotto il prefisso globale /v1:

  1. 1
    Registrazione dispositivo: POST /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber salva il pushToken del dispositivo e lo associa al serialNumber del pass dopo aver verificato l'header ApplePass <authenticationToken>.
  2. 2
    Push silenziosa di risveglio: Quando viene attivata una notifica o un aggiornamento saldo, Apple Push Delivery invia un payload JSON vuoto {} su HTTP/2 al gateway APNs di Apple.
  3. 3
    Interrogazione seriali: Il dispositivo iOS si risveglia in background e richiama GET /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier?passesUpdatedSince=<tag>, ricevendo un array di serialNumbers aggiornati e un nuovo tag lastUpdated.
  4. 4
    Recupero bundle e avviso in schermata di blocco: Per ogni seriale aggiornato, iOS richiede GET /v1/passes/:passTypeIdentifier/:serialNumber (inviando If-Modified-Since). iOS confronta il nuovo pass.json scaricato con la versione precedentemente salvata. Qualsiasi campo il cui value è cambiato e che definisce una stringa changeMessage con il segnaposto %@ genera un banner nella schermata di blocco:
JSON
{
  "key": "points_balance",
  "label": "REWARD POINTS",
  "value": "1,450 pts",
  "changeMessage": "Your reward balance was updated to %@!"
}
  1. 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 su POST /v1/log.

Importante: In Apple Wallet, changeMessage deve includere lo specificatore di formato %@ (che iOS sostituisce con il nuovo value del campo) e il value del 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 con notifyPreference: "NOTIFY_ON_UPDATE" invita Google Wallet a notificare l'utente.
  • Oggetti messaggio personalizzati (addMessage): I messaggi broadcast aggiungono un oggetto Message (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):

MetodoPercorso endpointRegole DTO / PayloadDescrizione
POST/api/v1/push-notifications/passes/:idrequest 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/schedulerequest 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/sendrequest payload (pushNotificationText)Invia in broadcast una notifica push immediata sui pass attivi di un modello (204 No Content).
POST/api/v1/push-notifications/templates/:idrequest payloadPianifica una notifica push per tutti i pass di un modello (segmentIds?, savedSearchIds?).
POST/api/v1/push-notifications/segmentationrequest 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/batchrequest 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)

JSON
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)

JSON
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.

Documentazione prodotto e API correlata

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.