Dans votre application mobile
Ajouter « Ajouter à Wallet » dans une application native à l’aide de charges utiles côté serveur pour Apple Wallet et Google Wallet.
Facilitez l’installation de Cartes Wallet directement depuis votre application mobile. Au lieu de rediriger les utilisateurs ailleurs, votre application garde le contrôle de l’identité, des droits et des données, tandis que Wallet offre un accès instantané aux Cartes hors ligne, les affiche au bon moment et les met à jour en temps réel. L’installation dans l’application garantit une expérience rapide et pratique que les utilisateurs peuvent présenter en magasin ou lors d’un événement sans avoir à rouvrir votre application.
Ajouter à Wallet depuis votre application mobile
Sur Apple Wallet comme sur Google Wallet, le flux est cohérent. Votre application détecte si la Carte est déjà installée, affiche le bon bouton « Ajouter à Wallet », et lance le flux d’enregistrement système lorsque c’est nécessaire.
Votre application ne peut pas forcer l’installation. L’utilisateur doit toujours confirmer dans l’interface système.
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 praticité. Il offre un accès rapide, une utilisation hors ligne et un stockage au niveau du système d’exploitation. Il peut également afficher les Cartes au bon moment (écran verrouillé, heure, localisation).
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 Cartes sont créées, actualisées et révoquées.
Pourquoi inclure « Add to Wallet » dans votre application
Ajouter le bouton réduit les frictions aux points de contact réels. Les utilisateurs installent la Carte en une seule pression, puis la présentent sans rouvrir l’application. Cela compte quand la file est longue et que le réseau est faible.
Wallet garde aussi la Carte accessible pendant des mois, et elle peut le rester même si l’application est désinstallée plus tard. Côté analytique, vous pouvez mesurer l’adoption et la performance des emplacements en étiquetant les installations avec neo.src.
Exemples concrets
Voici des exemples de ce qu’une Carte peut débloquer une fois qu’elle est 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 événementielle : « Entrée coupe-file » disponible pour cet événement.
Billetterie événementielle : « Surclassement de siège » appliqué automatiquement lorsqu’il est disponible.
Service : « Assistance prioritaire » disponible pour chaque demande de ticket.
Flux type 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 la bonne Carte depuis The Wallet Crew et renvoie une charge utile d’installation adaptée à l’appareil (Apple .pkpass ou un JWT Google). L’application ouvre ensuite l’interface native d’enregistrement du Wallet, et vous suivez les installations via les événements de Wallet Crew.
{% @mermaid/diagram content="sequenceDiagram autonumber actor User participant App as Application mobile participant Backend as Votre backend participant TWC as backend de The Wallet Crew participant Wallet as Apple/Google Wallet (interface système)"
N’appelez jamais les API de The Wallet Crew depuis le client mobile avec une clé API. Conservez les secrets uniquement sur votre backend.
Apple Wallet contre Google Wallet
Votre application mobile utilise l’interface native du Wallet, mais elle ne communique jamais directement avec The Wallet Crew au moyen d’une clé API. Votre backend est le seul composant qui appelle le backend de The Wallet Crew pour résoudre passId et générer la charge utile d’installation.
Apple Wallet utilise un lot de Cartes signé.
Votre backend demande une charge utile d’installation Apple au backend de The Wallet Crew. Il renvoie un .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. La Carte est ensuite stockée localement sur l’appareil.
Utilisez le libellé « Add to Apple Wallet ».
Google Wallet utilise des objets liés au cloud.
Votre backend demande une charge utile d’installation Google au backend de The Wallet Crew. Il renvoie une charge utile d’enregistrement, généralement un JWT, pour le flux d’enregistrement de Google Wallet.
Votre application Android lance l’interface d’enregistrement Google. L’utilisateur confirme l’installation. La Carte est liée au compte Google de l’utilisateur et peut se synchroniser entre les appareils.
Utilisez le libellé « Add to Google Wallet ».
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 un flux d’émission. Vous avez aussi besoin d’un backend que votre application peut appeler, car les secrets et la recherche de Cartes doivent rester côté serveur.
Architecture de haut niveau
À haut niveau, votre backend résout un identifiant stable en un passId passId, puis appelle les API de The Wallet Crew à l’aide de X-API-KEY. Votre application ne reçoit que la charge utile d’installation spécifique au fournisseur et installe la Carte à l’aide des API natives du Wallet.
Étape par étape
Résolvez le passId sur votre backend
Utilisez votre propre identifiant stable. Exemples : identifiant de fidélité, identifiant client, identifiant de billet.
Appelez le point de terminaison de liste des Cartes avec un filtre.
Exemple (recherche par identifiers.ur.customerId):
Adaptez filter[0].field à votre propre clé d’identifiant.
Les clés typiques ressemblent à identifiers.<namespace>.<name>.
Vous obtiendrez un tableau JSON contenant la Carte id.
C’est id l’ passId id que vous utiliserez ensuite.
Générez une « charge utile d’installation » spécifique au fournisseur
Une fois que vous avez passId, demandez la charge utile pour l’appareil cible. Apple renvoie un .pkpass fichier téléchargeable, et Google renvoie un jeton JWT. Un modèle de point de terminaison typique ressemble à ceci :
GET https://app.neostore.cloud/api/<tenantId>/passes/<passId>?device=<apple|google>&neo.src=<tracking>
neo.src est utilisé pour le suivi et l’attribution.
Format : <medium>|<tag1>,<tag2>|<originUrl>.
Suivez les installations et gérez les réinstallations
Utilisez les événements de Wallet Crew pour mesurer l’adoption et les sources. En pratique, vous associez à chaque emplacement dans l’application neo.src (profil, paiement, onboarding) et vous abonnez à Carte:Installed les événements (webhook) ou interrogez l’adoption via Insights.
FAQ
Puis-je mettre la clé API dans l’application mobile ?
Non. Traitez les clés API comme des mots de passe. Placez les appels API derrière votre backend.
L’application peut-elle appeler directement le point de terminaison « charge utile d’installation » ?
Oui, si vous utilisez seulement un passId et que vous n’ utilisez pas de clé API. C’est généralement sûr parce que passId est opaque et impossible à deviner.
Ne pas implémentez la recherche de Carte (par identifiant client) côté client.
Dois-je utiliser les flux Wallet natifs ou le SDK du site web dans une application mobile ?
Dans une application mobile, privilégiez les flux natifs de Wallet. Ils offrent la meilleure UX et le moins de friction. Ils évitent également les redirections web.
Utilisez le SDK du site web lorsque vous distribuez depuis des pages web, ou lorsque vous avez besoin d’un QR de secours sur ordinateur.
Voir : Sur votre site web
Comment dois-je intégrer « Add to Wallet » dans une application React Native ?
Utilisez des modules natifs ou une bibliothèque Wallet maintenue, puis lancez le flux d’enregistrement natif sur chaque plateforme. Un bon point de départ pratique est : https://habr.com/en/articles/858858/
Comment dois-je intégrer « Add to Wallet » dans une application Flutter ?
Ce modèle fonctionne bien dans Flutter. Conservez la recherche de Cartes et la génération de la charge utile sur votre backend, puis déclenchez les flux natifs d’enregistrement Wallet iOS/Android depuis Flutter.