Skip to content
Guida del Centro assistenza · Distribuzione passFase di onboarding 5
4 min di letturaVerificato 2026-11-16

Link di download e PassFlow

Personalizza pagine PassFlow smart con rilevamento OS, guide PassTour, protezione PIN, limiti e pausa di emergenza.

In questa guida

Guide visive interattive UI

Apri nella guida in 6 fasi

Esplora schermate reali della dashboard e dettagli ingranditi collegati a questa guida.

Focus UI ingrandito1 / 2
Elementi chiave dell'interfaccia

Limiti di emissione e controlli di accesso (Zoom)

Configura emissione illimitata o limitata, canali di accesso, routing Wallet e protezioni come il blocco del nuovo download dopo l'attivazione e la deduplicazione dei destinatari.

Panoramica e architettura degli endpoint intelligenti

Ogni pass emesso e ogni link di distribuzione del modello in Passinstance viene risolto da uno Smart Download Engine sensibile alla piattaforma (modello DownloadPage e Download Page API). Anziché distribuire link separati per Apple e Android, è sufficiente condividere un unico URL canonico (passAccessUrl, /d/:slug oppure /s/:token) che ispeziona dinamicamente l'header HTTP User-Agent del client, il contesto del browser e lo stato di sicurezza prima di fornire il payload Wallet appropriato.

Accesso alla distribuzione e interruttori di sicurezza link
Accesso alla distribuzione e interruttori di sicurezza link
FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
INSTRADAMENTO SMART DOWNLOAD E HANDOFF OS
FASE 01 RICHIESTA HTTP GET CLIENT IN INGRESSO
GET/d/:slug | GET/download/:slug | GET/s/:token
FASE 02 PIPELINE DI CONTROLLO ACCESSI E VALIDAZIONE TOKEN
1
Verifica stato Pass/Modello (ACTIVE, passDownloadDeactivated = false)
2
Controlla scadenza e blocco (enableDownloadUntil, limitToOneActivePerPass)
3
Valuta verifica PIN (?pin= / X-Wallet-Experience-Pin quando abilitata)
Safari iOS / WebKit
FASE 03A Stream ZIP .pkpass
Content-Type: application/vnd.apple. pkpass
Chrome Android
FASE 03B Redirect 302 a JWT
Google firmato pay.google.com/ gp/v/save/<jwt>
Desktop / WebView In-App
FASE 03C Rendering pagina PassFlow
brand + QR dinamico (GET/d/:slug/qr) +
E-mail/SMS e PassTour

Rilevamento dinamico dello User-Agent e comportamento per piattaforma

  1. 1
    iPhone e iPad (Safari su iOS): Trasmette direttamente il bundle .pkpass firmato crittograficamente con MIME type Content-Type: application/vnd.apple.pkpass, aprendo immediatamente la schermata nativa iOS Aggiungi ad Apple Wallet.
  2. 2
    WebView integrate in-app su iOS (Instagram, TikTok, Facebook, LinkedIn): Poiché le WebView dei social bloccano gli stream binari application/vnd.apple.pkpass, Passinstance rileva lo User-Agent in-app e mostra un overlay dedicato per guidare l'utente ad aprire il link nel browser nativo Safari.
  3. 3
    Dispositivi Android: Emette un redirect HTTP 302 (oppure mostra il pulsante one-tap Aggiungi a Google Wallet) verso https://pay.google.com/gp/v/save/<signed_jwt>, salvando l'oggetto cloud LoyaltyObject, EventTicketObject o GenericObject direttamente in Google Wallet.
  4. 4
    Browser desktop: Visualizza una pagina PassFlow responsive con il brand aziendale e un codice QR dinamico ad alto contrasto (GET /d/:slug/qr), insieme ai controlli self-service di inoltro via e-mail/SMS (POST /d/:slug/send-link-by-email, POST /d/:slug/send-link-by-sms) per trasferire in pochi secondi il pass sullo smartphone.

