Skip to content
Hilfecenter-Anleitung · Wallet-Updates & Benachrichtigungen
3 Min. LesezeitGeprüft 2026-11-16

Push-Benachrichtigungen

Senden Sie Sperrbildschirm-Hinweise über changeMessage auf iOS sowie Android-Alerts ohne SMS-Kosten pro Nachricht.

In dieser Anleitung

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

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
APPLE-APNs- & GOOGLE-WALLET-PUSH-PROTOKOLL
STUFE 01 PHASE 1: INITIALE GERÄTEREGISTRIERUNG (iOS)
iPhone installiert .pkpassRuft Passinstance Apple Web Service auf:POST/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeId/:serial
Header: Authorization: ApplePass <authenticationToken>
Body: { "pushToken": "<apns_device_hex_token>" }
STUFE 02 PHASE 2: AUSLÖSER FÜR PUSH-BENACHRICHTIGUNG
POST/api/v1/push-notifications/passes/:id | /templates/:id/send | /segmentation
Apple APNs HTTP/2-Protokoll
STUFE 03A
1
Apple Push Delivery öffnet TLS-HTTP/ Stream zu api.push.apple.com:443 signiert mit Pass-Type-Zert.(topic)
2
Sendet leeren Payload {} (<4096 B)
3
iPhone wacht auf & fragt Liste ab:GET/v1/devices/...?passesUpdated
4
iPhone lädt neues .pkpass viaGET/v1/passes/:passTypeId/:serial
5
iOS vergleicht altes vs. neues pass.json & löst changeMessage "... %@" aus
Google Wallet REST-API-Protokoll
STUFE 03B
1
Google Wallet Sync führt PATCH oder addMessage auf walletobjects/v1/... aus
2
Setzt notifyPreference: NOTIFY_ON_UPDATE
3
Google Play Services zeigt native Android-Sperrbildschirm- Wallet-Benachrichtigung an

Apple Wallet Web Service (/v1) & changeMessage-Spezifikation

Passinstance implementiert die vollständige Apple-Wallet-Web-Service-Spezifikation unter dem globalen Routenpräfix /v1:

  1. 1
    Geräteregistrierung: POST /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber speichert das pushToken des Geräts und verknüpft es nach Prüfung des Headers Authorization: ApplePass <authenticationToken> mit der serialNumber des Passes.
  2. 2
    Stiller Wake-up-Push: Wird eine Benachrichtigung oder Kontostandsänderung ausgelöst, sendet Apple Push Delivery ein leeres JSON-Payload {} über HTTP/2 an das Apple-APNs-Gateway.
  3. 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 aktualisierter serialNumbers sowie ein neues lastUpdated-Tag erhält.
  4. 4
    Paketabruf & Sperrbildschirm-Hinweis: Für jede aktualisierte Seriennummer fordert iOS GET /v1/passes/:passTypeIdentifier/:serialNumber an (mit If-Modified-Since). iOS vergleicht die neu heruntergeladene pass.json mit der lokal gespeicherten Version. Jedes Feld, dessen value sich geändert hat und das einen changeMessage-String mit dem Platzhalter %@ definiert, erzeugt eine Sperrbildschirm-Meldung:
JSON
{
  "key": "points_balance",
  "label": "REWARD POINTS",
  "value": "1,450 pts",
  "changeMessage": "Your reward balance was updated to %@!"
}
  1. 5
    Geräteabmeldung & Fehlerprotokollierung: Löscht jemand einen Pass aus Apple Wallet, ruft iOS DELETE /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber auf. Etwaige clientseitige Parsingfehler meldet iOS an POST /v1/log.

Wichtig: In Apple Wallet muss changeMessage zwingend den Format-Platzhalter %@ enthalten (den iOS durch den neuen Feldwert value ersetzt), und der Wert value des 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 mit notifyPreference: "NOTIFY_ON_UPDATE" veranlasst Google Wallet zur Benachrichtigung der Nutzerin oder des Nutzers.
  • Eigene Nachrichtenobjekte (addMessage): Broadcast-Meldungen hängen ein Message-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):

MethodeEndpunkt-PfadDTO- / Payload-RegelnBeschreibung
POST/api/v1/push-notifications/passes/:idrequest 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/schedulerequest 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/sendrequest payload (pushNotificationText)Sendet sofort ein Push-Benachrichtigungs-Update an alle aktiven Pässe einer Vorlage (204 No Content).
POST/api/v1/push-notifications/templates/:idrequest payloadPlant eine Push-Benachrichtigung für alle Pässe einer Vorlage (segmentIds?, savedSearchIds?).
POST/api/v1/push-notifications/segmentationrequest payload (searchId, message <=85 Zeichen, priority?)Sendet eine gezielte Push-Benachrichtigung an alle Pässe einer gespeicherten Such-UUID.
POST/api/v1/push-notifications/batchrequest 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)

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

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

Weiterführende Produkt- & Entwicklerdoku

Bereit für Ihr erstes Wallet-Kartenprogramm?

Erstellen Sie Ihren Workspace, konfigurieren Sie Ihre Vorlage und testen Sie eine echte Karte in Apple Wallet und Google Wallet, bevor Sie skalieren.