Skip to content
Hilfecenter-Anleitung · Wallet-IntegrationenOnboarding-Phase 4
3 Min. LesezeitGeprüft 2026-11-16

Apple Wallet

Wie Passinstance .pkpass-Pakete erzeugt, mit PKCS#7 signiert, iOS/watchOS-Geräte registriert und Web-Service-Callbacks verarbeitet.

In dieser Anleitung

Prüfen Sie passende Dashboard-Bereiche, Steuerelemente und Zoom-Hinweise zu diesem Thema.

Vergrößerter UI-Fokus
Wichtige UI-Elemente

Dual-Wallet Live-Pass-Vorschau (Zoom)

Wechseln Sie im Vorschau-Panel zwischen Apple und Google, um Grafiken, Guthabenformatierung, QR-Code-Lesbarkeit und Feldausrichtung zu kontrollieren.

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

Live-Pass-Vorschau für Apple Wallet vs. Google Wallet
Live-Pass-Vorschau für Apple Wallet vs. Google Wallet
SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
APPLE-WALLET-.PKPASS-PAKETIERUNG & WEB-SERVICE
STUFE 01 PKPASS-ARCHIV-BUILDER (Apple Wallet Packager)
1
pass.json serialisieren (formatVersion: 1, rgb(r,g,b)-Farben, Felder)
2
Retina-Assets verpacken (icon.png, logo.png, strip.png @1x/@2x/@3x)
3
Lokalisierungspakete kompilieren (<lang>.lproj/pass.strings in UTF-8)
4
SHA-1-Prüfsummenverzeichnis berechnenmanifest.json schreiben
5
Abgetrennte PKCS#7-signature erzeugen (Pass-Type-Zert. + Apple WWDR G4/G6)
6
ZIP-Archiv komprimierenStream als Content-Type: application/vnd.apple.pkpass
STUFE 02 APPLE WALLET WEB SERVICE-PROTOKOLL (/v1)
Gerät registrieren: POST/v1/devices/:deviceLibId/registrations/:typeId/:sn
Update-Liste abrufen:GET/v1/devices/:deviceLibId/registrations/:typeId
Paket laden: GET/v1/passes/:passTypeId/:serialNumber
Pass abmelden: DELETE/v1/devices/:deviceLibId/registrations/:typeId/:sn
Client-Fehlerlog: POST/v1/log

Interner Aufbau eines .pkpass-Archivs

Ein Apple-Wallet-.pkpass-Bundle ist ein Standard-ZIP-Archiv mit fünf strukturellen Hauptkomponenten:

Datei / VerzeichnisFormat & KodierungAufgabe in Apple Wallet
pass.jsonUTF-8 JSONDefiniert 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.stringsUTF-8 Strings-TabelleLokalisierte Schlüssel-Wert-Übersetzungen (z. B. de.lproj/pass.strings, fr.lproj/pass.strings), passend zur Systemsprache des iPhones.
manifest.jsonUTF-8 JSONFlaches Verzeichnis, das jeden relativen Dateipfad im Bundle (außer manifest.json und signature) seinem 40-stelligen hexadezimalen SHA-1-Hash zuordnet.
signatureBinä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) als rgb(r, g, b)-Zeichenketten serialisiert werden. Passinstances apple-pass-field.serializer.ts wandelt Hex-Werte automatisch in rgb(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

JSON
{
  "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>:

MethodeEndpunkt-PfadHTTP-StatuscodesZweck
POST/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber201 Created, 200 OK, 401 UnauthorizedRegistriert das pushToken von iPhone oder Apple Watch für APNs-Updates und markiert den Pass als installiert.
GET/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier200 OK, 204 No ContentLiefert { serialNumbers: [...], lastUpdated: "<tag>" } für Pässe, die seit ?passesUpdatedSince= geändert wurden.
GET/v1/passes/:passTypeIdentifier/:serialNumber200 OK, 304 Not Modified, 401 UnauthorizedErzeugt und streamt das neueste signierte .pkpass-Paket nach einem APNs-Wake-up oder manuellem Pull-to-Refresh.
DELETE/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber200 OK, 401 UnauthorizedMeldet das Gerät ab, sobald der Pass aus Apple Wallet gelöscht wird.
POST/v1/log200 OKNimmt 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.

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.