Überblick: Wie Wallet-Sperrbildschirm-Pushs funktionieren
Apple Wallet und Google Wallet erlauben keine beliebigen, ungebundenen Werbe-Pop-ups wie eigenständige native Apps. Stattdessen unterliegen Sperrbildschirm-Meldungen strengen kryptografischen Wallet-Protokollen, die direkt an Änderungen von Feldwerten auf einem installierten Pass gekoppelt sind. Sobald sich ein Pass-Feld ändert, zeigen beide Plattformen eine native Sperrbildschirm-Benachrichtigung an — ganz ohne SMS-Gebühren pro Nachricht.
Apple Wallet Web Service (/v1) & changeMessage-Spezifikation
Passinstance implementiert die vollständige Apple-Wallet-Web-Service-Spezifikation unter dem globalen Routenpräfix /v1:
-
1
Geräteregistrierung:
POST /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumberspeichert daspushTokendes Geräts und verknüpft es nach Prüfung des HeadersAuthorization: ApplePass <authenticationToken>mit derserialNumberdes Passes. -
2
Stiller Wake-up-Push: Wird eine Benachrichtigung oder Kontostandsänderung ausgelöst, sendet
Apple Push Deliveryein leeres JSON-Payload{}über HTTP/2 an das Apple-APNs-Gateway. -
3
Seriennummern-Abfrage: Das iOS-Gerät wacht im Hintergrund auf und ruft
GET /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier?passesUpdatedSince=<tag>auf, woraufhin es eine Liste aktualisierterserialNumberssowie ein neueslastUpdated-Tag erhält. -
4
Paketabruf & Sperrbildschirm-Hinweis: Für jede aktualisierte Seriennummer fordert iOS
GET /v1/passes/:passTypeIdentifier/:serialNumberan (mitIf-Modified-Since). iOS vergleicht die neu heruntergeladenepass.jsonmit der lokal gespeicherten Version. Jedes Feld, dessenvaluesich geändert hat und das einenchangeMessage-String mit dem Platzhalter%@definiert, erzeugt eine Sperrbildschirm-Meldung:
{
"key": "points_balance",
"label": "REWARD POINTS",
"value": "1,450 pts",
"changeMessage": "Your reward balance was updated to %@!"
}
-
5
Geräteabmeldung & Fehlerprotokollierung: Löscht jemand einen Pass aus Apple Wallet, ruft iOS
DELETE /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumberauf. Etwaige clientseitige Parsingfehler meldet iOS anPOST /v1/log.
Wichtig: In Apple Wallet muss
changeMessagezwingend den Format-Platzhalter%@enthalten (den iOS durch den neuen Feldwertvalueersetzt), und der Wertvaluedes Feldes muss sich tatsächlich vom bisherigen Wert auf dem Gerät unterscheiden. Wird exakt derselbe Textwert zweimal hintereinander gesendet, löst iOS keine zweite Sperrbildschirm-Meldung aus.
Google Wallet REST-Updates & Benachrichtigungs-Kontingente
Auf Android aktualisiert Passinstance das Cloud-Pass-Objekt (LoyaltyObject, EventTicketObject, GenericObject, OfferObject oder GiftCardObject) über die Google-walletobjects-REST-API:
-
Feld-Updates (
PATCH): Das Aktualisieren von Punkteständen, Stufenbezeichnungen oder Textmodulen mitnotifyPreference: "NOTIFY_ON_UPDATE"veranlasst Google Wallet zur Benachrichtigung der Nutzerin oder des Nutzers. -
Eigene Nachrichtenobjekte (
addMessage): Broadcast-Meldungen hängen einMessage-Objekt (messageType: "TEXT_AND_NOTIFY") an das Google-Wallet-Objekt an — hierbei gilt Googles Anti-Spam-Limit von maximal 3 Push-auslösenden Nachrichten pro Pass innerhalb von 24 Stunden.
API-Endpunkte für Push-Benachrichtigungen (Push Notifications API)
Alle Push-Endpunkte sind unter /api/v1/push-notifications eingebunden (Push Notifications API; Passes API stellt ergänzend POST /api/v1/passes/:id/notifications und POST /api/v1/passes/sendpushnotifications bereit):
| Methode | Endpunkt-Pfad | DTO- / Payload-Regeln | Beschreibung |
|---|---|---|---|
| POST | /api/v1/push-notifications/passes/:id | request payload (pushNotificationText, <=85 Zeichen; akzeptiert Pass-id oder externalId) | Sendet sofort (oder optional zeitgesteuert) ein Update an alle registrierten Geräte eines einzelnen Passes. |
| POST | /api/v1/push-notifications/passes/:id/schedule | request payload (pushNotificationText, publicationDate Y-m-d H:i, publicationTimezone?) | Plant eine zukünftige Benachrichtigung für einen einzelnen Pass (id oder externalId). |
| POST | /api/v1/push-notifications/templates/:id/send | request payload (pushNotificationText) | Sendet sofort ein Push-Benachrichtigungs-Update an alle aktiven Pässe einer Vorlage (204 No Content). |
| POST | /api/v1/push-notifications/templates/:id | request payload | Plant eine Push-Benachrichtigung für alle Pässe einer Vorlage (segmentIds?, savedSearchIds?). |
| POST | /api/v1/push-notifications/segmentation | request payload (searchId, message <=85 Zeichen, priority?) | Sendet eine gezielte Push-Benachrichtigung an alle Pässe einer gespeicherten Such-UUID. |
| POST | /api/v1/push-notifications/batch | request payload (passIds[] max. 500, message, priority?) | Sendet sofort eine Push-Benachrichtigung an bis zu 500 explizit angegebene Pass-IDs. |
Beispiel: Gezielte Push-Benachrichtigung auf gespeicherter Suche (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"
}
Beispiel: Benachrichtigung für einzelnen Pass (externalId oder UUID)
POST /api/v1/push-notifications/passes/crm_usr_44910
{
"pushNotificationText": "Hi Marcus, you unlocked Gold Tier status!",
"pushNotificationHeaderText": "Artisan Roasters VIP"
}
Geofencing, iBeacons & Auslöser durch relevante Daten
Zusätzlich zu serverseitig gesendeten Updates unterstützen Pässe das passive Einblenden auf dem Sperrbildschirm, das im Vorlagen-Editor konfiguriert wird:
-
GPS-Standorte (
locations): Bis zu 10 GPS-Koordinaten (latitude,longitude,relevantText,maxDistance) je.pkpass(sowie in Google-Wallet-Standortlisten). -
Bluetooth Low Energy (
beacons): Bis zu 10 iBeacon-Proximity-UUIDs (proximityUUID,major,minor,relevantText) für Indoor-Auslöser im Einzelhandel unter iOS. -
Relevante Termine (
relevantDate): ISO-8601-Ereigniszeitstempel, der ein Event-Ticket oder eine Bordkarte automatisch vor Beginn auf dem Sperrbildschirm einblendet.
Erfahren Sie alle Details zur Auslieferungsmechanik unter Wallet-Pass-Benachrichtigungen, Geofencing-Funktionen sowie Geplante Updates & Kampagnen.
