Skip to content
Guide du centre d'aide · Mises à jour & notifications
4 min de lectureVérifié 2026-11-16

Notifications push

Envoyez des alertes sur écran verrouillé iOS (via changeMessage) et Android sans coût par SMS, plus déclencheurs géolocalisés.

Dans ce guide

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.

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
PROTOCOLE PUSH APPLE APNs & GOOGLE WALLET
ÉTAPE 01 PHASE 1 : ENREGISTREMENT INITIAL DE L'APPAREIL (iOS)
L'iPhone installe .pkpassAppelle l'Apple Web Service Passinstance :POST/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeId/:serial
En-tête : Authorization: ApplePass <authenticationToken>
Corps : { "pushToken": "<apns_device_hex_token>" }
ÉTAPE 02 PHASE 2 : DÉCLENCHEMENT DE L'ENVOI DE NOTIFICATION PUSH
POST/api/v1/push-notifications/passes/:id | /templates/:id/send | /segmentation
Protocole Apple APNs HTTP/2
ÉTAPE 03A
1
Apple Push Delivery ouvre un flux HT TLS vers api.push.apple.com:443 signé par le Pass Type Cert (topic)
2
Envoie un paquet vide {} (<4096 o)
3
L'iPhone se réveille & interroge :GET/v1/devices/...?passesUpdated
4
L'iPhone télécharge .pkpass via :GET/v1/passes/:passTypeId/:serial
5
iOS compare ancien/nouveau pass.json & déclenche changeMessage: "... %@"
Protocole REST API Google Wallet
ÉTAPE 03B 2 | | 1. Google Wallet Sync exécu
PATCH ou addMessage sur walletobjects/v1/...
2
Définit notifyPreference : NOTIFY_ON_UPDATE
3
Google Play Services affiche la notification native wallet sur l'écran verrouillé Android

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. 1
    Enregistrement de l'appareil : POST /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber enregistre le pushToken de l'appareil et l'associe au serialNumber du passe après validation de l'en-tête ApplePass <authenticationToken>.
  2. 2
    Push silencieux de réveil : Lorsqu'une notification ou une modification de solde est déclenchée, Apple Push Delivery transmet une charge JSON vide {} en HTTP/2 vers la passerelle APNs d'Apple.
  3. 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 des serialNumbers modifiés et un nouveau jeton lastUpdated.
  4. 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ête If-Modified-Since). iOS compare le nouveau pass.json à la version stockée localement. Tout champ dont la valeur value a changé et qui définit un motif changeMessage contenant le marqueur %@ déclenche une bannière sur l'écran verrouillé :
JSON
{
  "key": "points_balance",
  "label": "REWARD POINTS",
  "value": "1,450 pts",
  "changeMessage": "Your reward balance was updated to %@!"
}
  1. 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 sur POST /v1/log.

Important : Dans Apple Wallet, changeMessage doit impérativement contenir le spécificateur de format %@ (que iOS remplace par la nouvelle valeur value), 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 avec notifyPreference: "NOTIFY_ON_UPDATE" invite Google Wallet à avertir l'utilisateur.
  • Messages personnalisés (addMessage) : Les diffusions ajoutent un objet Message (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éthodeChemin du point d'entréeDTO / Règles de charge utileDescription
POST/api/v1/push-notifications/passes/:idrequest 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/schedulerequest 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/sendrequest 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/:idrequest payloadPlanifie une notification push pour tous les passes d'un modèle (segmentIds?, savedSearchIds?).
POST/api/v1/push-notifications/segmentationrequest 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/batchrequest 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)

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

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

Prêt à lancer votre premier programme de cartes Wallet ?

Créez votre espace de travail, configurez votre modèle et testez une vraie carte dans Apple Wallet et Google Wallet avant de déployer à grande échelle.