Importante: Quando l'Associazione a un solo dispositivo (limitToOneActivePerPass: true) è attiva su un modello o su un pass (sharingProhibited), lo smart link di download si blocca automaticamente non appena un dispositivo completa la prima registrazione Apple Wallet Web Service (POST /v1/devices/:deviceLibraryIdentifier/registrations/...) oppure il callback save di Google Wallet, impedendo la condivisione non autorizzata del link.

Le rotte pubbliche di risoluzione dei download sono esposte al di fuori del prefisso /api/v1 su Public Download Page e Public Pass Recovery API (/d/:slug/* e alias /download/:slug/*, oltre alle rotte autenticate di gestione sotto /api/v1/download-pages/*):

MetodoPercorso endpointAmbito AuthDescrizione tecnica
GET/d/:slugPubblicoRouter smart link d'ingresso; reindirizza i browser a /download/:slug o restituisce info JSON su richiesta; supporta ?pass=:passId, ?lang=, ?pin=.
GET/d/:slug/infoPubblicoRestituisce metadati JSON (request payload), token di branding, passaggi PassTour e disponibilità del pass.
GET/d/:slug/qrPubblicoGenera un'immagine codice QR scansionabile che codifica lo smart URL di download.
GET/d/:slug/downloadPubblicoEsegue il rilevamento dello User-Agent e consegna .pkpass (iOS) o redirect JWT Google Save (Android); rispetta ?pin= o X-Wallet-Experience-Pin.
POST/d/:slug/createPubblico (Rate-Limited)Emette un pass direttamente da una pagina di download (request payload: name, email?, phone?, additionalFields?).
POST/d/:slug/send-link-by-emailPubblico (Rate-Limited)request payload ({ email, passLink? }) — invia via e-mail il link di download all'utente dalle viste desktop.
POST/d/:slug/send-link-by-smsPubblico (Rate-Limited)request payload ({ phoneNumber, passLink? }) — invia il link di download tramite SMS in formato E.164.
POST/d/:slug/request-recoveryPubblico (Rate-Limited){ emailOrPhone } — invia un link di recupero rapido quando un cliente cambia telefono o smarrisce il proprio link.
GET/s/:tokenPubblicoSmart link canonico associato al serialNumber / token di un singolo pass.

Sicurezza dei token, protezione PIN e consegna secondaria

È possibile configurare protezioni granulari sugli accessi a livello di modello oppure su singola emissione pass:

  • Scadenza download (enableDownloadUntil): Imposta un timestamp "YYYY-MM-DD HH:mm" o ISO oltre il quale i link non ancora riscattati smettono di emettere nuovi pass, mantenendo attivi quelli già installati nei Wallet dei clienti.
  • Blocco su singolo dispositivo attivo (limitToOneActivePerPass): Blocca ulteriori download quando il pass ha già una registrazione dispositivo attiva.
  • Blocco con PIN (pin query param / header X-Wallet-Experience-Pin): Richiede ai titolari di sbloccare con PIN i link protetti e i bundle .pkpasses prima dell'installazione nel Wallet (verificato tramite POST /api/v1/pass-projects/:id/validate-pin su Wallet Experiences).
  • Sospensione di tutti i download (passDownloadDeactivated): Interruttore di emergenza nelle Impostazioni del modello che blocca immediatamente nuovi download su tutti i canali senza revocare i pass già installati sui dispositivi dei clienti.
  • Priorità di risoluzione pass (?pass=:passId): La risoluzione pubblica valuta nell'ordine la disponibilità specifica del pass (P1), le impostazioni predefinite della pagina di download (P2) e il fallback del workspace (P3), mentre pass bundle (bundleId) coordina i download .pkpasses tra tessere collegate.
  • Overlay opzionali PassTour: Guidano gli utenti alle prime armi con Apple Wallet e Google Wallet mediante istruzioni visive interattive (Guida PassTour).

Esempio: payload per consegna secondaria e recupero

Quando un cliente visualizza un pass su computer desktop oppure perde l'accesso al proprio pass Wallet, la pagina PassFlow invoca gli endpoint pubblici di azione:

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

Approfondisca la documentazione correlata su Distribuzione self-service, Consegna via e-mail e SMS e Trovare o recuperare il pass.

Documentazione prodotto e API correlata

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.