> 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/on-your-mobile-app.md).

# Sur votre application mobile

Ajoutez un bouton Ajouter à Wallet à une application iOS ou Android native, avec une recherche de Carte et des charges utiles d'installation fournies par un backend.

Une marque qui dispose déjà d’une application mobile peut permettre à ses clients d’enregistrer leur carte dans Apple Wallet ou Google Wallet sans quitter l’application. L’application reste responsable de la connexion, des données de compte et des droits, tandis que le portefeuille offre à la carte un accès hors ligne, l’affiche sur l’écran verrouillé au bon moment et la maintient à jour. Les clients peuvent ensuite présenter la carte dans un magasin ou lors d’un événement sans rouvrir l’application.

<figure><img src="https://1734667767-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlFokgwgJiwLXu7G8MVSJ%2Fuploads%2F6tPWU0PPHxbK1uKEfsfe%2FMobileAppSDK.png?alt=media&amp;token=ad91ba3d-1a55-4976-a8ac-0b16b5b1f6f8" alt="A mobile app screen showing an Add to Wallet button next to a loyalty card, and the resulting pass in the wallet"><figcaption><p>Le bouton Ajouter à Wallet se trouve dans l’application de la marque ; l’installation elle-même s’effectue dans la fenêtre du portefeuille système.</p></figcaption></figure>

<details>

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

* Un détaillant affiche un bouton Ajouter à Apple Wallet sur l’écran de carte de fidélité de son application, afin que les membres puissent scanner la carte à la caisse même sans réseau.
* Une application de billetterie propose Ajouter à Google Wallet sur l’écran de confirmation de commande, juste après le paiement.
* Une application d’adhésion suggère d’enregistrer la carte lors de l’intégration, puis conserve un bouton plus petit sur l’écran de profil.
* Chacun de ces emplacements comporte son propre `neo.src` tag, afin que la marque puisse comparer quel écran génère le plus d’installations.

</details>

### Pourquoi l’application et le portefeuille fonctionnent ensemble

Une Carte Wallet ne remplace pas l’application native ; les deux répondent à des besoins différents. L’application gère les comptes, l’authentification, les paramètres et l’ensemble des fonctionnalités. Le Wallet gère la présentation et la praticité : accès rapide, utilisation hors ligne, stockage au niveau du système d’exploitation et affichage opportun sur l’écran de verrouillage en fonction de l’heure ou de l’emplacement. The Wallet Crew se trouve derrière les deux, en créant, mettant à jour et révoquant les Cartes.

L’ajout du bouton aux bons points de contact supprime les frictions. Les clients enregistrent la Carte en un seul tap et la présentent plus tard sans ouvrir l’application, ce qui est important lorsque la file d’attente est longue et que le réseau est faible. La Carte reste également disponible dans le Wallet tant qu’elle est valide, même si l’application est ensuite désinstallée.

{% hint style="info" %}
Une application ne peut pas installer une Carte silencieusement. Le client confirme toujours dans la feuille système du Wallet.
{% endhint %}

### Comment fonctionne le flux

Le flux est le même sur les deux plateformes. Le client se connecte à l’application et appuie sur le bouton. L’application demande au backend de la marque une charge utile d’installation. Le backend trouve la Carte du client dans The Wallet Crew, en la créant si nécessaire, puis récupère la charge utile correspondant à l’appareil : un `.pkpass` fichier pour Apple Wallet ou un JWT pour Google Wallet. L’application transmet cette charge utile au Wallet natif, qui affiche un aperçu, puis le client confirme. Le Wallet enregistre ensuite l’installation auprès de The Wallet Crew, qui peut notifier le backend de la marque via un webhook.

{% @mermaid/diagram content="sequenceDiagram; autonumber; actor Customer; participant App as Mobile app; participant Backend as Brand backend; participant TWC as The Wallet Crew; participant Wallet as Apple or Google Wallet; Customer->>App: Tap Add to Wallet; App->>Backend: Request install payload (customer + platform); Backend->>TWC: Look up pass by identifier (API key); TWC-->>Backend: passId; Backend->>TWC: Download pass (passId, device, neo.src); TWC-->>Backend: .pkpass file or Google JWT; Backend-->>App: Install payload; App->>Wallet: Open system save sheet; Wallet-->>Customer: Preview; Customer->>Wallet: Confirm; Wallet->>TWC: Register installation; TWC-->>Backend: Pass:Installed webhook (optional)" %}

