Skip to content
Guide du centre d'aide · Intégrations WalletPhase d'intégration 4
3 min de lectureVérifié 2026-11-16

Apple Wallet

Génération des archives .pkpass, signature PKCS#7, enregistrement iOS/watchOS et échanges serveur PassKit.

Dans ce guide

Visites interactives de l'interface

Ouvrir dans le guide en 6 phases

Inspectez les écrans exacts du tableau de bord et les zooms annotés liés à ce guide.

Focus interface zoomé
Éléments clés de l'interface

Aperçu en direct double Wallet (Zoom)

Basculez entre Apple et Google dans le panneau d'aperçu pour vérifier les visuels, le formatage du solde, la lisibilité du QR code et l'alignement des champs.

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.

Aperçu en direct d'un passe Apple Wallet vs Google Wallet
Aperçu en direct d'un passe Apple Wallet vs Google Wallet
FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
EMPAQUETAGE .PKPASS APPLE WALLET & WEB SERVICE
ÉTAPE 01 CONSTRUCTEUR D'ARCHIVE PKPASS (Apple Wallet Packager)
1
Sérialiser pass.json (formatVersion: 1, couleurs rgb(r,g,b), champs, NFC)
2
Injecter les visuels Retina (icon.png, logo.png, strip.png @1x/@2x/@3x)
3
Compiler les bundles de langues (<lang>.lproj/pass.strings en UTF-8)
4
Calculer le dictionnaire de hachages SHA-1Écrire manifest.json
5
Générer la signature PKCS#7 détachée (Pass Type Cert + Apple WWDR G4/G6)
6
Compresser en ZIPServir avec Content-Type: application/vnd.apple.pkpass
ÉTAPE 02 PROTOCOLE APPLE WALLET WEB SERVICE (/v1)
Enregistrer l'appareil : POST/v1/devices/:deviceLibId/registrations/:typeId/:sn
Lister les MàJ : GET/v1/devices/:deviceLibId/registrations/:typeId
Télécharger le paquet : GET/v1/passes/:passTypeId/:serialNumber
Désenregistrer : DELETE/v1/devices/:deviceLibId/registrations/:typeId/:sn
Journaux d'erreur iOS : POST/v1/log

Structure interne d'une archive .pkpass

Un paquet .pkpass Apple Wallet est une archive ZIP standard contenant cinq couches structurelles essentielles :

Fichier / RépertoireFormat & encodageRôle dans Apple Wallet
pass.jsonJSON UTF-8Dé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.stringsTable de chaînes UTF-8Traductions clé-valeur localisées (ex. de.lproj/pass.strings, fr.lproj/pass.strings) appliquées selon la langue système de l'iPhone.
manifest.jsonJSON UTF-8Dictionnaire plat associant chaque chemin relatif de fichier du paquet (hors manifest.json et signature) à son empreinte hexadécimale SHA-1 de 40 caractères.
signatureDER 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 format rgb(r, g, b). Le composant apple-pass-field.serializer.ts de Passinstance convertit automatiquement les codes hexadécimaux vers rgb(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

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éthodeChemin du point d'entréeCodes HTTPRôle
POST/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber201 Created, 200 OK, 401 UnauthorizedEnregistre 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/:passTypeIdentifier200 OK, 204 No ContentRetourne { serialNumbers: [...], lastUpdated: "<tag>" } pour les passes modifiés depuis ?passesUpdatedSince=.
GET/v1/passes/:passTypeIdentifier/:serialNumber200 OK, 304 Not Modified, 401 UnauthorizedGé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/:serialNumber200 OK, 401 UnauthorizedDésenregistre l'appareil lorsque le titulaire supprime la carte d'Apple Wallet.
POST/v1/log200 OKReç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.

Documentation produit et développeur associée

Prêt à lancer votre premier programme de cartes Wallet ?

Créez votre espace de travail, configurez votre modèle et testez une vraie carte dans Apple Wallet et Google Wallet avant de déployer à grande échelle.