Overzicht: hoe de Apple Wallet-integratie werkt
Passinstance genereert native Apple Wallet .pkpass-bundels (Apple Wallet Packager) die voldoen aan Apple's PassKit-pakketspecificatie voor iOS en watchOS. Elke pas wordt on the fly samengesteld als een cryptografisch ondertekend ZIP-archief en aangeboden met het MIME-type application/vnd.apple.pkpass.

Interne structuur van een .pkpass-archief
Een Apple Wallet .pkpass-bundel is een standaard ZIP-archief dat bestaat uit vijf structurele kernlagen:
| Bestand / map | Formaat en codering | Rol in Apple Wallet |
|---|---|---|
pass.json | UTF-8 JSON | Definieert de passtijl (storeCard, coupon, eventTicket, boardingPass, generic), passTypeIdentifier, teamIdentifier, serialNumber, authenticationToken, webServiceURL, velden, barcodes, locaties en het nfc-woordenboek. |
Visuele assets (.png) | PNG (@1x, @2x, @3x) | Tot 13 sjabloonafbeeldingsslots die worden gehydrateerd naar Apple PassKit-bestandsnamen (icon.png, logo.png, strip.png, thumbnail.png, background.png, footer.png, artwork.png, venueMap.png) over alle retina-resoluties. |
<lang>.lproj/pass.strings | UTF-8 Strings-tabel | Gelokaliseerde sleutel-waardevertalingen (bijv. de.lproj/pass.strings, fr.lproj/pass.strings) afgestemd op de systeemtaal van de iPhone. |
manifest.json | UTF-8 JSON | Een plat woordenboek dat elk relatief bestandspad in de bundel (met uitzondering van manifest.json en signature) koppelt aan de 40 tekens lange hexadecimale SHA-1-hash. |
signature | Binair DER (PKCS#7) | Losse cryptografische PKCS#7-handtekening van manifest.json, ondertekend met uw privésleutel voor de Apple Pass Type ID en gekoppeld aan het Apple WWDR G4/G6-tussencertificaat. |
Belangrijk: Apple Wallet vereist strikt dat kleurwaarden in
pass.json(backgroundColor,foregroundColor,labelColor) worden geserialiseerd alsrgb(r, g, b)-strings. Deapple-pass-field.serializer.tsvan Passinstance zet hex-waarden automatisch om naarrgb(r, g, b)en verwijdert alfakanalen, zodat iOS een bundel nooit afwijst tijdens handtekening- en schemaverificatie.
Voorbeeld van een pass.json-payloadstructuur
{
"formatVersion": 1,
"passTypeIdentifier": "pass.com.yourbrand.loyalty",
"serialNumber": "PI-8849-2026-X9",
"teamIdentifier": "9A8B7C6D5E",
"organizationName": "Phenix Roasters",
"description": "Phenix VIP Rewards Card",
"webServiceURL": "https://api.passinstance.com",
"authenticationToken": "b7f9e2c1a4d80931f6e5c2b8a1049d7e",
"foregroundColor": "rgb(255, 255, 255)",
"backgroundColor": "rgb(18, 24, 38)",
"labelColor": "rgb(148, 163, 184)",
"storeCard": {
"headerFields": [
{
"key": "tier",
"label": "TIER",
"value": "Gold"
}
],
"primaryFields": [
{
"key": "points",
"label": "POINTS BALANCE",
"value": 1450,
"changeMessage": "Your points balance updated to %@"
}
],
"backFields": [
{
"key": "support_link",
"label": "MEMBER PORTAL",
"value": "Visit https://yourbrand.com/member",
"attributedValue": "<a href=\"https://yourbrand.com/member\">Open Member Portal</a>"
}
]
},
"barcodes": [
{
"format": "PKBarcodeFormatQR",
"message": "PI-8849-2026-X9",
"messageEncoding": "iso-8859-1",
"altText": "PI-8849-2026-X9"
}
]
}
Apple Wallet Web Service-endpoints (/v1)
Elke actieve pas bevat een webServiceURL en een authenticationToken van minimaal 16 tekens. iOS- en watchOS-apparaten communiceren rechtstreeks met de /v1-endpoints van Passinstance via de HTTP-header Authorization: ApplePass <authenticationToken>:
| Methode | Endpoint-pad | HTTP-statuscodes | Doel |
|---|---|---|---|
| POST | /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber | 201 Created, 200 OK, 401 Unauthorized | Registreert de pushToken van de iPhone of Apple Watch voor APNs-updates en markeert de pas als geïnstalleerd. |
| GET | /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier | 200 OK, 204 No Content | Retourneert { serialNumbers: [...], lastUpdated: "<tag>" } voor passen die zijn gewijzigd sinds ?passesUpdatedSince=. |
| GET | /v1/passes/:passTypeIdentifier/:serialNumber | 200 OK, 304 Not Modified, 401 Unauthorized | Genereert en streamt de nieuwste ondertekende .pkpass-bundel wanneer het apparaat wordt geactiveerd door een APNs-push of handmatig omlaag vegen om te vernieuwen. |
| DELETE | /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber | 200 OK, 401 Unauthorized | Schrijft het apparaat uit wanneer de pashouder de pas verwijdert uit Apple Wallet. |
| POST | /v1/log | 200 OK | Ontvangt diagnostische { "logs": [...] }-arrays van iOS-apparaten als een .pkpass faalt bij validatie aan de clientzijde. |
Bekijk verdere technische specificaties bij Apple Wallet Platform, Apple Wallet-certificaten en Apple VAS-protocol voor contactloos gebruik.