{% hint style="warning" %}
N’intégrez jamais de clé API dans une application mobile. Un binaire d’application peut être décompilé, et une clé divulguée donne accès à toutes les Cartes du locataire. Conservez la clé et la recherche de Carte sur le backend.
{% endhint %}

### Différences entre Apple Wallet et Google Wallet

Les deux Wallets reçoivent des charges utiles différentes, donc le backend choisit la charge utile de la plateforme que l’application signale.

{% tabs %}
{% tab title="Apple Wallet (iOS)" %}
Apple Wallet utilise un fichier de Carte signé. L'équipe Wallet renvoie un `.pkpass` fichier lorsque la Carte est téléchargée avec `device=apple`.

L'application iOS charge le fichier dans un `PKPass` objet et le présente avec le `PKAddPassesViewController`. iOS affiche la feuille d'aperçu standard, et une fois que le client confirme, la Carte est stockée sur l'appareil. Utilisez le **Ajouter à Apple Wallet** bouton (`PKAddPassButton`).
{% endtab %}

{% tab title="Google Wallet (Android)" %}
Google Wallet utilise des cartes stockées dans le compte Google du client. L'équipe Wallet renvoie un JWT lorsque la carte est téléchargée avec `device=google`.

L'application Android transmet ce JWT au flux d'enregistrement du SDK Android de Google Wallet. Une fois que le client confirme, la carte est liée à son compte Google et peut se synchroniser sur tous ses appareils. Utilisez l'outil officiel **Ajouter à Google Wallet** bouton.
{% endtab %}
{% endtabs %}

### Implémentez « Ajouter à Wallet » dans une application mobile

Avant de commencer, le locataire doit être configuré pour Apple Wallet, Google Wallet ou les deux, et un [modèle de Carte](/configure/fr/advanced-configuration/wallet/template-configuration/how-to-create-a-template.md) doit exister pour que les Cartes soient émises. La marque a aussi besoin d'un backend que l'application peut appeler, car la clé API et la recherche de Carte doivent rester côté serveur.

Le backend transforme un identifiant client stable en un `CarteId`, puis télécharge la Carte pour la bonne plateforme. L'application ne reçoit jamais que la charge utile spécifique à la plateforme.

{% stepper %}
{% step %}

### Créer une clé API pour le backend

Le backend s'authentifie auprès de l'équipe Wallet avec une clé API créée dans la console d'administration. Donnez à la clé uniquement les portées nécessaires à ce flux : `tenant.Carte:read` pour rechercher des Cartes, plus `tenant.Carte:write` si le backend crée également des cartes pour les nouveaux clients. Stockez la clé dans le coffre de secrets du backend et envoyez-la dans le `X-API-KEY` l'en-tête.
{% endstep %}

{% step %}

### Trouver la carte du client

Le backend recherche la carte à l'aide d'un identifiant qu'il connaît déjà, comme un numéro de fidélité, un ID client ou un ID de billet. Cet identifiant doit être celui stocké sur la carte lors de la création, sous une clé au format `<namespace>.<name>`. Le point de terminaison de liste le filtre sous la forme `identifiers.<namespace>.<name>`:

```bash
curl --globoff -X GET \
  'https://app.neostore.cloud/api/<tenantId>/passes?pageIndex=0&pageSize=10&filter[0].field=identifiers.<namespace>.<name>&filter[0].operator=equals&filter[0].value=<customerId>' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: <api_key>'
```

La réponse est un tableau JSON de cartes. Le `id` de la carte correspondante est le `CarteId` utilisé à l'étape suivante. Chaque carte comporte également un `providers` objet répertoriant les Wallet sur lesquels elle est déjà installée, que l'application peut utiliser pour afficher « Voir dans Wallet » au lieu de « Ajouter à Wallet ».

