Aperçu : fonctionnement des notifications push sur écran verrouillé Wallet
Apple Wallet et Google Wallet n'autorisent pas l'envoi arbitraire de notifications publicitaires indépendantes comme une application mobile native classique : les alertes sur écran verrouillé obéissent à des protocoles cryptographiques stricts directement liés aux mutations de valeurs de champs d'un passe installé. Lorsqu'un champ change, les deux plateformes affichent une alerte native sur l'écran verrouillé sans aucun coût SMS à l'envoi.
Apple Wallet Web Service (/v1) & spécification changeMessage
Passinstance implémente intégralement la spécification Apple Wallet Web Service sous le préfixe global de route /v1 :
-
1
Enregistrement de l'appareil :
POST /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumberenregistre lepushTokende l'appareil et l'associe auserialNumberdu passe après validation de l'en-têteApplePass <authenticationToken>. -
2
Push silencieux de réveil : Lorsqu'une notification ou une modification de solde est déclenchée,
Apple Push Deliverytransmet une charge JSON vide{}en HTTP/2 vers la passerelle APNs d'Apple. -
3
Interrogation des numéros de série : L'appareil iOS se réveille en arrière-plan et appelle
GET /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier?passesUpdatedSince=<tag>, recevant la liste desserialNumbersmodifiés et un nouveau jetonlastUpdated. -
4
Récupération du passe & bannière sur écran verrouillé : Pour chaque numéro de série modifié, iOS appelle
GET /v1/passes/:passTypeIdentifier/:serialNumber(avec l'en-têteIf-Modified-Since). iOS compare le nouveaupass.jsonà la version stockée localement. Tout champ dont la valeurvaluea changé et qui définit un motifchangeMessagecontenant le marqueur%@déclenche une bannière sur l'écran verrouillé :
{
"key": "points_balance",
"label": "REWARD POINTS",
"value": "1,450 pts",
"changeMessage": "Your reward balance was updated to %@!"
}
-
5
Désenregistrement & journalisation d'erreurs : Lorsqu'un utilisateur supprime la carte d'Apple Wallet, iOS appelle
DELETE /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber. Toute erreur d'analyse côté client est signalée par iOS surPOST /v1/log.
Important : Dans Apple Wallet,
changeMessagedoit impérativement contenir le spécificateur de format%@(que iOS remplace par la nouvelle valeurvalue), et la nouvelle valeur du champ doit réellement différer de la précédente stockée sur l'appareil. L'envoi de deux valeurs strictement identiques d'affilée ne déclenche aucune seconde alerte sur l'écran verrouillé iOS.
Mises à jour REST Google Wallet & quotas de notification
Sur Android, Passinstance met à jour l'objet cloud (LoyaltyObject, EventTicketObject, GenericObject, OfferObject ou GiftCardObject) via l'API REST walletobjects de Google :
-
Mises à jour de champs (
PATCH) : La modification de points, d'intitulés de palier ou de modules texte avecnotifyPreference: "NOTIFY_ON_UPDATE"invite Google Wallet à avertir l'utilisateur. -
Messages personnalisés (
addMessage) : Les diffusions ajoutent un objetMessage(messageType: "TEXT_AND_NOTIFY") au passe Google Wallet, soumis au quota anti-spam de Google limitant à maximum 3 messages avec notification push par passe sur une fenêtre glissante de 24 heures.
Points d'entrée API des notifications push (Push Notifications API)
Tous les points d'entrée push sont montés sous /api/v1/push-notifications (Push Notifications API ; Passes API expose également POST /api/v1/passes/:id/notifications et POST /api/v1/passes/sendpushnotifications) :
| Méthode | Chemin du point d'entrée | DTO / Règles de charge utile | Description |
|---|---|---|---|
| POST | /api/v1/push-notifications/passes/:id | request payload (pushNotificationText, <=85 caractères ; accepte id ou externalId) | Envoie une mise à jour immédiate ou différée à tous les appareils enregistrés d'un passe unique. |
| POST | /api/v1/push-notifications/passes/:id/schedule | request payload (pushNotificationText, publicationDate Y-m-d H:i, publicationTimezone?) | Planifie une notification future pour un passe unique (id ou externalId). |
| POST | /api/v1/push-notifications/templates/:id/send | request payload (pushNotificationText) | Diffuse immédiatement une notification push à tous les passes actifs d'un modèle (204 No Content). |
| POST | /api/v1/push-notifications/templates/:id | request payload | Planifie une notification push pour tous les passes d'un modèle (segmentIds?, savedSearchIds?). |
| POST | /api/v1/push-notifications/segmentation | request payload (searchId, message <=85 caractères, priority?) | Envoie une notification ciblée aux passes correspondant à l'UUID d'une recherche enregistrée. |
| POST | /api/v1/push-notifications/batch | request payload (passIds[] max 500, message, priority?) | Envoie immédiatement une notification push vers une liste explicite de jusqu'à 500 IDs de passes. |
Exemple : notification ciblée sur recherche enregistrée (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"
}
Exemple : notification d'un passe individuel (externalId ou UUID)
POST /api/v1/push-notifications/passes/crm_usr_44910
{
"pushNotificationText": "Hi Marcus, you unlocked Gold Tier status!",
"pushNotificationHeaderText": "Artisan Roasters VIP"
}
Géofencing, iBeacons & déclencheurs par date pertinente
En complément des alertes déclenchées par le serveur, les passes prennent en charge un affichage contextuel passif sur l'écran verrouillé configuré dans l'éditeur de modèles :
-
Coordonnées GPS (
locations) : Jusqu'à 10 coordonnées GPS (latitude,longitude,relevantText,maxDistance) par archive.pkpass(et tableaux de localisation Google Wallet). -
Bluetooth Low Energy (
beacons) : Jusqu'à 10 identifiants de proximité iBeacon (proximityUUID,major,minor,relevantText) pour la détection en magasin sur iOS. -
Dates pertinentes (
relevantDate) : Horodatage ISO 8601 affichant automatiquement un billet d'événement ou une carte d'embarquement sur l'écran verrouillé à l'approche de l'horaire prévu.
Découvrez l'ensemble des mécaniques d'alerte sur Notifications de passes Wallet, Capacités de géofencing et Mises à jour & messages planifiés.
