Aperçu
Les designers et ingénieurs iOS qui prototypent des passes numériques à l'aide d'outils développeur macOS — tels que Pass Designer officiel d'Apple, Xcode ou des éditeurs de passes tiers sur poste de travail — peuvent importer leurs créations directement dans Passinstance. Vous n'avez pas à ressaisir manuellement les coordonnées de champs, les valeurs de couleurs, les types de codes-barres ni à téléverser les actifs image un par un.
Passinstance assure l'ingestion automatisée de :
-
Archives Apple Pass Designer (bundles
.passdesign). -
Documents XML Apple Property List (
.plistou.xml). -
Paquets Apple Wallet signés ou non signés (archives zip
.pkpass). -
Fichiers bruts de métadonnées Apple PassKit (
pass.json).
Le moteur d'import extrait les actifs image (icon.png, logo.png, strip.png, thumbnail.png), analyse la mise en page structurelle et la normalise en un modèle Passinstance entièrement modifiable, compatible à la fois avec Apple Wallet et Google Wallet.
Architecture système : moteur d'ingestion Apple PassKit & Plist
Formats de fichiers & extensions pris en charge
Le composant de téléversement dans Template Creation Wizard accepte les extensions correspondant à l'expression régulière /\.(passdesign|plist|xml|pkpass|zip|json)$/i :
| Format / Extension | Description | Contenu extrait |
|---|---|---|
.passdesign | Dossier bundle Apple Pass Designer ou archive compressée. | Géométrie complète du passe, mise en page visuelle des champs, couleurs et tous les actifs PNG Retina. |
.plist / .xml | Format XML Apple Property List. | Structures de champs, paires libellé/valeur, types de transport, codes-barres et règles de pertinence. |
.pkpass | Archive Apple Wallet standard (signée ou non signée). | pass.json, répertoires de localisation (.lproj) et actifs image. La signature numérique (signature) et le manifeste (manifest.json) sont ignorés en toute sécurité. |
pass.json | Dictionnaire Apple PassKit canonique. | Structure JSON Apple PassKit standard. |
Sécurité XML & protection contre les entités (parsePlistXmlToObject)
Lors de l'ingestion de documents Apple .plist ou .xml, Passinstance utilise un analyseur XML interne durci (parsePlistXmlToObject dans template-import-export.util.ts) appliquant des invariants de sécurité stricts :
-
1
Protection XXE (zéro résolution d'entité externe) : le parseur ignore totalement les déclarations
<!DOCTYPE>, les définitions d'entités externes (SYSTEMouPUBLIC) et les références de schéma XML. Cela élimine les vulnérabilités d'injection XML External Entity (XXE) et de Server-Side Request Forgery (SSRF). -
2
Garde-fou de récursion et de profondeur : la profondeur d'imbrication est plafonnée à
MAX_PLIST_DEPTH = 32. Les dictionnaires ou tableaux imbriqués dépassant ce seuil sont interrompus par une exception de validation afin d'empêcher tout débordement de pile. -
3
Prévention des bombes Zip : lors de la décompression des archives
.passdesignou.pkpass, le moteur limite le nombre total d'entrées àMAX_ZIP_ENTRIES = 250et la taille décompressée par fichier àMAX_ZIP_ENTRY_BYTES = 1 Mo(1048576octets). -
4
Protection contre la pollution de prototype : les clés de propriété correspondant à
__proto__,constructorouprototypesont supprimées lors de la construction des dictionnaires.
Référence de correspondance des types Apple PassKit
L'utilitaire d'import mappe automatiquement les types Apple Property List et les structures PassKit vers les modèles Passinstance :
| Type Apple PassKit / Plist | Équivalent modèle Passinstance | Comportement de normalisation |
|---|---|---|
<dict> | Object JavaScript | Converti en groupes de champs, objets couleur ou dictionnaires de géolocalisation. |
<array> | Array JavaScript | Converti en tableaux de champs (headerFields, primaryFields, etc.). |
<string> | string | Nettoie les espaces et déséchappe les entités XML (&, <, >). |
<integer> / <real> | number | Converti en nombres à virgule flottante ou entiers. |
<true/> / <false/> | boolean | Converti en primitives booléennes JavaScript standard. |
<date> | string ISO 8601 | Normalisé en horodatages ISO-8601 UTC (YYYY-MM-DDTHH:MM:SSZ). |
<data> | string Base64 | Décodé depuis le Base64 en tampons binaires d'actifs pour les images. |
Normalisation du style de passe vers PassKind
| Style de passe Apple | PassKind Passinstance | Invariants de mise en page & champs |
|---|---|---|
storeCard | storeCard | Mise en page recto avec image bandeau (strip) ; jusqu'à 4 champs secondaires/auxiliaires. |
coupon | coupon | Mise en page recto avec image bandeau (strip) ; les champs auxiliaires sont redirigés vers les champs secondaires. |
eventTicket | eventTicket | Prend en charge la texture d'arrière-plan, l'image bandeau et les blocs compagnons de lieu iOS 18. |
boardingPass | boardingPass | Analyse transitType (PKTransitTypeAir, PKTransitTypeTrain, etc.) et les champs principaux départ/arrivée. |
generic | generic | Mise en page polyvalente standard avec miniature (thumbnail) facultative. |
Importer via le tableau de bord (étape par étape)
-
1
Accédez à Modèles (Templates) dans le tableau de bord Passinstance et cliquez sur + Nouveau modèle (+ New Template).
-
2
À l'Étape 1 (Détails) de
Template Creation Wizard:
- Cliquez sur Importer un passe existant (Import existing pass) ou glissez-déposez votre fichier .passdesign, .plist, .pkpass ou pass.json dans la zone de dépôt.
-
3
L'assistant analyse le fichier instantanément et en extrait :
- Nom et description du modèle : pré-remplis depuis description ou organizationName. - Type de passe (PassKind) : détecté automatiquement d'après le dictionnaire de style Apple. - Couleurs : couleurs d'arrière-plan, de premier plan et de libellé appliquées à la palette. - Images : actifs Retina (icon.png, logo.png, strip.png) téléversés dans le stockage d'actifs de l'espace de travail. - Mise en page des champs : champs d'en-tête, primaires, secondaires, auxiliaires et verso placés dans leurs zones respectives.
-
4
Poursuivez avec l'Étape 2 (Type de passe) et l'Étape 3 (Applications Wallet) pour vérifier ou activer la prise en charge Google Wallet.
-
5
À l'Étape 4 (Finalisation), assignez un certificat Apple Pass Type afin d'activer la signature cryptographique, puis cliquez sur Terminer.
Importer via l'API REST
Vous pouvez également importer des paquets Apple Pass Designer par programmation via POST /api/v1/templates/import.
Requête HTTP (multipart/form-data)
curl -X POST https://api.passinstance.com/api/v1/templates/import \
-H "X-API-Key: <API_KEY>" \
-F "file=@loyalty_pass.passdesign" \
-F "name=Imported Loyalty Card"
Réponse HTTP (201 Created)
{
"success": true,
"data": {
"id": "tmpl_01h8x7j6k5m4n3p2q1",
"name": "Imported Loyalty Card",
"kind": "storeCard",
"status": "PUBLISHED",
"versionNumber": 1,
"importedFrom": "apple_pass_designer",
"imagesImported": ["icon", "logo", "strip"],
"fieldsCount": 8,
"createdAt": "2026-11-16T20:35:00.000Z"
},
"statusCode": 201
}
Dépannage de l'import Apple Pass
| Symptôme / Erreur | Cause racine | Résolution |
|---|---|---|
Unsupported file format | L'extension du fichier ne figure pas dans la liste prise en charge. | Vérifiez que votre fichier se termine par .passdesign, .plist, .xml, .pkpass, .zip ou .json. |
Missing required icon asset | Le paquet Apple ne contenait ni icon.png ni icon@2x.png. | Apple PassKit exige une icône pour chaque passe. Ajoutez une icône PNG 76x76 ou 114x114 à votre paquet avant de l'importer. |
Zip entry size exceeded | Un actif image dans l'archive dépasse 1 Mo. | Optimisez vos images matricielles avec un outil de compression PNG ou téléversez les actifs séparément après création du modèle. |
Unsigned package notice | Le fichier .pkpass importé ne comportait pas de signature cryptographique valide. | Comportement normal pour les paquets de prototypage (isUnsignedPackage: true). Passinstance accepte les archives non signées et signe les passes à l'émission avec le certificat Apple de votre espace de travail. |
Découvrez Créer un modèle depuis JSON pour les imports de schéma brut ou Design & configuration des modèles pour ajuster le rendu visuel dans l'éditeur.