Si le tableau est vide, le client n'a pas encore de carte. Le backend en crée une avec le même identifiant :

```bash
curl -X POST \
  'https://app.neostore.cloud/api/<tenantId>/passes?passType=<passType>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: <api_key>' \
  -d '{ "identifiers": { "<namespace>.<name>": "<customerId>" } }'
```

Le corps de la réponse est le nouvel identifiant de carte, qui peut être utilisé directement comme `CarteId`. [Gérer le cycle de vie des cartes avec l'API](/developers-guides/fr/integration-guides/wallet/pass-lifecycle.md) couvre l'ensemble des options de création, et la [référence de l'API Carte](/api-reference/pass-management/pass.md) détaille chaque champ.
{% endstep %}

{% step %}

### Télécharger la charge utile d'installation

Avec le `CarteId`, le backend télécharge la carte pour la plateforme du client. Le `device` paramètre sélectionne la charge utile : `apple` renvoie le `.pkpass` fichier et `google` renvoie le JWT.

```
GET https://app.neostore.cloud/api/<tenantId>/passes/<passId>?device=apple&neo.src=<tracking>
```

Le `neo.src` paramètre attribue l'installation à un emplacement. Son format est `tags|medium|origin`: des tags séparés par des virgules, puis le canal, puis l'origine. Par exemple, `neo.src=loyalty-card|app|profile` étiquette les installations lancées depuis l'écran de profil de l'application. Utilisez une valeur distincte pour chaque écran qui affiche le bouton.

{% hint style="info" %}
Ce point de terminaison n'a pas besoin de clé API, car une `CarteId` est opaque et ne peut pas être devinée. Le backend peut donc renvoyer la `CarteId` à l'application et laisser l'application télécharger elle-même la charge utile. La recherche par identifiant client doit toujours rester côté backend.
{% endhint %}
{% endstep %}

{% step %}

### Ouvrir la feuille native Wallet

L’application transmet la charge utile au SDK Wallet de la plateforme. Sur iOS, il présente le `.pkpass` fichier avec PassKit. Sur Android, il transmet le JWT au flux d’enregistrement Google Wallet. Les deux plateformes documentent l’intégration :

{% embed url="<https://developer.apple.com/documentation/passkit/pkaddpassbutton/>" %}

{% embed url="<https://developers.google.com/wallet/retail/loyalty-cards/android>" %}
{% endstep %}

{% step %}

### Suivre les installations

Une fois qu’un client confirme, The Wallet Crew enregistre l’installation avec sa `neo.src` source. Les nombres d’installations par support et par source sont disponibles dans Insights, qui montre quels écrans de l’application performent le mieux. Pour réagir en temps réel, par exemple pour masquer le bouton ou mettre à jour la fiche client, abonnez le backend aux `Carte:Installed` et `Carte:Uninstalled` événements via un [webhook](https://docs.thewalletcrew.io/developers-guides/integration-guides/webhooks).
{% endstep %}
{% endstepper %}

### Valider l’intégration

Testez le flux sur un vrai iPhone et un vrai appareil Android avec un client de test avant la mise en production. Confirmez qu’un client existant reçoit sa carte existante plutôt qu’un doublon, qu’un nouveau client obtient une carte créée au premier appui, et que l’installation est signalée dans Insights sous la `neo.src` source attendue. Confirmez également qu’un second appui sur le bouton ouvre la même carte au lieu d’en créer une autre.

Les erreurs les plus courantes proviennent de l’étape de téléchargement. Un `400` signifie que le `device` paramètre est manquant ou invalide. Un `404` signifie qu’aucune carte n’a ce `CarteId`, souvent parce qu’un identifiant de test a été utilisé sur le mauvais locataire ou environnement. Un `409` avec `device=apple` signifie que le modèle de carte ne contient pas une image requise par Apple Wallet, comme l’icône, et doit être complété dans le modèle avant que la carte puisse être enregistrée.

### FAQ

<details>

<summary><strong>La clé API peut-elle être stockée dans l’application mobile ?</strong></summary>

Non. Traitez les clés API comme des mots de passe. Tout ce qui est livré dans une application peut être extrait, donc chaque appel nécessitant une clé doit passer par le backend de la marque.

</details>

<details>

<summary><strong>L’application peut-elle télécharger la carte directement depuis The Wallet Crew ?</strong></summary>

Oui, tant qu’elle n’utilise que le `CarteId` et aucune clé API. Le point de terminaison de téléchargement est public car une `CarteId` ne peut pas être deviné. La recherche d’une carte par identifiant client doit rester côté backend, car les identifiants clients sont souvent prévisibles.

</details>

<details>

<summary><strong>Que se passe-t-il lorsque le client n’a pas encore de carte ?</strong></summary>

La recherche renvoie un tableau vide. Le backend crée alors la carte avec `POST /api/{tenantId}/passes?passType={passType}` et le même identifiant, puis utilise l’id renvoyé pour télécharger la charge utile. Un nouveau client a donc besoin d’un appel backend de plus qu’un client existant.

</details>

<details>

<summary><strong>Est-ce que <code>PATCH</code> crée une carte lorsqu’aucune n’existe ?</strong></summary>

Non. `PATCH /api/{tenantId}/passes` met à jour uniquement une carte correspondant aux identifiants fournis et renvoie `404` lorsqu’aucune ne correspond. Utilisez la recherche, puis `POST` lorsque la carte est manquante.

</details>

<details>

<summary><strong>Une application mobile doit-elle utiliser les flux natifs Wallet ou le SDK du site web ?</strong></summary>

Les flux natifs Wallet offrent l’expérience la plus fluide dans une application, sans redirection web. Le SDK du site web convient aux pages web et aux parcours sur ordinateur qui nécessitent une solution de secours par code QR ; voir [Sur votre site web](/guides-enrolment/fr/inscription/on-your-website.md).

</details>

<details>

<summary><strong>Comment Add to Wallet est-il intégré dans une application React Native ?</strong></summary>

La partie backend ne change pas ; seule la dernière étape, l’ouverture de la feuille Wallet, nécessite un pont natif. La bibliothèque open source [react-native-wallet-manager](https://github.com/dev-family/react-native-wallet-manager) encapsule les deux Wallet derrière une seule API JavaScript. Sur iOS, elle nécessite la capacité Wallet dans Xcode ; sur Android, elle nécessite la `com.google.android.gms:play-services-pay` dépendance.

Chaque plateforme utilise une méthode différente. Sur iOS, `addCarteFromUrl(url)` prend l’URL de téléchargement de la carte avec `device=apple` et ouvre la feuille Apple Wallet. Sur Android, `addCarteToGoogleWallet(jwt)` prend le JWT renvoyé avec `device=google`. Évitez `addCarteFromUrl` sur Android, car cela ouvre un navigateur au lieu de la feuille Google Wallet. `canAddCartes()` vérifie que l’appareil prend en charge un Wallet avant l’affichage du bouton.

```javascript
import { Platform } from 'react-native';
import WalletManager from 'react-native-wallet-manager';

// carteId et googleJwt proviennent du backend de la marque
if (Platform.OS === 'ios') {
  const src = encodeURIComponent('loyalty-card|app|profile');
  await WalletManager.addCarteFromUrl(
    `https://app.neostore.cloud/api/${tenantId}/cartes/${carteId}?device=apple&neo.src=${src}`
  );
} else {
  await WalletManager.addCarteToGoogleWallet(googleJwt);
}
```

Cette bibliothèque est maintenue par un tiers, et non par The Wallet Crew. Vérifiez sa version actuelle et sa compatibilité avec la version React Native de l’application avant de l’adopter.

</details>

<details>

<summary><strong>Comment Add to Wallet est-il intégré dans une application Flutter ?</strong></summary>

La partie backend ne change pas. Dans l’application, Flutter appelle les flux natifs d’enregistrement de CarteKit et de Google Wallet, soit via un plugin Wallet maintenu, soit via un petit channel de plateforme pour chaque plateforme, en suivant la même séparation que ci-dessus : le `.pkpass` fichier sur iOS et le JWT sur Android.

</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/on-your-mobile-app.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.