Skip to content
Guide du centre d'aide · Modèles de passesPhase d'intégration 2
8 min de lectureVérifié 2026-11-16

Design & configuration des modèles

Maîtrisez l'éditeur visuel : types de cartes, couleurs avec contrôle de contraste WCAG, logos, bannières et codes-barres.

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é1 / 2
Éléments clés de l'interface

Couleurs de marque & contraste WCAG (Zoom)

Réglez couleurs d'étiquette, de valeur et de fond avec correction de contraste en un clic, inversion, couleur révoquée et adaptation OS.

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.

Couleurs de marque et vérificateur de contraste dans l'éditeur
Couleurs de marque et vérificateur de contraste dans l'éditeur

Architecture système : pipeline de sérialisation des modèles

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX D'ARCHITECTURE SYSTÈME : CONCEPTION & SÉRIALISATION DE MODÈLE
ÉTAPE 01 ÉDITEUR VISUEL / API REST (/api/v1/templates)
6 zones de champs
(En-têteVerso)
13 empl. images
(@1x, @2x, @3x)
Schéma coul.
(RGB / Hex)
11 codes-b.
& Géofencing
ÉTAPE 02 MOTEUR DE VALIDATION & COMPILATION DES MODÈLES
Applique les contraintes géométriques pass type (storeCard, etc.)
Convertit les couleursrgb(r, g, b) pour Apple & #RRGGBB pour Google
Génère les dérivés Retina (@1x, @2x, @3x) dans le stockage objet S3
Valide le contraste WCAG 2.1 AA & l'encodage code-barres (iso-8859-1/utf-8)
ÉTAPE 03A APPLE WALLET (Paquet .pkpass)
Sérialisation dictionnaire pass.json
icon.png, logo@2x.png, strip.png
locations[], beacons[], nfc{}
ÉTAPE 03B GOOGLE WALLET (Ressource Class)
LoyaltyClass / EventTicketClass
hexBackgroundColor & heroImage
callbackOptions & config Smart Tap

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 WalletCorrespondance Google WalletContenu 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érieurSolde de points, badge VIP, numéro de porte
primaryFields (PRIMARY)Bannière centrale majeure superposée sur ou sous stripMétrique / titre principal mis en avantNom du titulaire, % de remise, titre d'événement
secondaryFields (SECONDARY)Rangée directement sous les champs principaux (jusqu'à 4 colonnes)Première rangée textModulesDataID membre, place/rang/tribune, compteur de tampons
auxiliaryFields (AUXILIARY)Rangée supplémentaire sous les secondaires (ou au-dessus sur eventTicket)Rangée secondaire textModulesDataDate 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 lieuModules de détails auxiliairesFAQ événement, consignes d'entrée, mentions secondaires
footerFields (FOOTER)Zone inférieure juste à côté du code-barresLibellé sous le code-barresCode 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 parseur pass.json d'Apple Wallet impose strictement des triplets CSS RGB sans canal alpha — par exemple rgb(24, 24, 27). Les codes hexadécimaux (#18181B) ou valeurs rgba() 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 classes walletobjects de 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 backgroundColor et foregroundColor / 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 dans pass.json. Lors d'appels à l'API REST Passinstance, vous pouvez fournir soit rgb(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'emplacementPlateforme cibleDimensions @1xDimensions @2xDimensions @3xRôle & emplacement dans la mise en page
iconApple Wallet29 x 29 px58 x 58 px87 x 87 pxIcône requise pour les notifications sur écran verrouillé et pièces jointes
logoApple Wallet160 x 50 px320 x 100 px480 x 150 pxLogo de marque en haut à gauche à côté de logoText et des champs header
primaryLogoUnifié / Secours160 x 50 px320 x 100 px480 x 150 pxLogo canonique hérité sur l'ensemble des cibles Wallet
googlePayLogoGoogle Wallet660 x 660 px (min)——Logo de programme recadré en cercle dans l'en-tête Google Wallet (ratio 1:1)
stripApple (storeCard, coupon, eventTicket)375 x 123 px (eventTicket : 375 x 98 px)750 x 246 px1125 x 369 pxBannière horizontale pleine largeur derrière ou au-dessus des champs principaux
backgroundApple (eventTicket, generic)180 x 220 px360 x 440 px540 x 660 pxTexture d'arrière-plan floutée sur toute la carte
thumbnailApple (generic, membership, eventTicket)90 x 90 px180 x 180 px270 x 270 pxPortrait photo carré ou badge produit affiché à droite
footerApple (boardingPass, eventTicket)286 x 15 px572 x 30 px858 x 45 pxBandeau fin affiché juste au-dessus du code-barres
artworkApple WWDC25 Poster Ticket375 x 480 px750 x 960 px1125 x 1440 pxAffiche événementielle haute visibilité pour Event Tickets iOS
venueMapApple WWDC25 Event Guide375 x 375 px750 x 750 px1125 x 1125 pxPlan téléchargeable des places/du site dans l'Event Guide iOS
secondaryLogoCo-branding unifié160 x 50 px320 x 100 px480 x 150 pxBadge partenaire ou sponsor secondaire
androidBackgroundGoogle Wallet1032 x 336 px——Surcharge dédiée pour la bannière heroImage Google Wallet (ratio 3.07:1)
androidLogoGoogle Wallet660 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 formatType canoniqueApple Wallet natifGoogle Wallet natifCas d'usage courant
PKBarcodeFormatQR (PKBarcodeFormatSquare)QR_CODEOui (PKBarcodeFormatQR)Oui (QR_CODE)Fidélité retail, accueil événementiel, scanners caméra
PKBarcodeFormatPDF417 (PKBarcodeFormatRectangle)PDF_417Oui (PKBarcodeFormatPDF417)Oui (PDF_417)Cartes d'embarquement aérien, titres de transport, badges
PKBarcodeFormatAztecAZTECOui (PKBarcodeFormatAztec)Oui (AZTEC)Billets ferroviaires, billets d'événements haute densité
PKBarcodeFormatCode128CODE_128Oui (PKBarcodeFormatCode128)Oui (CODE_128)Lecteurs laser de caisse en grande distribution, cartes de membre
PKBarcodeFormatCode39CODE_39Repli / Rendu généréOui (CODE_39)Lecteurs industriels, automobile et badges
PKBarcodeFormatCodabarCODABARRepli / Rendu généréOui (CODABAR)Bibliothèques, laboratoires et colis logistiques
PKBarcodeFormatEAN13EAN_13Repli / Rendu généréOui (EAN_13)Coupons retail et encaissement UPC/EAN en magasin
PKBarcodeFormatI2of5ITF (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
PKBarcodeFormatNoneNONEAucun 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, altitude optionnelle, maxDistance en mètres et relevantText affiché sur l'écran verrouillé).
  • Balises Bluetooth Low Energy (modèle Beacon) : jusqu'à 10 iBeacons Apple (proximityUUID, identifiants 16 bits major et minor et relevantText) pour la détection de micro-localisation en intérieur aux entrées ou portiques.
  • Pertinence temporelle (RelevantDate) : horodatage ISO 8601 (relevantDate) et expirationDate qui 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, bundleEnabled et maxBundleSize (jusqu'à 10 passes par lot).

6. Référence API programmatique des modèles (request payload)

Lister les modèles de l'espace de travail

GET /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

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)

JSON
{
  "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.

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.