> 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/download-pages.md).

# 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.

<details>

<summary><strong>Exemples concrets</strong></summary>

* 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.

</details>

### 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](/guides-enrolment/fr/inscription/enrolment-form.md) lorsqu’une inscription, des 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 [Sur votre application mobile](/guides-enrolment/fr/inscription/on-your-mobile-app.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 `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`.      |

{% hint style="info" %}
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`.
{% endhint %}

### 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.

<details>

<summary><strong>Exemples concrets</strong></summary>

* 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.

</details>

{% 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 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.
{% 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 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.

{% 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 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.

{% hint style="warning" %}
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.
{% endhint %}
{% endtab %}
{% endtabs %}

#### 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.

1. Confirmez qu’une page de carte unique affiche la carte attendue.
2. Confirmez qu’une page de liste de cartes renvoie toutes les cartes attendues.
3. Confirmez que les cartes inactives respectent le paramètre d’affichage choisi.
4. 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](/guides-enrolment/fr/inscription/enrolment-form.md) — collecter des données avant d’émettre une carte.
* [Sur votre site web](/guides-enrolment/fr/inscription/on-your-website.md) — ajouter des actions Wallet à un site web existant.
* [Par e-mail](/guides-enrolment/fr/inscription/via-email.md) — envoyer des liens de carte sécurisés aux clients existants.
* [Sur votre application mobile](/guides-enrolment/fr/inscription/on-your-mobile-app.md) — lancer l’installation native dans Wallet depuis une application.

### FAQ

<details>

<summary><strong>Quand faut-il utiliser une page de liste de cartes ?</strong></summary>

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.

</details>

<details>

<summary><strong>Une marque peut-elle utiliser plusieurs pages de téléchargement ?</strong></summary>

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

</details>

<details>

<summary><strong>Une page de téléchargement peut-elle inscrire un client ?</strong></summary>

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.

</details>

<details>

<summary><strong>Quelle méthode de recherche faut-il utiliser ?</strong></summary>

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.

</details>

<details>

<summary><strong>Les identifiants externes doivent-ils être signés ?</strong></summary>

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

</details>


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thewalletcrew.io/guides-enrolment/fr/inscription/download-pages.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.