Überblick & Architektur intelligenter Endpunkte
Jeder ausgegebene Pass- und Vorlagen-Verteilungslink in Passinstance wird über eine plattformbewusste Smart Download Engine (DownloadPage-Modell und Download Page API) aufgelöst. Statt separate Links für Apple und Android zu verteilen, geben Sie eine einzige kanonische URL weiter (passAccessUrl, /d/:slug oder /s/:token), die dynamisch den HTTP-User-Agent des Clients, den Browser-Kontext sowie den Sicherheitsstatus auswertet, bevor sie das passende Wallet-Payload ausliefert.

Dynamische User-Agent-Erkennung & Plattformverhalten
-
1
iPhone & iPad (iOS Safari): Streamt das kryptografisch signierte
.pkpass-Paket direkt mit dem MIME-TypContent-Type: application/vnd.apple.pkpassund öffnet unmittelbar den nativen iOS-Dialog Zu Apple Wallet hinzufügen. -
2
Eingebettete iOS In-App-WebViews (Instagram, TikTok, Facebook, LinkedIn): Da eingebettete Social-Media-WebViews binäre Streams vom Typ
application/vnd.apple.pkpassblockieren, erkennt Passinstance den In-App-User-Agentund blendet ein spezielles Safari-Übergabe-Overlay ein, das Nutzerinnen und Nutzer anweist, den Link in nativem Safari zu öffnen. -
3
Android-Geräte: Führt eine HTTP-
302-Weiterleitung aus (oder zeigt den Ein-Klick-Button Zu Google Wallet hinzufügen), die aufhttps://pay.google.com/gp/v/save/<signed_jwt>verweist und das Cloud-Objekt (LoyaltyObject,EventTicketObjectoderGenericObject) direkt in Google Wallet speichert. -
4
Desktop-Browser: Rendert eine gebrandete, responsive PassFlow-Seite mit einem kontrastreichen dynamischen QR-Code (
GET /d/:slug/qr) sowie Self-Service-Optionen zum Weiterleiten per E-Mail oder SMS (POST /d/:slug/send-link-by-email,POST /d/:slug/send-link-by-sms), sodass Desktop-Besucher den Pass in Sekunden auf ihr Smartphone übertragen können.
Wichtig: Wenn Bindung an einzelnes Gerät (Single-Device Binding) (
limitToOneActivePerPass: true) auf einer Vorlage oder einem Pass (sharingProhibited) aktiviert ist, sperrt sich der Smart-Download-Link automatisch, sobald ein Gerät seine erste Apple-Wallet-Web-Service-Registrierung (POST /v1/devices/:deviceLibraryIdentifier/registrations/...) oder einen Google-Wallet-save-Callback abschließt — unbefugtes Weiterleiten des Links wird verhindert.
API-Endpunkte für Smart-Links & Download-Seiten
Öffentliche Download-Endpunkte sind außerhalb des Präfixes /api/v1 auf Public Download Page und Public Pass Recovery API eingebunden (/d/:slug/* und Alias /download/:slug/*, ergänzt durch authentifizierte Verwaltungsrouten unter /api/v1/download-pages/*):
| Methode | Endpunkt-Pfad | Authentifizierung | Technische Beschreibung |
|---|---|---|---|
| GET | /d/:slug | Öffentlich | Einstiegsrouter für Smart-Links; leitet Browser an /download/:slug weiter oder liefert auf Wunsch JSON-Infos; unterstützt ?pass=:passId, ?lang=, ?pin=. |
| GET | /d/:slug/info | Öffentlich | Gibt JSON-Metadaten (request payload), Branding-Tokens, PassTour-Schritte und Pass-Verfügbarkeit zurück. |
| GET | /d/:slug/qr | Öffentlich | Generiert eine scanbare QR-Code-Grafik mit der Smart-Download-URL. |
| GET | /d/:slug/download | Öffentlich | Führt die User-Agent-Erkennung aus und liefert .pkpass (iOS) oder die Google-Save-JWT-Weiterleitung (Android); berücksichtigt ?pin= bzw. X-Wallet-Experience-Pin. |
| POST | /d/:slug/create | Öffentlich (Rate-Limited) | Erstellt einen Pass direkt über eine Download-Seite (request payload: name, email?, phone?, additionalFields?). |
| POST | /d/:slug/send-link-by-email | Öffentlich (Rate-Limited) | request payload ({ email, passLink? }) — sendet den Download-Link aus der Desktop-Ansicht per E-Mail zu. |
| POST | /d/:slug/send-link-by-sms | Öffentlich (Rate-Limited) | request payload ({ phoneNumber, passLink? }) — versendet den Download-Link per SMS im E.164-Format. |
| POST | /d/:slug/request-recovery | Öffentlich (Rate-Limited) | { emailOrPhone } — sendet einen Magic-Recovery-Link, wenn eine Kundin oder ein Kunde das Smartphone wechselt oder den Link verloren hat. |
| GET | /s/:token | Öffentlich | Kanonischer Smart-Link, der an ein individuelles serialNumber / Pass-Token gebunden ist. |
Token-Sicherheit, PIN-Schutz & Zweitzustellung
Sie können detaillierte Zugriffsbeschränkungen entweder auf Vorlagenebene oder pro einzelner Pass-Ausgabe konfigurieren:
-
Download-Frist (
enableDownloadUntil): Erzwingt ein Datum samt Uhrzeit ("YYYY-MM-DD HH:mm"oder ISO-Zeitstempel), nach dem nicht abgerufene Download-Links keine neuen Pässe mehr ausgeben — während bereits installierte Pässe in Kunden-Wallets aktiv bleiben. -
Einzelgerät-Sperre (
limitToOneActivePerPass): Blockiert erneute Downloads, sobald für den Pass eine aktive Geräteregistrierung vorliegt. -
PIN-Schutz (
pin-Query-Parameter /X-Wallet-Experience-Pin-Header): Verlangt vor der Wallet-Installation die Eingabe einer PIN zum Entsperren geschützter Download-Links und.pkpasses-Bündel (wird auf Wallet Experiences überPOST /api/v1/pass-projects/:id/validate-pingeprüft). -
Alle Downloads pausieren (
passDownloadDeactivated): Notfall-Schutzschalter in den Vorlageneinstellungen, der neue Downloads über alle Kanäle hinweg sofort anhält, ohne bereits auf Kundengeräten installierte Pässe zu entwerten. -
Auflösungspriorität (
?pass=:passId): Die öffentliche Auflösung prüft pass-spezifische Verfügbarkeit (P1), Download-Seiten-Standards (P2) und Workspace-Fallback (P3), währendpass bundle(bundleId).pkpasses-Downloads über verknüpfte Karten hinweg koordiniert. -
Optionale PassTour-Overlays: Führt erstmalige Apple- und Google-Wallet-Nutzende mit interaktiven visuellen Schritt-für-Schritt-Hinweisen durch die Installation (PassTour-Leitfaden).
Beispiel: Zweitzustellung & Wiederherstellungs-Payloads
Wenn jemand eine Karte auf dem Desktop betrachtet oder den Zugriff auf das Wallet verloren hat, ruft die PassFlow-Seite die öffentlichen Aktions-Endpunkte auf:
POST /d/vip-gold-2026/send-link-by-email
{
"email": "alex.rivera@example.com",
"passLink": "https://app.passinstance.com/d/vip-gold-2026?pass=pass_01j8k9m2"
}
POST /d/vip-gold-2026/request-recovery
{
"emailOrPhone": "alex.rivera@example.com"
}
Lesen Sie verwandte Dokumentationen unter Self-Service-Verteilung, E-Mail- & SMS-Versand und Ihren Pass finden oder wiederherstellen.
