La création de cartes natives Apple Wallet (fichiers .pkpass) permet aux entreprises de diffuser des cartes de fidélité, billets d'événement, cartes d'embarquement, coupons et cartes de membre directement sur l'iPhone et l'Apple Watch, sans obliger les utilisateurs à télécharger une application mobile dédiée.
Ce guide technique complet couvre l'architecture Apple PassKit, la signature cryptographique, la diffusion et les mises à jour push en temps réel.
1. Anatomie d'une carte Apple Wallet (.pkpass)
Une carte Apple Wallet est une archive ZIP compressée portant l'extension .pkpass, contenant un fichier JSON structuré, des images adaptées et des manifestes signés cryptographiquement reconnus par Apple.
Structure requise du bundle
my-pass.pkpass
├── pass.json # Mise en page principale, définition des champs et métadonnées
├── logo.png # Emblème de marque en haut à gauche (160x160 @2x)
├── logo@2x.png
├── icon.png # Icône de notification écran verrouillé (58x58 @2x)
├── icon@2x.png
├── strip.png # Image bannière pour billets et coupons (375x144 @2x)
├── strip@2x.png
├── manifest.json # Empreintes SHA-1 de tous les fichiers de l'archive
└── signature # Signature cryptographique PKCS#7 créée avec votre certificat Pass Type ID
2. Configuration Apple Developer et signature par certificat
Pour signer nativement des cartes Apple Wallet, Apple exige des identifiants de signature PKCS#12 issus d'un compte Apple Developer actif.
Étapes du pipeline de signature :
-
1
Pass Type ID : Enregistrez un identifiant unique (ex.
pass.com.votreentreprise.fidelite) dans l'Apple Developer Portal. -
2
Demande de signature de certificat (CSR) : Générez une clé privée RSA 2048 bits et un fichier CSR via OpenSSL ou Trousseau d'accès.
-
3
Certificat Pass Type : Téléchargez votre certificat
.cerémis et exportez-le au format.p12avec sa clé privée. -
4
Certificat intermédiaire WWDR : Incluez le certificat intermédiaire Apple Worldwide Developer Relations G6 dans la chaîne de confiance.
[!NOTE]
Signature gérée en production : Pour signer des cartes Apple Wallet en production sous l'identité de votre marque, téléversez votre certificat Apple Developer Pass Type ID dans votre espace Passinstance. Passinstance automatise ensuite l'empaquetage
.pkpass, la signature PKCS#7 et la chaîne intermédiaire WWDR.
3. Configurer les champs de pass.json
Le fichier pass.json définit le style de mise en page (storeCard, coupon, eventTicket, boardingPass, generic) et les champs dynamiques :
{
"formatVersion": 1,
"passTypeIdentifier": "pass.com.passinstance.loyalty",
"serialNumber": "PASS-8842-2026",
"teamIdentifier": "ABC123XYZ",
"organizationName": "Artisan Coffee",
"description": "Carte de fidélité Artisan Coffee",
"logoText": "Artisan Coffee",
"foregroundColor": "rgb(255, 255, 255)",
"backgroundColor": "rgb(10, 90, 84)",
"labelColor": "rgb(164, 243, 222)",
"storeCard": {
"primaryFields": [
{
"key": "stamps",
"label": "PROGRESSION",
"value": "8 sur 10 tampons"
}
],
"secondaryFields": [
{
"key": "holder",
"label": "MEMBRE",
"value": "Jane Doe"
}
]
},
"barcodes": [
{
"format": "PKBarcodeFormatQR",
"message": "PASS-LOYALTY-8842",
"messageEncoding": "iso-8859-1"
}
],
"webServiceURL": "https://api.passinstance.com/v1/apple",
"authenticationToken": "tok_exemple_99182348"
}

4. Coordonnées de localisation et déclencheurs natifs
Les cartes Apple Wallet prennent en charge jusqu'à 10 coordonnées géographiques (locations) permettant à iOS d'afficher passivement un rappel sur l'écran verrouillé lorsque le client s'approche de votre boutique ou lieu d'événement.
"locations": [
{
"latitude": 48.856614,
"longitude": 2.3522219,
"relevantText": "Bienvenue ! Présentez votre carte en caisse pour profiter de votre avantage."
}
]
5. Pousser des mises à jour en temps réel (APNs)
Lorsque le solde, le palier ou la date d'expiration d'une carte évolue, Apple Wallet actualise la carte à distance via l'Apple Push Notification service (APNs) :
-
1
À l'installation, iOS envoie une requête POST vers votre
webServiceURLavec le jeton push de l'appareil (pushToken). -
2
Pour mettre à jour la carte, un signal push APNs vide est transmis vers les serveurs Apple pour cibler ce
pushToken. -
3
iOS se réveille en arrière-plan, récupère le dernier
pass.jsonauprès du serveur, met à jour la carte et affiche une bannière si un champ configuré avecchangeMessagea changé.
6. Générer des cartes Apple Wallet facilement avec Passinstance
Plutôt que de maintenir vos propres pipelines de signature OpenSSL, vos serveurs APNs et vos endpoints d'enregistrement d'appareils, Passinstance automatise l'ensemble du flux :
import { Passinstance } from "@passinstance/sdk";
const client = new Passinstance({ apiKey: process.env.PASSINSTANCE_API_KEY });
// Émettre une carte Apple Wallet signée
const pass = await client.passes.create({
templateId: "tpl_coffee_loyalty",
data: {
holderName: "Jane Doe",
stamps: "8 of 10 Stamps",
},
});
console.log("Lien Ajouter à Apple Wallet :", pass.appleWalletUrl);

Points clés à retenir
-
Aucune application requise : Les clients ajoutent leur carte en un geste depuis Safari, un QR code, un e-mail ou un lien hébergé.
-
Toujours à jour : Les modifications de solde se synchronisent sur iPhone et Apple Watch via APNs.
-
Pertinence géographique : Les coordonnées GPS affichent la carte sur l'écran verrouillé à l'approche de vos points de vente.





