Vue d'ensemble
Un Modèle de passe (modèle Template) définit la géométrie structurelle, l'identité visuelle, les zones de mise en page des champs, la symbologie des codes-barres et les règles de pertinence géolocalisée partagées par tous les passes émis au titre d'un programme. Passinstance compile une configuration canonique unique à la fois en archives natives Apple Wallet (.pkpass) et en définitions cloud Google Wallet (Class / Object).
Ouvrez n'importe quel modèle dans le tableau de bord puis cliquez sur Éditer le modèle (Edit Template) pour configurer le design et les règles Wallet côte à côte avec un aperçu en direct Apple Wallet et Google Wallet, ou gérez vos modèles par programmation via /api/v1/templates.

Architecture système : pipeline de sérialisation des modèles
1. Identité, types de passes & zones de mise en page
Lors de la création d'un modèle, sélectionnez le pass type / PassKind sous-jacent (storeCard, coupon, eventTicket, boardingPass, membership, studentId, generic, posterGeneric ou businessCard), éventuellement associé à theme preference (posterGeneric, posterEventTicket, bannerEventTicket, semanticBoardingPass, DARK) et transit type (PKTransitTypeAir, PKTransitTypeBoat, PKTransitTypeBus, PKTransitTypeGeneric, PKTransitTypeTrain) pour les cartes d'embarquement. Chaque type de passe détermine la manière dont le système d'exploitation mobile affiche l'en-tête, l'image principale et les rangées de champs.
Les 7 positions canoniques de champs (field placement type)
Le modèle Field et request payload répartissent les données dans des zones d'affichage distinctes (HEADER, PRIMARY, SECONDARY, AUXILIARY, BACK, ADDITIONALINFO, FOOTER) :
Position du champ (request payload / field placement type) | Rendu Apple Wallet | Correspondance Google Wallet | Contenu typique |
|---|---|---|---|
headerFields (HEADER) | Coin supérieur droit à côté du logo (max. 1 à 3 champs compacts) | Mappé sur les métadonnées de statut/en-tête supérieur | Solde de points, badge VIP, numéro de porte |
primaryFields (PRIMARY) | Bannière centrale majeure superposée sur ou sous strip | Métrique / titre principal mis en avant | Nom du titulaire, % de remise, titre d'événement |
secondaryFields (SECONDARY) | Rangée directement sous les champs principaux (jusqu'à 4 colonnes) | Première rangée textModulesData | ID membre, place/rang/tribune, compteur de tampons |
auxiliaryFields (AUXILIARY) | Rangée supplémentaire sous les secondaires (ou au-dessus sur eventTicket) | Rangée secondaire textModulesData | Date d'expiration, boutique, organisateur |
backFields (BACK) | Verso défilant du passe (accepte textes longs et liens) | Vue Détails dépliable (textModulesData & linksModuleData) | Conditions générales, téléphone support, URLs web |
additionalInfoFields (ADDITIONALINFO) | Détails complémentaires iOS 18+ et blocs d'information du lieu | Modules de détails auxiliaires | FAQ événement, consignes d'entrée, mentions secondaires |
footerFields (FOOTER) | Zone inférieure juste à côté du code-barres | Libellé sous le code-barres | Code de sécurité ou instructions de saisie manuelle |
2. Couleurs & règles de sérialisation par plateforme
Le modèle Color enregistre quatre propriétés sémantiques principales par modèle : backgroundColor, foregroundColor (texte des valeurs), labelColor (intitulés de champs) et stripColor (teinte du texte superposé sur l'image strip).
-
Apple Wallet (
rgb(r, g, b)) : le parseurpass.jsond'Apple Wallet impose strictement des triplets CSS RGB sans canal alpha — par exemplergb(24, 24, 27). Les codes hexadécimaux (#18181B) ou valeursrgba()sont automatiquement normalisés par le sérialiseur Passinstance afin qu'aucune syntaxe de couleur invalide n'entre dans les paquets.pkpass. -
Google Wallet (
#RRGGBB) : les classeswalletobjectsde Google Wallet exigent des chaînes hexadécimales à 6 caractères (#18181B). Passinstance traduit de façon transparente les couleurs de votre modèle pour les deux plateformes. -
Vérification de contraste WCAG : l'éditeur visuel évalue en temps réel le ratio de contraste de luminance entre
backgroundColoretforegroundColor/labelColor, et avertit l'opérateur si la lisibilité passe sous les seuils WCAG AA.
Important : Apple Wallet exige impérativement les couleurs au format
rgb(r, g, b)et rejette les codes hexadécimaux ou canaux alpha danspass.json. Lors d'appels à l'API REST Passinstance, vous pouvez fournir soitrgb(r, g, b), soit#RRGGBB— le backend normalise et sérialise automatiquement le format exact requis par chaque plateforme.
3. Les 13 emplacements visuels & variantes Retina
Passinstance gère 13 emplacements d'images distincts sur le modèle Template. Lorsque vous importez un PNG source haute résolution, le pipeline de traitement génère automatiquement les versions redimensionnées @1x, @2x et @3x pour Apple Wallet tout en hébergeant les URLs CDN publiques exigées par Google Wallet :
| Clé d'emplacement | Plateforme cible | Dimensions @1x | Dimensions @2x | Dimensions @3x | Rôle & emplacement dans la mise en page |
|---|---|---|---|---|---|
icon | Apple Wallet | 29 x 29 px | 58 x 58 px | 87 x 87 px | Icône requise pour les notifications sur écran verrouillé et pièces jointes |
logo | Apple Wallet | 160 x 50 px | 320 x 100 px | 480 x 150 px | Logo de marque en haut à gauche à côté de logoText et des champs header |
primaryLogo | Unifié / Secours | 160 x 50 px | 320 x 100 px | 480 x 150 px | Logo canonique hérité sur l'ensemble des cibles Wallet |
googlePayLogo | Google Wallet | 660 x 660 px (min) | — | — | Logo de programme recadré en cercle dans l'en-tête Google Wallet (ratio 1:1) |
strip | Apple (storeCard, coupon, eventTicket) | 375 x 123 px (eventTicket : 375 x 98 px) | 750 x 246 px | 1125 x 369 px | Bannière horizontale pleine largeur derrière ou au-dessus des champs principaux |
background | Apple (eventTicket, generic) | 180 x 220 px | 360 x 440 px | 540 x 660 px | Texture d'arrière-plan floutée sur toute la carte |
thumbnail | Apple (generic, membership, eventTicket) | 90 x 90 px | 180 x 180 px | 270 x 270 px | Portrait photo carré ou badge produit affiché à droite |
footer | Apple (boardingPass, eventTicket) | 286 x 15 px | 572 x 30 px | 858 x 45 px | Bandeau fin affiché juste au-dessus du code-barres |
artwork | Apple WWDC25 Poster Ticket | 375 x 480 px | 750 x 960 px | 1125 x 1440 px | Affiche événementielle haute visibilité pour Event Tickets iOS |
venueMap | Apple WWDC25 Event Guide | 375 x 375 px | 750 x 750 px | 1125 x 1125 px | Plan téléchargeable des places/du site dans l'Event Guide iOS |
secondaryLogo | Co-branding unifié | 160 x 50 px | 320 x 100 px | 480 x 150 px | Badge partenaire ou sponsor secondaire |
androidBackground | Google Wallet | 1032 x 336 px | — | — | Surcharge dédiée pour la bannière heroImage Google Wallet (ratio 3.07:1) |
androidLogo | Google Wallet | 660 x 660 px | — | — | Surcharge explicite du logo Google Wallet s'il diffère de googlePayLogo |
4. Formats de codes-barres pris en charge & règles de validation
Le modèle Barcode et request payload coordonnent barcode format (formats Apple Wallet incluant les formes géométriques PKBarcodeFormatSquare / PKBarcodeFormatRectangle et PKBarcodeFormatNone) et les types canoniques BarcodeType (QR_CODE, PDF_417, AZTEC, CODE_128, EAN_13, CODE_39, CODABAR, ITF), avec altText (ou barcodeAlternativeText), messageEncoding (ISO_8859_1, UTF_8, ISO_8859_15, WINDOWS_1252, SHIFT_JIS), appleFallbackType et addSecurityAnimation (effet scintillant anti-capture d'écran) :
| Valeur barcode format | Type canonique | Apple Wallet natif | Google Wallet natif | Cas d'usage courant |
|---|---|---|---|---|
PKBarcodeFormatQR (PKBarcodeFormatSquare) | QR_CODE | Oui (PKBarcodeFormatQR) | Oui (QR_CODE) | Fidélité retail, accueil événementiel, scanners caméra |
PKBarcodeFormatPDF417 (PKBarcodeFormatRectangle) | PDF_417 | Oui (PKBarcodeFormatPDF417) | Oui (PDF_417) | Cartes d'embarquement aérien, titres de transport, badges |
PKBarcodeFormatAztec | AZTEC | Oui (PKBarcodeFormatAztec) | Oui (AZTEC) | Billets ferroviaires, billets d'événements haute densité |
PKBarcodeFormatCode128 | CODE_128 | Oui (PKBarcodeFormatCode128) | Oui (CODE_128) | Lecteurs laser de caisse en grande distribution, cartes de membre |
PKBarcodeFormatCode39 | CODE_39 | Repli / Rendu généré | Oui (CODE_39) | Lecteurs industriels, automobile et badges |
PKBarcodeFormatCodabar | CODABAR | Repli / Rendu généré | Oui (CODABAR) | Bibliothèques, laboratoires et colis logistiques |
PKBarcodeFormatEAN13 | EAN_13 | Repli / Rendu généré | Oui (EAN_13) | Coupons retail et encaissement UPC/EAN en magasin |
PKBarcodeFormatI2of5 | ITF (accepte ITF_14 à 14 chiffres sur Google) | Repli / Rendu généré | Oui (ITF_14 sur 14 chiffres) | Emballages, gros et tickets numériques entrelacés |
PKBarcodeFormatNone | NONE | Aucun code-barres affiché | Aucun code-barres affiché | Passes exclusivement NFC (nfcNoBarcode: true) |
5. Géofencing, iBeacons, identifiants & pertinence temporelle
Les passes apparaissent automatiquement sur l'écran verrouillé du client lorsque des déclencheurs physiques ou temporels correspondent :
-
Localisations GPS (modèle
Location) : jusqu'à 10 coordonnées par modèle (latitude,longitude,altitudeoptionnelle,maxDistanceen mètres etrelevantTextaffiché sur l'écran verrouillé). -
Balises Bluetooth Low Energy (modèle
Beacon) : jusqu'à 10 iBeacons Apple (proximityUUID, identifiants 16 bitsmajoretminoretrelevantText) pour la détection de micro-localisation en intérieur aux entrées ou portiques. -
Pertinence temporelle (
RelevantDate) : horodatage ISO 8601 (relevantDate) etexpirationDatequi font apparaître les billets d'événement ou bons à durée limitée à l'approche de l'heure prévue. -
Paramètres d'identifiants personnalisés & de regroupement : configurez
customIdentifiersEnabled,externalIdentifierPattern,customIdentifierValidationPattern,bundleOnDownload,bundleEnabledetmaxBundleSize(jusqu'à10passes par lot).
6. Référence API programmatique des modèles (request payload)
Lister les modèles de l'espace de travail
/api/v1/templates?page=1&limit=20&rowKind=PRODUCTION
Créer un nouveau modèle (request payload)
POST /api/v1/templates En-têtes : X-API-Key: <API_KEY> | Content-Type: application/json
{
"name": "Artisan Coffee Club - Gold",
"kind": "storeCard",
"status": "DRAFT",
"organizationName": "Artisan Roasters GmbH",
"description": "Artisan Coffee Loyalty Card",
"colors": {
"backgroundColor": "rgb(20, 35, 28)",
"foregroundColor": "rgb(255, 255, 255)",
"labelColor": "rgb(167, 243, 208)",
"stripColor": "rgb(255, 255, 255)"
},
"barcode": {
"format": "PKBarcodeFormatQR",
"messageEncoding": "UTF_8",
"altText": "{serialNumber}",
"addSecurityAnimation": true
},
"locations": [
{
"latitude": 52.520008,
"longitude": 13.404954,
"maxDistance": 150,
"relevantText": "Welcome back to Artisan Roasters! Tap to scan your card."
}
]
}
Réponse HTTP (201 Created)
{
"success": true,
"data": {
"id": "tmpl_01hxyz987654321",
"groupId": "grp_01hxyz987654321",
"versionNumber": 1,
"rowKind": "DRAFT",
"status": "DRAFT",
"name": "Artisan Coffee Club - Gold",
"kind": "storeCard",
"colors": {
"backgroundColor": "rgb(20, 35, 28)",
"foregroundColor": "rgb(255, 255, 255)",
"labelColor": "rgb(167, 243, 208)",
"stripColor": "rgb(255, 255, 255)"
},
"createdAt": "2026-11-15T10:15:00.000Z"
},
"statusCode": 201
}
Poursuivez avec Champs dynamiques & personnalisation pour relier vos attributs personnalisés à la mise en page du modèle, ou explorez les Mécaniques de passes & fonctionnalités.
