Aperçu : fonctionnement de l'intégration Apple Wallet
Passinstance génère des archives natives Apple Wallet .pkpass (Apple Wallet Packager) conformes à la spécification PassKit d'Apple pour iOS et watchOS. Chaque passe est assemblé à la volée sous la forme d'une archive ZIP signée cryptographiquement et servie avec le type MIME application/vnd.apple.pkpass.

Structure interne d'une archive .pkpass
Un paquet .pkpass Apple Wallet est une archive ZIP standard contenant cinq couches structurelles essentielles :
| Fichier / Répertoire | Format & encodage | Rôle dans Apple Wallet |
|---|---|---|
pass.json | JSON UTF-8 | Définit le style du passe (storeCard, coupon, eventTicket, boardingPass, generic), passTypeIdentifier, teamIdentifier, serialNumber, authenticationToken, webServiceURL, les champs, codes-barres, coordonnées GPS et le dictionnaire nfc. |
Ressources visuelles (.png) | PNG (@1x, @2x, @3x) | Jusqu'à 13 emplacements d'images du modèle convertis vers les noms de fichiers Apple PassKit (icon.png, logo.png, strip.png, thumbnail.png, background.png, footer.png, artwork.png, venueMap.png) aux résolutions Retina. |
<lang>.lproj/pass.strings | Table de chaînes UTF-8 | Traductions clé-valeur localisées (ex. de.lproj/pass.strings, fr.lproj/pass.strings) appliquées selon la langue système de l'iPhone. |
manifest.json | JSON UTF-8 | Dictionnaire plat associant chaque chemin relatif de fichier du paquet (hors manifest.json et signature) à son empreinte hexadécimale SHA-1 de 40 caractères. |
signature | DER binaire (PKCS#7) | Signature cryptographique PKCS#7 détachée de manifest.json, générée avec votre clé privée Apple Pass Type ID et chaînée au certificat intermédiaire Apple WWDR G4/G6. |
Important : Apple Wallet impose strictement que les valeurs de couleur de
pass.json(backgroundColor,foregroundColor,labelColor) soient sérialisées au formatrgb(r, g, b). Le composantapple-pass-field.serializer.tsde Passinstance convertit automatiquement les codes hexadécimaux versrgb(r, g, b)et supprime tout canal alpha afin qu'iOS ne rejette jamais le paquet lors de la validation du schéma et de la signature.
Exemple de structure d'une charge utile pass.json
{
"formatVersion": 1,
"passTypeIdentifier": "pass.com.yourbrand.loyalty",
"serialNumber": "PI-8849-2026-X9",
"teamIdentifier": "9A8B7C6D5E",
"organizationName": "Phenix Roasters",
"description": "Phenix VIP Rewards Card",
"webServiceURL": "https://api.passinstance.com",
"authenticationToken": "b7f9e2c1a4d80931f6e5c2b8a1049d7e",
"foregroundColor": "rgb(255, 255, 255)",
"backgroundColor": "rgb(18, 24, 38)",
"labelColor": "rgb(148, 163, 184)",
"storeCard": {
"headerFields": [
{
"key": "tier",
"label": "TIER",
"value": "Gold"
}
],
"primaryFields": [
{
"key": "points",
"label": "POINTS BALANCE",
"value": 1450,
"changeMessage": "Your points balance updated to %@"
}
],
"backFields": [
{
"key": "support_link",
"label": "MEMBER PORTAL",
"value": "Visit https://yourbrand.com/member",
"attributedValue": "<a href=\"https://yourbrand.com/member\">Open Member Portal</a>"
}
]
},
"barcodes": [
{
"format": "PKBarcodeFormatQR",
"message": "PI-8849-2026-X9",
"messageEncoding": "iso-8859-1",
"altText": "PI-8849-2026-X9"
}
]
}
Points d'entrée Apple Wallet Web Service (/v1)
Chaque passe actif embarque webServiceURL ainsi qu'un jeton authenticationToken d'au moins 16 caractères. Les appareils iOS et watchOS dialoguent directement avec les routes /v1 de Passinstance en présentant l'en-tête HTTP Authorization: ApplePass <authenticationToken> :
| Méthode | Chemin du point d'entrée | Codes HTTP | Rôle |
|---|---|---|---|
| POST | /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber | 201 Created, 200 OK, 401 Unauthorized | Enregistre le pushToken de l'iPhone ou de l'Apple Watch pour les mises à jour APNs et marque le passe comme installé. |
| GET | /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier | 200 OK, 204 No Content | Retourne { serialNumbers: [...], lastUpdated: "<tag>" } pour les passes modifiés depuis ?passesUpdatedSince=. |
| GET | /v1/passes/:passTypeIdentifier/:serialNumber | 200 OK, 304 Not Modified, 401 Unauthorized | Génère et transmet l'archive .pkpass signée la plus récente lors d'un réveil APNs ou d'un rafraîchissement manuel par glissement vers le bas. |
| DELETE | /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber | 200 OK, 401 Unauthorized | Désenregistre l'appareil lorsque le titulaire supprime la carte d'Apple Wallet. |
| POST | /v1/log | 200 OK | Reçoit les tableaux de diagnostic { "logs": [...] } envoyés par iOS lorsqu'un .pkpass échoue à la validation côté appareil. |
Approfondissez ces spécifications techniques sur Plateforme Apple Wallet, Certificats Apple Wallet et Protocole sans contact Apple VAS.
