Überblick: So funktioniert die Apple-Wallet-Integration
Passinstance generiert native Apple Wallet .pkpass-Pakete (Apple Wallet Packager), die vollständig der Apple PassKit-Paketspezifikation für iOS und watchOS entsprechen. Jeder Pass wird dynamisch als kryptografisch signiertes ZIP-Archiv zusammengestellt und mit dem MIME-Typ application/vnd.apple.pkpass ausgeliefert.

Interner Aufbau eines .pkpass-Archivs
Ein Apple-Wallet-.pkpass-Bundle ist ein Standard-ZIP-Archiv mit fünf strukturellen Hauptkomponenten:
| Datei / Verzeichnis | Format & Kodierung | Aufgabe in Apple Wallet |
|---|---|---|
pass.json | UTF-8 JSON | Definiert Pass-Stil (storeCard, coupon, eventTicket, boardingPass, generic), passTypeIdentifier, teamIdentifier, serialNumber, authenticationToken, webServiceURL, Felder, Barcodes, Standorte und das nfc-Dictionary. |
Visuelle Assets (.png) | PNG (@1x, @2x, @3x) | Bis zu 13 Vorlagen-Bildslots werden in die offiziellen Apple-PassKit-Dateinamen (icon.png, logo.png, strip.png, thumbnail.png, background.png, footer.png, artwork.png, venueMap.png) über alle Retina-Auflösungen hinweg überführt. |
<lang>.lproj/pass.strings | UTF-8 Strings-Tabelle | Lokalisierte Schlüssel-Wert-Übersetzungen (z. B. de.lproj/pass.strings, fr.lproj/pass.strings), passend zur Systemsprache des iPhones. |
manifest.json | UTF-8 JSON | Flaches Verzeichnis, das jeden relativen Dateipfad im Bundle (außer manifest.json und signature) seinem 40-stelligen hexadezimalen SHA-1-Hash zuordnet. |
signature | Binäres DER (PKCS#7) | Abgetrennte kryptografische PKCS#7-Signatur über manifest.json, erstellt mit dem Private Key Ihrer Apple Pass Type ID und verkettet zum Zwischenzertifikat Apple WWDR G4/G6. |
Wichtig: Apple Wallet verlangt zwingend, dass Farbwerte in
pass.json(backgroundColor,foregroundColor,labelColor) alsrgb(r, g, b)-Zeichenketten serialisiert werden. Passinstancesapple-pass-field.serializer.tswandelt Hex-Werte automatisch inrgb(r, g, b)um und entfernt Alpha-Kanäle, sodass iOS ein Paket während der Signatur- und Schemaprüfung niemals ablehnt.
Beispielstruktur einer pass.json-Datei
{
"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-Endpunkte (/v1)
Jeder Live-Pass enthält webServiceURL sowie ein mindestens 16-stelliges authenticationToken. iOS- und watchOS-Geräte kommunizieren direkt mit Passinstances /v1-Endpunkten über den HTTP-Header Authorization: ApplePass <authenticationToken>:
| Methode | Endpunkt-Pfad | HTTP-Statuscodes | Zweck |
|---|---|---|---|
| POST | /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber | 201 Created, 200 OK, 401 Unauthorized | Registriert das pushToken von iPhone oder Apple Watch für APNs-Updates und markiert den Pass als installiert. |
| GET | /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier | 200 OK, 204 No Content | Liefert { serialNumbers: [...], lastUpdated: "<tag>" } für Pässe, die seit ?passesUpdatedSince= geändert wurden. |
| GET | /v1/passes/:passTypeIdentifier/:serialNumber | 200 OK, 304 Not Modified, 401 Unauthorized | Erzeugt und streamt das neueste signierte .pkpass-Paket nach einem APNs-Wake-up oder manuellem Pull-to-Refresh. |
| DELETE | /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber | 200 OK, 401 Unauthorized | Meldet das Gerät ab, sobald der Pass aus Apple Wallet gelöscht wird. |
| POST | /v1/log | 200 OK | Nimmt Diagnose-Arrays { "logs": [...] } von iOS-Geräten entgegen, falls ein .pkpass die clientseitige Prüfung nicht besteht. |
Weitere technische Spezifikationen finden Sie unter Apple-Wallet-Plattform, Apple-Wallet-Zertifikate sowie Kontaktloses Apple-VAS-Protokoll.
