# Sur votre application mobile

Facilitez l'installation des passes Wallet pour les utilisateurs directement depuis votre application mobile. Plutôt que de rediriger les utilisateurs ailleurs, votre application conserve le contrôle de l'identité, des droits et des données pendant que Wallet fournit un accès instantané aux passes hors ligne, les affiche au bon moment et les met à jour en temps réel. L'installation depuis l'application garantit une expérience rapide et pratique que les utilisateurs peuvent présenter en magasin ou lors d'un événement sans devoir rouvrir votre application.

<figure><img src="/files/e2df4818c15948d73b5668510481094448ed6e24" alt="Mobile App Add To Wallet SDK integration "><figcaption></figcaption></figure>

## Ajouter à Wallet depuis votre application mobile

Sur Apple Wallet et Google Wallet, le flux est cohérent. Votre application détecte si le pass est déjà installé, affiche le bon bouton « Ajouter à Wallet » et lance le flux d'enregistrement système si nécessaire.

{% hint style="info" %}
Votre application ne peut pas forcer l'installation. L'utilisateur doit toujours confirmer dans l'interface système.
{% endhint %}

### L'application native et Wallet sont complémentaires

Un wallet ne remplace pas votre application native. Ils répondent à des besoins différents et fonctionnent mieux ensemble. Wallet se concentre sur la présentation et la commodité. Il offre un accès rapide, une utilisation hors ligne et un stockage au niveau du système d'exploitation. Il peut aussi afficher les passes au bon moment (écran verrouillé, horaire, emplacement).

Votre application gère les comptes, l'authentification, les paramètres et l'ensemble des fonctionnalités. The Wallet Crew est l'endroit où les passes sont créés, actualisés et révoqués.

### Pourquoi inclure « Ajouter à Wallet » dans votre application

Ajouter le bouton réduit les frictions aux points de contact réels. Les utilisateurs installent le pass en une seule touche, puis le présentent sans rouvrir l'application. Cela compte quand la file est longue et que le réseau est faible.

Wallet conserve également le pass accessible pendant des mois, et il peut rester accessible même si l'application est ensuite désinstallée. Côté analytics, vous pouvez mesurer l'adoption et les performances des emplacements en étiquetant les installations avec `neo.src`.

<details>

<summary>Exemples concrets</summary>

Voici des exemples de ce qu'un pass peut débloquer une fois dans Wallet :

* Adhésion : « Livraison gratuite » sur chaque commande en ligne.
* Commerce de détail : « 10% de réduction sur tous les achats » pendant toute la saison.
* Billetterie d'événement : « Accès voie rapide » disponible pour cet événement.
* Billetterie d'événement : « Surclassement de siège » appliqué automatiquement lorsqu'il est disponible.
* Service : « Support prioritaire » disponible pour chaque soumission de ticket.

</details>

### Flux typique de bout en bout

Les détails de la plateforme diffèrent, mais le flux produit reste le même. L'utilisateur se connecte, appuie sur le bouton et votre application appelle votre backend. Votre backend récupère le pass approprié depuis The Wallet Crew et renvoie une charge d'installation qui correspond à l'appareil (Apple `.pkpass` ou un JWT Google). L'application ouvre ensuite l'interface d'enregistrement native du wallet, et vous suivez les installations via les événements Wallet Crew.

