> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/guides-enrolment/fr/inscription/pages-de-telechargement.md).
# Pages de téléchargement
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](/guides-enrolment/fr/inscription/enrolment-form.md) lorsque l’inscription, les vérifications d’identité ou la collecte du consentement doivent avoir lieu en premier.
Utilisez [Sur votre site Web](/guides-enrolment/fr/inscription/on-your-website.md) pour intégrer un bouton Ajouter à Wallet dans une expérience Web existante. Utilisez [Dans votre application mobile](/guides-enrolment/fr/inscription/readme-1.md) 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`. |
{% hint style="info" %}
Définissez `requireValidRedirectId` à `true` lorsque les redirections de plateforme approuvées doivent contrôler l’accès. Sa valeur par défaut est `false`.
{% endhint %}
### 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.
{% tabs %}
{% tab title="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.
{% endtab %}
{% tab title="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.
{% hint style="warning" %}
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.
{% endhint %}
{% endtab %}
{% tab title="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.
{% hint style="warning" %}
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.
{% endhint %}
{% endtab %}
{% endtabs %}
#### 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](/guides-enrolment/fr/inscription/enrolment-form.md) — capturez les données avant d’émettre une carte.
* [Sur votre site Web](/guides-enrolment/fr/inscription/on-your-website.md) — ajoutez des actions Wallet à un site Web existant.
* [Via e-mail](/guides-enrolment/fr/inscription/via-email.md) — envoyez des liens de carte sécurisés aux clients existants.
* [Dans votre application mobile](/guides-enrolment/fr/inscription/readme-1.md) — 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](/guides-enrolment/fr/inscription/enrolment-form.md) 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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.thewalletcrew.io/guides-enrolment/fr/inscription/pages-de-telechargement.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.