Pages de téléchargement

Configurez des pages de téléchargement hébergées qui permettent aux clients d’enregistrer une ou plusieurs Cartes Apple Wallet et Google Wallet.

Les pages de téléchargement sont des pages de distribution de cartes hébergées. Elles permettent aux clients d’enregistrer des cartes Apple Wallet ou Google Wallet sans remplir de formulaire d’inscription.

Exemples concrets

• Un e-mail de fidélité renvoie vers une seule carte client existante.
• Une confirmation de réservation affiche chaque billet d’une même commande.
• Une zone de compte répertorie les cartes et billets actifs d’un client.

Quand utiliser une page de téléchargement

Utilisez une page de téléchargement lorsque la carte existe déjà. L’URL de distribution résout la carte, puis affiche l’action Wallet pertinente.

Utilisez un Formulaire d'inscription lorsque l’inscription, les vérifications d’identité ou la collecte du consentement doivent avoir lieu en premier.

Utilisez Sur votre site Web pour intégrer un bouton Ajouter à Wallet dans une expérience Web existante. Utilisez Dans votre application mobile pour un parcours d’application native.

Configurer une page de téléchargement

Configurez les pages de téléchargement dans Wallet → Pages de téléchargement. Chaque page nécessite un slug d’URL unique et un type de page.

Utilisez des slugs distincts pour des parcours de distribution distincts. Par exemple, utilisez fidélité pour les cartes et billets pour les cartes d’événement.

Choisissez le type de page

Type de page	Clé de configuration	À utiliser lorsque
Carte unique	carte	Une seule URL de distribution résout une carte.
Liste de cartes	passList	Une seule URL de distribution résout plusieurs cartes.

Une page à carte unique affiche les actions Wallet pour la carte résolue. Une page à liste de cartes permet aux clients de sélectionner les cartes correspondantes.

Configurer une page à carte unique

Utilisez une carte page lorsque l’URL résout exactement une carte.

Propriété	Par défaut	Objectif
autoDownloadPass	false	Télécharge automatiquement le fichier de carte. Cela convient aux parcours de liens profonds mobiles.
passCreation.flow	—	S’exécute lorsqu’aucune carte n’existe. Le flux doit contenir un Carte élément.

Sans passCreation.flow, une carte manquante génère une erreur.

Configurer une page à liste de cartes

Utilisez une passList page lorsque l’URL peut résoudre plusieurs cartes. Une réservation avec plusieurs billets est un exemple courant.

Propriété	Par défaut	Objectif
allowDownloadAllPasses	true	Affiche une action pour télécharger chaque carte résolue.
showInactivePasses	false	Répertorie les cartes inactives sans autoriser le téléchargement.

Appliquer les paramètres partagés

Les deux types de page prennent en charge ces paramètres.

Propriété	Objectif
headerImage	Affiche une image en haut de la page. Utilisez une URL absolue ou un /public/ chemin.
theme	Remplace le thème de la page.
internationalization.resources	Définit des ressources de chaînes traduites, comme /locales/fields.
errorLayoutName	Envoie les erreurs irrécupérables vers un autre slug de page.
requireValidRedirectId	N’accepte qu’une redirection de plateforme connue lorsqu’il est défini sur true.

Définissez requireValidRedirectId à true lorsque les redirections de plateforme approuvées doivent contrôler l’accès. Sa valeur par défaut est false.

Construire une URL de distribution

Une URL de distribution ouvre une page de téléchargement hébergée. Les clients utilisent cette page pour enregistrer une carte dans Apple Wallet ou Google Wallet.

Utilisez des URL de distribution dans les e-mails, les messages SMS, les codes QR et les pages d’atterrissage de campagne. Choisissez la méthode de recherche en fonction des données disponibles lors de la génération du lien.

Choisissez la méthode de recherche avant de construire l’URL. Déterminez d’abord si le lien résout une carte connue ou un enregistrement client. Évaluez ensuite si l’identifiant est opaque, prévisible ou sensible. Enfin, confirmez où l’URL est générée et quel connecteur la traite.

Utilisez un ID de carte lorsque l’ID de carte attribué par la plateforme est déjà disponible. Utilisez un ID externe lorsqu’un identifiant détenu par l’entreprise doit résoudre une carte ou une liste de cartes. Utilisez un jeton d’authentification lorsqu’un backend crée un lien sécurisé et spécifique au destinataire.

Chaque URL de distribution a cette structure de base :

https://{host}/{tenant}/{layout}?{lookup parameter}

• {host} est un domaine personnalisé ou app.neostore.cloud.
• {tenant} est l’identifiant du tenant.
• {layout} est le slug de page de téléchargement configuré.
• {lookup parameter} identifie la carte ou le client.

La mise en page contrôle la page après la découverte de la carte. Elle peut afficher une carte, une liste de cartes ou un parcours d’inscription.

Exemples concrets

