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 carte client existante.
Une confirmation de réservation affiche chaque billet d’une même commande.
Un espace 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 appropriée.

Utilisez un Formulaire d’inscription lorsqu’une inscription, des 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 Sur 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 fidelite pour les cartes et billets pour les cartes d’événement.

Choisir le type de page

Type de page

Clé de configuration

À utiliser lorsque

Carte unique

carte

Une URL de distribution résout une carte.

Liste de cartes

passList

Une URL de distribution résout plusieurs cartes.

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

Configurer une page de 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 la carte. Convient aux parcours de liens profonds mobiles.

passCreation.flow

—

S’exécute lorsqu’aucune carte n’existe. Le flux doit contenir un élément Carte .

Sans passCreation.flow, l’absence de carte produit une erreur.

Configurer une page de liste de cartes

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

Propriété

Par défaut

Objectif

allowDownloadAllPasses

true

Affiche une action permettant de télécharger toutes les cartes résolues.

showInactivePasses

false

Répertorie les cartes inactives sans autoriser leur 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 chemin /public/ .

theme

Remplace le thème de la page.

internationalization.resources

Définit des ressources de chaînes traduites, telles que /locales/fields.

errorLayoutName

Envoie les erreurs irrécupérables vers le slug d’une autre page.

requireValidRedirectId

N’accepte une redirection de plateforme connue que lorsqu’il est défini sur true.

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

Créer 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 les URL de distribution dans les e-mails, les SMS, les codes QR et les pages de destination 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 créer 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 gère.

Utilisez un ID de carte lorsque la carte exacte de la plateforme est connue. 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é propre à chaque destinataire.

Chaque URL de distribution présente cette structure de base :

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

{host} est un domaine personnalisé ou app.neostore.cloud.
{tenant} est l’identifiant du locataire.
{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 avoir trouvé la carte. Elle peut afficher une carte, une liste de cartes ou un flux 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 associé à un identifiant de réservation.
Un lien de campagne utilise un jeton d’authentification pour chaque destinataire.

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 ne nécessite pas de signature.

Cela convient aux communications clients 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.

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

Utilisez la même clé et la même valeur 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 en tant que paramètre .hmac correspondant :

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

Utilisez HMAC-SHA256 avec le secret du locataire. Les secrets du locataire sont disponibles dans Paramètres → Clés API et secrets. Deux secrets rotatifs sont acceptés. Cela permet 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.

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 jeton. La clé API nécessite la portée AuthenticationToken.Write . La réponse renvoie un JWT par ensemble de revendications. Ajoutez ce JWT en tant que paramètre neo.authToken de l’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 ou une 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 la manière dont 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, telles que email-campaign,loyalty.
medium est un canal, tel que email, sms, ou qr.
origin est la source de référence. L’en-tête HTTP Referer est utilisé s’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 ciblant des données connues.

Confirmez qu’une page de carte unique affiche la carte attendue.
Confirmez qu’une page de liste de cartes renvoie toutes les cartes attendues.
Confirmez que les cartes inactives respectent le paramètre d’affichage choisi.
Confirmez qu’un identifiant ou une signature modifié ne résout pas de carte.

Choisir le bon canal de distribution

Les pages de téléchargement hébergent l’expérience de distribution de cartes. Les autres canaux déterminent où cette expérience commence.

Formulaire d’inscription — collecter des données avant d’émettre une carte.
Sur votre site web — ajouter des actions Wallet à un site web existant.
Par e-mail — envoyer des liens de carte sécurisés aux clients existants.
Sur votre application mobile — lancer l’installation native dans Wallet depuis une application.

FAQ

Quand faut-il utiliser une page de liste de cartes ?

Utilisez une passList page lorsqu’une URL de distribution peut résoudre plusieurs cartes. Les confirmations de réservation et les espaces 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 inscrire 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 faut-il utiliser ?

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 de la plateforme ne nécessitent pas de signature.

Mis à jour il y a 26 jours