Aperçu & architecture des points d'entrée intelligents
Chaque passe émis et chaque lien de distribution de modèle dans Passinstance est servi par un moteur de téléchargement intelligent adaptatif à la plateforme (modèle DownloadPage et contrôleur Download Page API). Plutôt que de diffuser des liens distincts pour Apple et Android, vous distribuez une URL canonique unique (passAccessUrl, /d/:slug ou /s/:token) qui inspecte dynamiquement l'en-tête HTTP User-Agent, le contexte du navigateur et les règles de sécurité avant de délivrer la charge utile adaptée.

Détection dynamique du User-Agent & comportement par plateforme
-
1
iPhone & iPad (iOS Safari) : Transmet directement l'archive
.pkpasssignée cryptographiquement avec le type MIMEContent-Type: application/vnd.apple.pkpass, ouvrant immédiatement la feuille modale native iOS Ajouter à Cartes. -
2
WebViews intégrées sur iOS (Instagram, TikTok, Facebook, LinkedIn) : Comme les navigateurs intégrés des réseaux sociaux bloquent les flux binaires
application/vnd.apple.pkpass, Passinstance détecte ceUser-Agentet affiche un écran d'accompagnement guidant le titulaire pour ouvrir le lien dans Safari. -
3
Appareils Android : Effectue une redirection HTTP
302(ou affiche un bouton Add to Google Wallet en un tap) vershttps://pay.google.com/gp/v/save/<signed_jwt>, provisionnant directement leLoyaltyObject,EventTicketObjectouGenericObjectdans Google Wallet. -
4
Navigateurs sur ordinateur : Affiche une page PassFlow responsive aux couleurs de votre marque avec un QR code dynamique à fort contraste (
GET /d/:slug/qr) ainsi que les options d'envoi autonome par e-mail ou SMS (POST /d/:slug/send-link-by-email,POST /d/:slug/send-link-by-sms) pour transférer le passe sur smartphone en quelques secondes.
Important : Lorsque le verrouillage sur un seul appareil (
limitToOneActivePerPass: true) est activé sur un modèle ou un passe (sharingProhibited), le lien de téléchargement intelligent se verrouille automatiquement dès qu'un premier appareil termine son enregistrement Apple Wallet Web Service (POST /v1/devices/:deviceLibraryIdentifier/registrations/...) ou son callbacksaveGoogle Wallet, empêchant tout partage non autorisé du lien.
Points d'entrée API des liens intelligents & pages de téléchargement
Les routes publiques de résolution sont exposées hors du préfixe /api/v1 via Public Download Page et Public Pass Recovery API (/d/:slug/* et l'alias /download/:slug/*, en complément des routes d'administration authentifiées sous /api/v1/download-pages/*) :
| Méthode | Chemin du point d'entrée | Portée d'authentification | Description technique |
|---|---|---|---|
| GET | /d/:slug | Public | Routeur principal du lien intelligent ; redirige les navigateurs vers /download/:slug ou sert les métadonnées JSON selon la requête ; accepte ?pass=:passId, ?lang=, ?pin=. |
| GET | /d/:slug/info | Public | Retourne les métadonnées JSON (request payload), les jetons visuels de marque, les étapes PassTour et la disponibilité du passe. |
| GET | /d/:slug/qr | Public | Génère une image QR code scannable encodant l'URL intelligente de téléchargement. |
| GET | /d/:slug/download | Public | Analyse le User-Agent et délivre le .pkpass (iOS) ou la redirection JWT Google Save (Android) ; tient compte de ?pin= ou X-Wallet-Experience-Pin. |
| POST | /d/:slug/create | Public (limité en débit) | Émet un passe directement depuis la page de téléchargement (request payload : name, email?, phone?, additionalFields?). |
| POST | /d/:slug/send-link-by-email | Public (limité en débit) | request payload ({ email, passLink? }) — envoie le lien de téléchargement par e-mail depuis la vue bureau. |
| POST | /d/:slug/send-link-by-sms | Public (limité en débit) | request payload ({ phoneNumber, passLink? }) — expédie le lien de téléchargement par SMS au format E.164. |
| POST | /d/:slug/request-recovery | Public (limité en débit) | { emailOrPhone } — envoie un lien magique de récupération lorsqu'un client change de téléphone ou perd son lien. |
| GET | /s/:token | Public | Lien intelligent canonique rattaché au serialNumber / jeton d'un passe individuel. |
Sécurité par jeton, protection par code PIN & envoi secondaire
Vous pouvez définir des garde-fous granulaires au niveau du modèle comme lors de l'émission d'un passe individuel :
-
Expiration du téléchargement (
enableDownloadUntil) : Appliquez un horodatage"YYYY-MM-DD HH:mm"ou ISO après lequel les liens non réclamés cessent de délivrer de nouveaux passes, tandis que les cartes déjà installées restent actives dans les portefeuilles clients. -
Verrouillage sur appareil unique (
limitToOneActivePerPass) : Bloque tout nouveau téléchargement dès qu'un enregistrement d'appareil actif existe sur le passe. -
Protection par code PIN (
pinen query param / en-têteX-Wallet-Experience-Pin) : Exigez des titulaires qu'ils déverrouillent les liens de téléchargement et bundles.pkpassesprotégés avant installation (vérifié viaPOST /api/v1/pass-projects/:id/validate-pinsur les Wallet Experiences). -
Mise en pause d'urgence (
passDownloadDeactivated) : Interrupteur d'arrêt immédiat dans les paramètres du modèle qui bloque tout nouveau téléchargement sur l'ensemble des canaux sans révoquer les cartes déjà installées. -
Priorité de résolution (
?pass=:passId) : La résolution publique évalue successivement la disponibilité spécifique du passe (P1), les valeurs par défaut de la page de téléchargement (P2) et les réglages de repli de l'espace de travail (P3), tandis quepass bundle(bundleId) coordonne les téléchargements.pkpassesentre cartes liées. -
Superpositions PassTour optionnelles : Accompagnez les nouveaux utilisateurs Apple et Google Wallet grâce à des instructions visuelles interactives (Guide PassTour).
Exemple : charges utiles d'envoi secondaire & de récupération
Lorsqu'un client consulte un passe sur ordinateur ou perd l'accès à sa carte wallet, la page PassFlow appelle les points d'entrée d'action publics :
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"
}
Consultez également la documentation associée sur Distribution en libre-service, Envoi par e-mail & SMS et Retrouver ou récupérer votre passe.
