Overzicht: hoe pushmeldingen op het toegangsscherm van wallets werken
Apple Wallet en Google Wallet staan geen willekeurige losse pushpop-ups toe zoals zelfstandige native apps; in plaats daarvan worden meldingen op het toegangsscherm aangestuurd door strikte cryptografische wallet-protocollen die rechtstreeks gekoppeld zijn aan mutaties van veldwaarden op een geïnstalleerde pas. Zodra een pasveld verandert, tonen beide platformen een native melding op het toegangsscherm zonder sms-kosten per bericht.
Apple Wallet Web Service (/v1) & changeMessage-specificatie
Passinstance implementeert de volledige Apple Wallet Web Service-specificatie onder het globale routevoorvoegsel /v1:
-
1
Apparaatregistratie:
POST /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumberslaat hetpushTokenvan het apparaat op en koppelt dit aan hetserialNumbervan de pas na verificatie van de headerAuthorization: ApplePass <authenticationToken>. -
2
Stille wake-uppush: Wanneer een melding of saldowijziging wordt geactiveerd, stuurt
Apple Push Deliveryeen lege JSON-payload{}via HTTP/2 naar Apple's APNs-gateway. -
3
Serienummer-polling: Het iOS-apparaat ontwaakt op de achtergrond en roept
GET /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier?passesUpdatedSince=<tag>aan, en ontvangt een array van bijgewerkteserialNumbersen een nieuwelastUpdated-tag. -
4
Bundel ophalen & melding op toegangsscherm: Voor elk bijgewerkt serienummer vraagt iOS
GET /v1/passes/:passTypeIdentifier/:serialNumberop (metIf-Modified-Since). iOS vergelijkt de nieuw gedownloadepass.jsonmet de eerder opgeslagen versie. Elk veld waarvan devalueis gewijzigd en waarvoor eenchangeMessage-string met de tijdelijke aanduiding%@is gedefinieerd, activeert een banner op het toegangsscherm:
{
"key": "points_balance",
"label": "REWARD POINTS",
"value": "1,450 pts",
"changeMessage": "Your reward balance was updated to %@!"
}
-
5
Apparaatafmelding & foutlogboek: Wanneer een gebruiker een pas uit Apple Wallet verwijdert, roept iOS
DELETE /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumberaan. Eventuele client-side parseerfouten worden door iOS gemeld aanPOST /v1/log.
Belangrijk: In Apple Wallet moet
changeMessagede formaataanduiding%@bevatten (die iOS vervangt door de nieuwe veldwaardevalue), en moet devaluevan het veld daadwerkelijk verschillen van de vorige waarde op het apparaat. Tweemaal exact dezelfde tekstwaarde achter elkaar sturen activeert geen tweede iOS-toegangsschermmelding.
Google Wallet REST-updates & meldingsquota
Op Android werkt Passinstance het cloudpasobject (LoyaltyObject, EventTicketObject, GenericObject, OfferObject of GiftCardObject) bij via Google's walletobjects REST API:
-
Veldupdates (
PATCH): Het bijwerken van punten, niveaulabels of tekstmodules metnotifyPreference: "NOTIFY_ON_UPDATE"geeft Google Wallet signaal om de gebruiker te waarschuwen. -
Aangepaste berichtobjecten (
addMessage): Broadcastberichten voegen eenMessage-object (messageType: "TEXT_AND_NOTIFY") toe aan de Google Wallet-pas, onderworpen aan de antispam-limiet van Google van maximaal 3 meldinggevende pushberichten per pas binnen 24 uur.
API-endpoints voor pushmeldingen (Push Notifications API)
Alle pushendpoints zijn gekoppeld onder /api/v1/push-notifications (Push Notifications API; Passes API biedt daarnaast POST /api/v1/passes/:id/notifications en POST /api/v1/passes/sendpushnotifications):
| Methode | Endpointpad | DTO / payloadregels | Beschrijving |
|---|---|---|---|
| POST | /api/v1/push-notifications/passes/:id | request payload (pushNotificationText, <=85 tekens; accepteert pas-id of externalId) | Verstuurt onmiddellijk of optioneel op een toekomstig tijdstip een update naar alle geregistreerde apparaten van één pas. |
| POST | /api/v1/push-notifications/passes/:id/schedule | request payload (pushNotificationText, publicationDate Y-m-d H:i, publicationTimezone?) | Plant een toekomstige melding in voor één pas (id of externalId). |
| POST | /api/v1/push-notifications/templates/:id/send | request payload (pushNotificationText) | Verstuurt onmiddellijk een pushmeldingsupdate naar actieve passen van een sjabloon (204 No Content). |
| POST | /api/v1/push-notifications/templates/:id | request payload | Plant een pushmelding in voor alle passen van een sjabloon (segmentIds?, savedSearchIds?). |
| POST | /api/v1/push-notifications/segmentation | request payload (searchId, message <=85 tekens, priority?) | Verstuurt een gerichte pushmelding naar passen die overeenkomen met een UUID van een opgeslagen zoekopdracht. |
| POST | /api/v1/push-notifications/batch | request payload (passIds[] max. 500, message, priority?) | Verstuurt onmiddellijk een pushmelding naar maximaal 500 opgegeven pas-ID's. |
Voorbeeld: gerichte pushmelding via opgeslagen zoekopdracht (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"
}
Voorbeeld: melding voor één pas (externalId of UUID)
POST /api/v1/push-notifications/passes/crm_usr_44910
{
"pushNotificationText": "Hi Marcus, you unlocked Gold Tier status!",
"pushNotificationHeaderText": "Artisan Roasters VIP"
}
Geofencing, iBeacons & triggers voor relevante datums
Naast door de server gepushte updates ondersteunen passen passieve weergave op het toegangsscherm op het apparaat zelf, in te stellen in de Sjablooneditor:
-
GPS-locaties (
locations): Maximaal 10 GPS-coördinaten (latitude,longitude,relevantText,maxDistance) per.pkpass(en Google Wallet-locatiearrays). -
Bluetooth Low Energy (
beacons): Maximaal 10 iBeacon-nabijheids-UUID's (proximityUUID,major,minor,relevantText) voor retailtriggers binnenshuis op iOS. -
Relevante datums (
relevantDate): ISO 8601-evenementtijdstempel dat een evenementticket of instapkaart automatisch op het toegangsscherm toont zodra het evenement nadert.
Bekijk alle bezorgingsmechanieken op Wallet-pasmeldingen, Geofencing-mogelijkheden en Geplande updates & berichten.
