Skip to content
Hilfecenter-Anleitung · Einführung in PassinstanceOnboarding-Phase 1
4 Min. LesezeitGeprüft 2026-11-16

Wie Passinstance funktioniert

Verfolgen Sie die gesamte Architektur von der Vorlagenerstellung und Signierung bis hin zu Scan, Push-Updates und Analysen.

In dieser Anleitung

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

Vergrößerter UI-Fokus
Wichtige UI-Elemente

Workspace-Dashboard — Live-KPIs & Trends (Zoom)

Nach dem Go-live „Active in Wallets“, „Removed from Wallets“, „Not Installed“ sowie Erstellungs- und Registrierungstrends verfolgen.

Überblick

Passinstance automatisiert den gesamten Lebenszyklus digitaler Pässe — vom Design über die kryptografische Paketierung, die Multi-Channel-Verteilung und die Validierung am Point of Sale bis hin zur stillen Push-Synchronisierung. Durch die Trennung von visuellem Layout, Geschäftslogik-Mechaniken und Gerätekommunikationsprotokollen liefert die Plattform ein einheitliches Erlebnis über die Ökosysteme von iOS und Android hinweg.

Durchgängiger technischer Ablauf

Das folgende Sequenzdiagramm beschreibt den End-to-End-Ablauf von der Vorlagenerstellung bis zur Wallet-Synchronisierung in Echtzeit:

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
END-TO-END-PASS-LEBENSZYKLUS
BETEILIGTE SYSTEMKOMPONENTEN
P1 Admin / API-Client
P2 Passinstance Core API
P3 Apple / Google Cloud
P4 Kundengerät
SCHRITT 1 ANFRAGE / AKTION POST/api/v1/templates
›
(Layout & Mechaniken)
SCHRITT 2 ANFRAGE / AKTION POST/api/v1/passes
SCHRITT 3 ANFRAGE / AKTION Sign .pkpass (PKCS#7)
SCHRITT 4 ANFRAGE / AKTION Google JWT erzeugen
›
Download-URL zurück
›
(https://app.passinstance.com/d/:slug oder /p/:passId)
SCHRITT 5 ANFRAGE / AKTION Kundin/Kunde öffnet Smart-Download-Link
›
(Browser erkennt OS)
SCHRITT 6 ANTWORT Gerät registriert (POST/v1/devices)
›
(Apple pushToken in Passinstance database gespeichert)
SCHRITT 7 ANFRAGE / AKTION Scan an der Kasse / am POS (POST/api/v1/scans)
›
(Header: x-scanner-key, Body: { scannedBarcodeValue })
SCHRITT 8 ANFRAGE / AKTION Mechanik ausführen
›
(Stempel/Punkte erhöhen)
SCHRITT 9 ANFRAGE / AKTION Stillen Push senden
›
(Leerer APNs-Payload)
SCHRITT 10 ANFRAGE / AKTION Stilles APNs-Wakeup
SCHRITT 11 ANTWORT Aktualisierten Pass abrufen (GET/v1/passes)
SCHRITT 12 ANFRAGE / AKTION Frisches .pkpass ausliefern
›
(Nativer Sperrbildschirm
›
Hinweis „Stand: %@“)

Technischer Lebenszyklus Schritt für Schritt

1. Vorlagenerstellung & Versionierung

Jeder Pass entsteht auf Basis eines Template-Datensatzes. Passinstance verwendet eine Single-Table-Versionierung, die über TemplateRowKind (PRODUCTION, PUBLISHED, ARCHIVED, DRAFT) und template status (DRAFT, PUBLISHED, ARCHIVED, DEPRECATED, UNDER_REVIEW, DELETING, DELETED) gesteuert wird. Änderungen im Entwurf bleiben in einer DRAFT-Revision isoliert, bis im Dashboard oder über die API POST /api/v1/templates/:id/publish aufgerufen wird. Dadurch wird der Entwurf zur kanonischen PRODUCTION-Basiszeile hochgestuft, während unveränderliche PUBLISHED- und ARCHIVED-Historien-Snapshots erhalten bleiben. Vor der Veröffentlichung prüft die Plattform über GET /api/v1/templates/:id/publish-risk-check kritische Feldänderungen und ermittelt, wie viele aktive Pässe aktualisiert werden.

2. Kryptografische Signierung, Artefaktstatus & Pass-Ausgabe

Beim Erzeugen eines Pass-Datensatzes (POST /api/v1/passes) löst die Pass-Erstellung templateId über resolvePassCreationTemplateId auf die produktive Basiszeile auf, verknüpft eine optionale mandantenweit eindeutige externalId, berücksichtigt den optionalen HTTP-Header Idempotency-Key (idempotencyKey) und initialisiert appleArtifactStatus sowie googleArtifactStatus (ArtifactStatus: NOT_GENERATED -> GENERATING -> READY \| FAILED \| INVALIDATED):

  • Apple Wallet: Beim Download bündelt Apple Wallet Packager die pass.json, bis zu 13 Bild-Slots (image asset slot inklusive @2x- und @3x-Retina-Varianten) sowie lokalisierte pass.strings in ein .pkpass-ZIP-Archiv, berechnet die Hashwerte in manifest.json und signiert das Manifest mit einer abgetrennten PKCS#7-Signatur mithilfe Ihres Apple Pass Type ID- und des Apple WWDR-Zertifikats. Mehrere zusammengehörige Pässe mit derselben bundleId (Pass.bundleId) können gemeinsam als .pkpasses-Archiv ausgeliefert werden.
  • Google Wallet: Das Backend synchronisiert Klassendefinitionen (LoyaltyClass, EventTicketClass, GenericClass usw.) mit den Google-Wallet-REST-APIs und signiert eine RS256-JWT-Save-URL (https://pay.google.com/gp/v/save/:jwt).

Passinstance vergibt kanonische Smart-Präsentations-URLs (https://app.passinstance.com/d/:slug, https://app.passinstance.com/p/:passId oder /s/:token auf API-/Vanity-Hosts). Beim Aufruf durch Endkundinnen und Endkunden gilt:

  • Öffentlicher Download-Endpunkt (GET /d/:slug/download) erkennt den User-Agent automatisch:

- iOS Safari erhält eine HTTP-Antwort mit dem MIME-Typ application/vnd.apple.pkpass, wodurch direkt der native Apple-Wallet-Hinzufügedialog geöffnet wird. - Android Chrome wird auf https://pay.google.com/gp/v/save/:jwt weitergeleitet und startet Google Wallet. - Desktop-Browser rendern die PassFlow-Downloadseite mit einem kontrastreichen QR-Code (GET /d/:slug/qr) sowie optionalem E-Mail-/SMS-Selbstversand.

4. Geräteregistrierung & Web-Service-Handshake

Sobald der Pass in Apple Wallet gespeichert wird, initiiert das iOS-Gerät das offizielle Apple-Wallet-Web-Service-Protokoll:

  • Es sendet POST /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber mit dem Header Authorization: ApplePass <authenticationToken>.
  • Passinstance validiert das Token, speichert das pushToken des Geräts in der Datenbank und überführt den Pass-Status von AWAITING_OPT_IN nach ACTIVE.

5. POS-Validierung & Ausführung von Mechaniken

An der Kasse oder beim Einlass scannt das Personal den Pass mit der App Passinstance Scanner oder einem integrierten Kassensystem:

  • Eine Anfrage wird an POST /api/v1/scans gesendet, authentifiziert über x-scanner-key.
  • Der Pass Mechanics Engine wertet die aktiven Regeln aus (z. B. Stempel gutschreiben, Prepaid-Guthaben abbuchen, Einmal-Coupons entwerten oder tägliche Anwesenheitsbeschränkungen prüfen).

6. Stille Cloud-Push-Synchronisierung

Wenn sich Pass-Daten ändern:

  • Passinstance sendet ein leeres JSON-Payload {} über HTTP/2 an die Apple-APNs-Server.
  • Das Apple-Gerät wacht still im Hintergrund auf, fragt GET /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier?passesUpdatedSince=<tag> ab und lädt das aktualisierte .pkpass-Paket herunter.
  • Jedes Feld, das mit einer changeMessage inklusive Platzhalter %@ konfiguriert ist, löst eine native iOS-Sperrbildschirm-Benachrichtigung aus.
  • Parallel dazu sendet Passinstance eine REST-PATCH-Anfrage an den Google-Wallet-Endpunkt walletobjects, um die Android-Karte in Echtzeit zu aktualisieren.
Dashboard-Übersicht mit Trends und KPIs
Dashboard-Übersicht mit Trends und KPIs

Zentrale API-Endpunkte & HTTP-Methoden

Endpunkt-PfadHTTP-MethodeAuthentifizierungFunktion
/api/v1/templatesPOSTBearer / API KeyNeue Pass-Vorlagendefinition erstellen
/api/v1/templates/:id/publishPOSTBearer / API KeyEntwurfsvorlage als produktive Version veröffentlichen
/api/v1/passesPOSTBearer / API KeyNeuen Pass mit benutzerdefinierten Feldwerten ausgeben
/api/v1/passes/:idPATCHBearer / API KeyBestehende Pass-Attribute aktualisieren und Push einreihen
/api/v1/scansPOSTx-scanner-keyPass-Barcode validieren, Mechanik ausführen, Scan protokollieren
/v1/devices/...POSTApplePass <token>Callback zur Apple-Wallet-Geräteregistrierung

Wichtig: Updates in Apple Wallet erfolgen Pull-basiert: Passinstance überträgt keine Pass-Daten innerhalb der APNs-Benachrichtigung. Stattdessen weist ein leeres APNs-Wake-up-Signal das Apple-Gerät an, das aktuelle signierte .pkpass-Paket sicher von den Passinstance-Servern abzurufen.

Entdecken Sie den vollständigen 6-Phasen-Onboarding-Leitfaden oder lesen Sie unsere API-Architektur.

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.