{% @mermaid/diagram content="sequenceDiagram
autonumber
actor User
participant App as Mobile app
participant Backend as Your backend
participant TWC as The Wallet Crew backend
participant Wallet as Apple/Google Wallet (system UI)

```
User->>App: Tap “Add to Wallet”
App->>Backend: Request install payload (user context + device)

Backend->>TWC: Resolve passId (lookup by external identifier)
TWC-->>Backend: passId

Backend->>TWC: Fetch install payload (passId + device + neo.src)
TWC-->>Backend: Apple .pkpass OR Google JWT

Backend-->>App: Return install payload
App->>Wallet: Launch system save flow
Wallet-->>User: Preview + confirmation
User->>Wallet: Confirm installation

Wallet->>TWC: Register installation (provider callback)
TWC-->>Backend: (Optional) Pass:Installed event (webhook)" %}
```

{% hint style="warning" %}
N'appelez jamais les API The Wallet Crew depuis le client mobile avec une clé API. Gardez les secrets uniquement sur votre backend.
{% endhint %}

### Apple Wallet vs Google Wallet

Votre application mobile utilise l'interface native du wallet, mais elle ne communique jamais directement avec The Wallet Crew à l'aide d'une clé API. Votre backend est le seul composant qui appelle **Le backend The Wallet Crew** pour résoudre `passId` et générer la charge d'installation.

{% tabs %}
{% tab title="Apple Wallet (iOS)" %}
Apple Wallet utilise un **bundle de pass signé**.

Votre backend demande une charge d'installation Apple au backend The Wallet Crew. Il renvoie un fichier téléchargeable `.pkpass`.

Votre application iOS télécharge le `.pkpass` et le présente avec PassKit. iOS affiche la feuille d'aperçu standard, et l'utilisateur confirme l'installation. Le pass est alors stocké localement sur l'appareil.

Utilisez l'étiquette « Ajouter à Apple Wallet ».&#x20;
{% endtab %}

{% tab title="Google Wallet (Android)" %}
Google Wallet utilise **objets liés au cloud**.

Votre backend demande une charge d'installation Google au backend The Wallet Crew. Il renvoie une charge Save, généralement un JWT, pour le flux d'enregistrement Google Wallet.

Votre application Android lance l'interface d'enregistrement Google. L'utilisateur confirme l'installation. Le pass est lié au compte Google de l'utilisateur et peut se synchroniser entre les appareils.

Utilisez l'étiquette « Ajouter à Google Wallet ».&#x20;
{% endtab %}
{% endtabs %}

## Comment l'implémenter

Votre tenant doit être prêt pour Apple Wallet et/ou Google Wallet, et vous devez déjà disposer d'un modèle et d'un flux d'émission. Vous avez également besoin d'un backend que votre application peut appeler, car les secrets et la recherche de pass doivent rester côté serveur.

#### Architecture de haut niveau

À un niveau élevé, votre backend résout un identifiant stable en un `passId`, puis appelle les API The Wallet Crew en utilisant `X-API-KEY`. Votre application ne reçoit que la charge d'installation spécifique au fournisseur et installe le pass en utilisant les API natives du wallet.

#### Étape par étape

{% stepper %}
{% step %}

### Créer une clé API (backend uniquement)

Créez une clé API dans la console d'administration.\
Utilisez le principe du moindre privilège.

Voir : [API Key](/docs/fr/configurer/platform/api-key.md)

Vous l'enverrez comme :

`X-API-KEY: <your_api_key>`
{% endstep %}

{% step %}

### Résoudre le passId sur votre backend

Utilisez votre propre identifiant stable.\
Exemples : ID de fidélité, ID client, ID de billet.

Appelez le point de terminaison de la liste des passes avec un filtre.

Exemple (recherche par `identifiers.ur.customerId`):

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

Adapter `filter[0].field` à votre propre clé d'identifiant.\
Les clés typiques ressemblent à `identifiers.<namespace>.<name>`.

Vous obtiendrez un tableau JSON contenant le `id`.\
Ce `id` est le `passId` que vous utiliserez ensuite.
{% endstep %}

{% step %}

### Générer une « charge d'installation » spécifique au fournisseur

Une fois que vous avez `passId`, demandez la charge pour l'appareil cible. Apple renvoie un fichier téléchargeable `.pkpass` et Google renvoie un jeton JWT. Un schéma d'endpoint typique ressemble à ceci :

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

{% hint style="info" %}
`neo.src` est utilisé pour le suivi et l'attribution.\
Format : `<medium>|<tag1>,<tag2>|<originUrl>`.
{% endhint %}
{% endstep %}

{% step %}

### Installer le pass depuis l'application

Utilisez les SDK natifs du wallet. Sur iOS, téléchargez le `.pkpass` et affichez l'interface « Ajouter à Apple Wallet ». Sur Android, transmettez le JWT au flux d'enregistrement Google Wallet.

Docs du fournisseur :

{% 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 et gérer les réinstallations

Utilisez les événements Wallet Crew pour mesurer l'adoption et les sources. En pratique, vous étiquetez chaque emplacement in-app avec `neo.src` (profil, paiement, intégration) et vous abonnez à `Pass:Installed` événements (webhook) ou interrogez l'adoption via Insights.
{% endstep %}
{% endstepper %}

## FAQ

<details>

<summary>Puis-je mettre la clé API dans l'application mobile ?</summary>

Non. Traitez les clés API comme des mots de passe. Placez les appels API derrière votre backend.

</details>

<details>

<summary>L'application peut-elle appeler directement le point d'extrémité « install payload » ?</summary>

Oui, si vous n'utilisez qu'un `passId` et que vous **ne** utilisez pas de clé API. C'est typiquement sûr car `passId` est opaque et non devinable.

Ne **ne** implémentez la recherche de pass (par ID client) sur le client.

</details>

<details>

<summary>Dois-je utiliser les flux wallet natifs ou le SDK web dans une application mobile ?</summary>

Dans une application mobile, préférez les **flux wallet natifs**. Ils offrent la meilleure UX et le moins de frictions. Ils évitent également les redirections web.

Utilisez la **SDK web** lorsque vous distribuez depuis des pages web, ou lorsque vous avez besoin d'un fallback QR pour desktop.

Voir : [Sur votre site web](/docs/fr/inscrire/on-your-website.md)

</details>

<details>

<summary>Comment intégrer « Ajouter à Wallet » dans une application Flutter ?</summary>

Ce modèle fonctionne bien dans Flutter. Gardez la recherche de pass et la génération de charge sur votre backend, puis déclenchez les flux d'enregistrement natifs iOS/Android depuis Flutter.

</details>

<details>

<summary>Comment intégrer « Ajouter à Wallet » dans une application React Native ?</summary>

Utilisez des modules natifs ou une bibliothèque wallet maintenue, puis lancez le flux d'enregistrement natif sur chaque plateforme. Un point de départ pratique est : <https://habr.com/en/articles/858858/>

</details>

<details>

<summary>Apple vs Google : que reçois-je ?</summary>

Apple Wallet renvoie un fichier `.pkpass` . Google Wallet renvoie un JWT. Votre backend doit choisir la bonne charge par appareil.

</details>

<details>

<summary>Que se passe-t-il si le pass n'existe pas encore ?</summary>

Créez-le d'abord, puis relancez le même flux pour récupérer le `passId` et la charge d'installation.

Commencez ici : [Comment créer des passes via l'API dans The Wallet Crew](/docs/fr/developper/guides/wallet/how-to-create-passes-via-api-in-the-wallet-crew.md)

</details>


---

# Agent Instructions: 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:

```
GET https://docs.thewalletcrew.io/docs/fr/inscrire/on-your-mobile-app.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.