Skip to content
Hilfecenter-Anleitung · Pass-VerteilungOnboarding-Phase 5
4 Min. LesezeitGeprüft 2026-11-16

Download-Links & PassFlow

Passen Sie OS-erkennende PassFlow-Downloadseiten, PassTour-Hinweise, PIN-Schutz, Download-Limits und Pause-Schutzschalter an.

In dieser Anleitung

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

Vergrößerter UI-Fokus1 / 2
Wichtige UI-Elemente

Ausgabelimits & Zugriffskontrollen (Zoom)

Konfigurieren Sie unbegrenzte oder begrenzte Ausgabe, Zugangswege, Wallet-Routing sowie Schutzregeln wie „Erneuten Download nach Aktivierung blockieren“ und Empfänger-Deduplizierung.

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

Verteilungszugriff und Link-Schutzschalter
Verteilungszugriff und Link-Schutzschalter
SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
SMART-DOWNLOAD-ROUTING & OS-ÜBERGABE
STUFE 01 EINGEHENDE HTTP-GET-ANFRAGE DES CLIENTS
GET/d/:slug | GET/download/:slug | GET/s/:token
STUFE 02 ZUGRIFFSSCHUTZ & TOKEN-VALIDIERUNGS-PIPELINE
1
Pass-/Vorlagenstatus prüfen (ACTIVE, passDownloadDeactivated = false)
2
Frist & Sperre prüfen (enableDownloadUntil, limitToOneActivePerPass)
3
PIN-Prüfung auswerten (?pin= / X-Wallet-Experience-Pin, sofern aktiviert)
iOS Safari / WebKit
STUFE 03A .pkpass-ZIP streamen
Content-Type: application/vnd.apple. pkpass
Android Chrome
STUFE 03B 302-Redirect auf
signiertes Google-
JWT: pay.google. com/gp/v/save/<..>
Desktop / In-App-WebView
STUFE 03C Gebrandete PassFlow-
Seite + QR-Code (GET/d/:slug/qr) +
E-Mail/SMS & PassTour

Dynamische User-Agent-Erkennung & Plattformverhalten

  1. 1
    iPhone & iPad (iOS Safari): Streamt das kryptografisch signierte .pkpass-Paket direkt mit dem MIME-Typ Content-Type: application/vnd.apple.pkpass und öffnet unmittelbar den nativen iOS-Dialog Zu Apple Wallet hinzufügen.
  2. 2
    Eingebettete iOS In-App-WebViews (Instagram, TikTok, Facebook, LinkedIn): Da eingebettete Social-Media-WebViews binäre Streams vom Typ application/vnd.apple.pkpass blockieren, erkennt Passinstance den In-App-User-Agent und blendet ein spezielles Safari-Übergabe-Overlay ein, das Nutzerinnen und Nutzer anweist, den Link in nativem Safari zu öffnen.
  3. 3
    Android-Geräte: Führt eine HTTP-302-Weiterleitung aus (oder zeigt den Ein-Klick-Button Zu Google Wallet hinzufügen), die auf https://pay.google.com/gp/v/save/<signed_jwt> verweist und das Cloud-Objekt (LoyaltyObject, EventTicketObject oder GenericObject) direkt in Google Wallet speichert.
  4. 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.

Ö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/*):

MethodeEndpunkt-PfadAuthentifizierungTechnische Beschreibung
GET/d/:slugÖffentlichEinstiegsrouter 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ÖffentlichGibt JSON-Metadaten (request payload), Branding-Tokens, PassTour-Schritte und Pass-Verfügbarkeit zurück.
GET/d/:slug/qrÖffentlichGeneriert eine scanbare QR-Code-Grafik mit der Smart-Download-URL.
GET/d/:slug/downloadÖffentlichFü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ÖffentlichKanonischer 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 über POST /api/v1/pass-projects/:id/validate-pin geprü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ährend pass 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:

JSON
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"
}
JSON
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.

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.