Häufige Installations- und Scan-Probleme beheben
Die meisten Probleme beim Hinzufügen eines Passes oder beim Scannen an der Kasse werden durch eingebettete Social-Media-Browser, abweichende Google-Konten, Download-Schutzmechanismen (verifyDownloadPin / downloadUntil) oder Bildschirmspiegelungen am Kassenbereich verursacht.
Diagnose-Referenz für Download-Schutzschranken
Wenn Sie prüfen möchten, warum ein Smart-Link (/d/:slug, /download/:slug oder /s/:token) Apple Wallet oder Google Wallet nicht unmittelbar öffnet, kontrollieren Sie den Antwortstatus und die konfigurierte Schutzschranke:
| Symptom / Verhalten der Schutzschranke | Backend-Mechanismus | Ursache & Lösung für Passinhaber |
|---|---|---|
| „Safari kann diese Datei nicht laden“ oder leerer Bildschirm auf dem iPhone | Eingebettete WKWebView-MIME-Einschränkung | Der Link wurde in Instagram, TikTok, Facebook, LinkedIn oder einer E-Mail-Vorschau geöffnet. Tippen Sie auf ... -> In Systembrowser öffnen (Safari), damit iOS die über bundleId signierte .pkpass-Datei installieren kann. |
| Pass erfordert eine 4- bis 6-stellige PIN | verifyDownloadPin (Public Download Page) | Der Aussteller hat einen PIN-Schutz für den Download aktiviert (pinVerified: false bis zur Eingabe). Geben Sie die PIN auf der PassFlow-Seite (GET /d/:slug?pin=...) oder über die E-Mail-/SMS-Aufforderung ein, um die Wallet-Links freizuschalten. |
Link abgelaufen (downloadUntil) | Zeitstempel-Prüfung downloadUntil | Das zeitlich begrenzte Download-Token ist abgelaufen. Verwenden Sie die Wiederherstellungsschaltfläche auf der Seite (POST /d/:slug/request-recovery mit { emailOrPhone }), um einen neuen Link zu erhalten. |
Gerätelimit erreicht (HTTP 403 Forbidden) | limitToOneActivePerPass: true | Der Pass ist bereits auf einem anderen Gerät aktiv. Entfernen Sie den Pass zuerst von Ihrem alten Smartphone oder bitten Sie den Aussteller, die Gerätebindung zurückzusetzen. |
| Karte unter Android gespeichert, fehlt aber in der Google Wallet App | Abweichendes Google-Konto | Chrome war mit einem anderen Gmail-Konto angemeldet als die Google Wallet App. Wechseln Sie in Google Wallet über das Profilsymbol oben rechts zum passenden Konto. |
PIN-geschützte Download-Seite freischalten
Wenn eine Vorlage, ein Wallet-Experience-Paket oder eine Download-Seite vor dem Ausliefern der signierten .pkpass-Datei bzw. der Google-Speicher-URL eine PIN-Prüfung verlangt, validiert Public Download Page die PIN über verifyDownloadPin (über den Header oder den Query-Parameter ?pin= auf /d/:slug und /d/:slug/download) und hält die Wallet-Download-URLs zurück (error=pin_required / pinVerified: false), bis eine gültige PIN auf der PassFlow-Seite eingegeben wird.
Optisches Barcode- & NFC-Scannen an der Kasse korrigieren
Wenn ein Kassenscanner oder die Kamera eines Mitarbeiter-Smartphones Ihren Pass am Point of Sale schwer erfassen kann:
-
1
Bildschirmhelligkeit maximieren: Apple Wallet und Google Wallet erhöhen beim Anzeigen eines Barcodes automatisch die Displayhelligkeit; aggressive Energiesparmodi können dies jedoch überschreiben. Erhöhen Sie die Helligkeit bei Bedarf manuell.
-
2
Abgedunkelte Blickschutzfolien entfernen oder neigen: Polarisierte Sichtschutzgläser reduzieren den Kontrast in schrägen Winkeln unter Ladenbeleuchtung erheblich. Halten Sie das Smartphone flach und direkt vor das optische Scannerfenster (
10–15 cmAbstand). -
3
Direkt an das NFC-Kontaktlossymbol halten: Bei Pässen mit Apple VAS oder Google Smart Tap (
NFC) halten Sie die obere Kante Ihres iPhones bzw. die mittlere Rückseite Ihres Android-Smartphones 1 Sekunde lang direkt an das Kontaktlossymbol des Lesegeräts und bestätigen Sie bei Aufforderung mit Face ID / Touch ID / Biometrie. -
4
Lesbare Seriennummer nutzen: Jeder Barcode-Pass enthält einen Klartextcode (
serialNumberoder Mitglieds-ID) direkt unter der QR-/PDF417-/Code128-Grafik, sodass Mitarbeitende den Pass überGET /api/v1/scans/pass?barcode=...auch bei beschädigtem Display abrufen können.
Wichtig: Wenn auf Ihrem Pass das Kennzeichen für abgelaufen oder entwertet angezeigt wird (pass status:
VOIDEDoderEXPIRED), wurde die Karte bereits eingelöst oder hat ihr Ablaufdatum überschritten und wird vom Scanner abgewiesen (ALREADY_VOIDED/PASS_VOIDED_AFTER_SCANoderEXPIRED).
Benötigen Sie weitere Unterstützung? Lesen Sie Pass zur Wallet hinzufügen oder kontaktieren Sie uns über Support kontaktieren.
