Skip to content
Helpcentrum-gids · Wallet-updates & meldingen
4 min leestijdGecontroleerd 2026-11-16

Pushmeldingen

Stuur meldingen op het toegangsscherm via changeMessage op iOS en Android zonder sms-kosten per bericht.

In deze gids

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.

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
APPLE APNs & GOOGLE WALLET-PUSHPROTOCOL
FASE 01 FASE 1: EERSTE APPARAATREGISTRATIE (iOS)
iPhone installeert .pkpassRoept Passinstance Apple Web Service aan:POST/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeId/:serial
Header: Authorization: ApplePass <authenticationToken>
Body: { "pushToken": "<apns_device_hex_token>" }
FASE 02 FASE 2: TRIGGER VOOR PUSHMELDINGVERZENDING
POST/api/v1/push-notifications/passes/:id | /templates/:id/send | /segmentation
Apple APNs HTTP/2-protocol
FASE 03A
1
Apple Push Delivery opent TLS HTTP/2 naar api.push.apple.com:443 getek. met Pass Type-certificaat (topic)
2
Stuurt lege payload {} (<4096 B)
3
iPhone ontwaakt & vraagt wijzigingen:GET/v1/devices/...?passesUpdated
4
iPhone haalt bijgewerkte .pkpass opGET/v1/passes/:passTypeId/:serial
5
iOS vergelijkt oude vs nieuwe pass.json & vuurt changeMessage
Google Wallet REST API-protocol
FASE 03B ream| | 1. Google Wallet Sync voert
PATCH of addMessage uit op walletobjects/v1/...
2
Stelt notifyPreference in: NOTIFY_ON_UPDATE
3
Google Play Services toont een native Android-walletmelding op het toegangsscherm

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

Passinstance implementeert de volledige Apple Wallet Web Service-specificatie onder het globale routevoorvoegsel /v1:

  1. 1
    Apparaatregistratie: POST /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber slaat het pushToken van het apparaat op en koppelt dit aan het serialNumber van de pas na verificatie van de header Authorization: ApplePass <authenticationToken>.
  2. 2
    Stille wake-uppush: Wanneer een melding of saldowijziging wordt geactiveerd, stuurt Apple Push Delivery een lege JSON-payload {} via HTTP/2 naar Apple's APNs-gateway.
  3. 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 bijgewerkte serialNumbers en een nieuwe lastUpdated-tag.
  4. 4
    Bundel ophalen & melding op toegangsscherm: Voor elk bijgewerkt serienummer vraagt iOS GET /v1/passes/:passTypeIdentifier/:serialNumber op (met If-Modified-Since). iOS vergelijkt de nieuw gedownloade pass.json met de eerder opgeslagen versie. Elk veld waarvan de value is gewijzigd en waarvoor een changeMessage-string met de tijdelijke aanduiding %@ is gedefinieerd, activeert een banner op het toegangsscherm:
JSON
{
  "key": "points_balance",
  "label": "REWARD POINTS",
  "value": "1,450 pts",
  "changeMessage": "Your reward balance was updated to %@!"
}
  1. 5
    Apparaatafmelding & foutlogboek: Wanneer een gebruiker een pas uit Apple Wallet verwijdert, roept iOS DELETE /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber aan. Eventuele client-side parseerfouten worden door iOS gemeld aan POST /v1/log.

Belangrijk: In Apple Wallet moet changeMessage de formaataanduiding %@ bevatten (die iOS vervangt door de nieuwe veldwaarde value), en moet de value van 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 met notifyPreference: "NOTIFY_ON_UPDATE" geeft Google Wallet signaal om de gebruiker te waarschuwen.
  • Aangepaste berichtobjecten (addMessage): Broadcastberichten voegen een Message-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):

MethodeEndpointpadDTO / payloadregelsBeschrijving
POST/api/v1/push-notifications/passes/:idrequest 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/schedulerequest 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/sendrequest payload (pushNotificationText)Verstuurt onmiddellijk een pushmeldingsupdate naar actieve passen van een sjabloon (204 No Content).
POST/api/v1/push-notifications/templates/:idrequest payloadPlant een pushmelding in voor alle passen van een sjabloon (segmentIds?, savedSearchIds?).
POST/api/v1/push-notifications/segmentationrequest 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/batchrequest 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)

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

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

Gerelateerde product- en ontwikkelaarsdocs

Klaar om uw eerste kaartprogramma te lanceren?

Maak uw workspace aan, configureer uw sjabloon en test een echte kaart in Apple Wallet en Google Wallet voordat u opschaalt.