• Un e-mail de fidélité résout une carte client avec un identifiant CRM signé.
• Un code QR ouvre chaque billet lié à un identifiant de réservation.
• Un lien de campagne utilise un jeton d’authentification pour chaque destinataire.

ID de carte

Utilisez un ID de carte lorsque l’ID de carte attribué par la plateforme est déjà disponible. Cette valeur opaque identifie une carte connue. Elle n’a pas besoin de signature.

Cela convient aux communications client après la création de la carte. Stockez l’ID de carte lors de la création de la carte. Ajoutez-le ensuite à l’URL de distribution.

ID externe

Utilisez un ID externe lorsqu’un identifiant stable détenu par l’entreprise est disponible. La clé d’identifiant est libre. Les clés courantes incluent y2.customerId, comarch.customerId, et shopify.orderId.

Utilisez la même clé et la même valeur que celles stockées sur la carte. La méthode de sécurité dépend de l’identifiant et du connecteur. Un ID externe peut être protégé par une signature HMAC ou en incluant un secret dans l’URL de distribution.

Pour une recherche protégée par HMAC, ajoutez la signature au paramètre correspondant .hmac :

id.y2.customerId={customerId}&id.y2.customerId.hmac={hmac}

Utilisez HMAC-SHA256 avec le secret du tenant. Les secrets du tenant sont disponibles dans Paramètres → Clés API et secrets. Deux secrets rotatifs sont acceptés. Cela prend en charge la rotation des secrets sans interruption de distribution.

N’exposez pas un identifiant prévisible sans protection. Les numéros de client et de carte de fidélité peuvent être énumérés pour accéder à d’autres cartes.

Jeton d’authentification

Utilisez un jeton d’authentification lorsqu’un backend crée un lien signé pour chaque destinataire. Le jeton identifie le client avant l’ouverture de la page de téléchargement.

Générez le JWT sur un serveur avec l’API de jetons. La clé API nécessite le AuthenticationToken.Write scope. La réponse renvoie un JWT par jeu de revendications. Ajoutez ce JWT comme paramètre de neo.authToken URL de distribution.

Les jetons sont valides pendant 10 ans par défaut. Définissez validityDuration pour raccourcir cette période. Par exemple, 1.00:00:00 crée une période de validité d’un jour.

Générez les jetons uniquement sur un serveur. N’exposez jamais une clé API ni la logique de génération de jetons dans le code du navigateur ou les modèles d’e-mail.

Ajouter le suivi de campagne

Ajoutez neo.src pour enregistrer comment un client a atteint la page de téléchargement. Son format est tags|medium|origin.

• tags sont des catégories séparées par des virgules, comme email-campaign,loyalty.
• medium est un canal, comme email, sms, ou qr.
• origin est la source de référence. L’en-tête HTTP Referer est utilisé lorsqu’il est omis.

Par exemple, un e-mail de fidélité peut utiliser neo.src=email-campaign,loyalty|email|crm.

Valider le flux de distribution

Testez chaque page avec une URL de distribution qui cible des données connues.

1. Confirmez qu’une page à carte unique affiche la carte attendue.
2. Confirmez qu’une page à liste de cartes renvoie chaque carte attendue.
3. Confirmez que les cartes inactives suivent le paramètre d’affichage choisi.
4. Confirmez qu’un identifiant ou une signature modifiés ne résolvent pas de carte.

Choisissez le bon canal de distribution

Les pages de téléchargement hébergent l’expérience de distribution de cartes. Les autres canaux contrôlent l’endroit où cette expérience commence.

• Formulaire d'inscription — capturez les données avant d’émettre une carte.
• Sur votre site Web — ajoutez des actions Wallet à un site Web existant.
• Via e-mail — envoyez des liens de carte sécurisés aux clients existants.
• Dans votre application mobile — lancez l’installation native de Wallet depuis une application.

FAQ

Quand une page à liste de cartes doit-elle être utilisée ?

Utilisez une passList page lorsqu’une seule URL de distribution peut résoudre plusieurs cartes. Les confirmations de réservation et les zones de compte sont des exemples courants.

Une marque peut-elle utiliser plusieurs pages de téléchargement ?

Oui. Plusieurs pages peuvent utiliser le même type. Donnez à chaque page un slug distinct pour son parcours de distribution.

Une page de téléchargement peut-elle enregistrer un client ?

Non. Utilisez un Formulaire d'inscription lorsque l’identité du client doit être collectée avant l’émission de la carte.

Quelle méthode de recherche doit être utilisée ?

Utilisez un ID de carte lorsque la carte exacte est connue. Utilisez un identifiant externe signé pour les identifiants métier stables. Utilisez un jeton d’authentification lorsqu’un backend crée un lien sécurisé par destinataire.

Les identifiants externes doivent-ils être signés ?

Signez les identifiants prévisibles avec HMAC-SHA256. Les ID de carte opaques attribués par la plateforme ne nécessitent pas de signature.