Skip to content
Guida del Centro assistenza · Aiuto per i titolari di pass
4 min di letturaVerificato 2026-11-16

Risolvere problemi Wallet

Sblocca file .pkpass nei browser interni delle app social, allinea l'account Google e migliora la lettura QR.

In questa guida

Risolvere i problemi comuni di installazione e scansione dei pass

La maggior parte degli inconvenienti riscontrati dai titolari durante l'installazione del pass o la scansione alla cassa è causata dai browser integrati nelle app social, da discrepanze tra gli Account Google, dai controlli di sicurezza per il download (verifyDownloadPin / downloadUntil) o dai riflessi sullo schermo al punto cassa.

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
DIAGNOSTICA DEI CONTROLLI DI DOWNLOAD E BROWSER
FASE 01 IL TITOLARE APRE /d/:slug, /download/:slug O /s/:token
FASE 02A INTERCETTAZIONE WEBVIEW
Instagram/TikTok iOS blocca .pkpass
Invita a toccare
"Apri in Safari"
FASE 02B GESTIONE LINK SCADUTO
Link oltre downloadUntil
Invita l'utente a richiedere un nuovo link via POST/d/:slug/ request-recovery
FASE 02C CONTROLLO VERIFICA PIN
Richiede il PIN su /d/:slug e verifica verifyDownloadPin con ?pin= / header prima dello streaming

Riferimento diagnostico per i controlli di download del titolare del pass

Per diagnosticare il motivo per cui uno smart link (/d/:slug, /download/:slug o /s/:token) non apre immediatamente Apple Wallet o Google Wallet, verifichi lo stato della risposta e il comportamento del controllo di sicurezza:

Sintomo / Comportamento del controlloMeccanismo di backendCausa e soluzione per il titolare del pass
"Safari non può scaricare questo file" o schermata bianca su iPhoneRestrizione MIME della WKWebView integrataIl link è stato aperto all'interno di Instagram, TikTok, Facebook, LinkedIn o di un visualizzatore di anteprima email. Tocchi ... -> Apri nel browser di sistema (Safari) affinché iOS possa installare il file .pkpass firmato con bundleId.
Il pass richiede un PIN da 4 a 6 cifreverifyDownloadPin (Public Download Page)L'emittente ha abilitato la protezione tramite PIN per il download (pinVerified: false finché non viene soddisfatta). Inserisca il PIN nella pagina PassFlow (GET /d/:slug?pin=...) o tramite il modulo email/SMS per sbloccare i link del wallet.
Link scaduto (downloadUntil)Applicazione del timestamp downloadUntilIl token di download a tempo limitato è scaduto. Utilizzi il pulsante di recupero presente sulla pagina (POST /d/:slug/request-recovery con { emailOrPhone }) per ricevere un nuovo link.
Limite di dispositivi raggiunto (HTTP 403 Forbidden)limitToOneActivePerPass: trueIl pass è già attivo su un altro dispositivo. Rimuova prima il pass dal vecchio telefono oppure chieda all'emittente di reimpostare l'associazione del dispositivo.
Carta salvata su Android, ma assente nell'app Google WalletMancata corrispondenza del profilo Account GoogleChrome era connesso a un account Gmail secondario mentre l'app Google Wallet visualizza l'account principale. Cambi account toccando l'avatar in alto a destra in Google Wallet.

Sblocco di una pagina di download protetta da PIN

Quando un modello, un pacchetto Wallet Experience o una pagina di download richiede la verifica tramite PIN prima di trasmettere il file .pkpass firmato o l'URL di salvataggio Google, Public Download Page convalida il PIN tramite verifyDownloadPin (accettando l'header oppure il parametro di query ?pin= su /d/:slug e /d/:slug/download) e trattiene gli URL di download del wallet (error=pin_required / pinVerified: false) finché non viene inserito il PIN valido nell'interfaccia PassFlow.

Risolvere i problemi di scansione ottica del codice a barre e NFC alla cassa

Se uno scanner POS in negozio o la fotocamera dello smartphone all'ingresso ha difficoltà a leggere il pass al banco:

  1. 1
    Aumenti al massimo la luminosità dello schermo: Apple Wallet e Google Wallet aumentano automaticamente la retroilluminazione dello schermo quando viene mostrato un codice a barre, ma le modalità di risparmio energetico aggressive possono bloccare questo comportamento. Alzi manualmente la luminosità del telefono.
  2. 2
    Eviti le pellicole protettive oscurate per la privacy: i filtri polarizzati per la privacy riducono drasticamente il contrasto ad angoli inclinati sotto l'illuminazione dall'alto dei negozi. Tenga il telefono piatto e rivolto direttamente verso la finestra del lettore ottico (a 10–15 cm di distanza).
  3. 3
    Avvicini il telefono al simbolo contactless NFC: per i pass configurati con Apple VAS o Google Smart Tap (NFC), avvicini il bordo superiore dell'iPhone o la parte centrale posteriore dello smartphone Android direttamente all'icona delle onde contactless del lettore per 1 secondo e completi lo sblocco con Face ID / Touch ID / impronta digitale se richiesto.
  4. 4
    Utilizzi il numero di serie leggibile: ogni pass con codice a barre include un codice alternativo (serialNumber o ID socio) stampato direttamente sotto il grafico QR/PDF417/Code128, in modo che il personale possa cercare il pass tramite GET /api/v1/scans/pass?barcode=... qualora lo schermo sia incrinato.

Importante: Se visualizza un badge di scadenza o annullamento sul pass (pass status: VOIDED o EXPIRED), la carta è già stata riscattata o ha raggiunto la data di fine validità e verrà rifiutata dallo scanner del punto vendita (ALREADY_VOIDED / PASS_VOIDED_AFTER_SCAN o EXPIRED).

Ha ancora bisogno di assistenza? Consulti Aggiungere un pass al proprio wallet oppure ci contatti tramite Contattare il supporto.

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.