Panoramica
Un Modello di pass (modello Template) definisce la geometria strutturale, il branding visivo, le zone dei campi nel layout, la simbologia del codice a barre e le regole di rilevanza basate sulla posizione condivise da tutti i pass emessi all'interno di un programma. Passinstance compila un'unica configurazione canonica del modello sia in archivi nativi Apple Wallet (.pkpass) sia in definizioni cloud Google Wallet (Class / Object).
Apra qualsiasi modello nella Dashboard ed entri in Modifica modello per configurare design e regole Wallet fianco a fianco con l'anteprima live di Apple Wallet e Google Wallet, oppure gestisca i modelli in modo programmatico tramite /api/v1/templates.

Architettura di sistema: pipeline di serializzazione dei modelli
1. Identità, tipi di pass e zone dei campi nel layout
Alla creazione di un modello, selezioni pass type / PassKind sottostante (storeCard, coupon, eventTicket, boardingPass, membership, studentId, generic, posterGeneric o businessCard), abbinato opzionalmente a theme preference (posterGeneric, posterEventTicket, bannerEventTicket, semanticBoardingPass, DARK) e transit type (PKTransitTypeAir, PKTransitTypeBoat, PKTransitTypeBus, PKTransitTypeGeneric, PKTransitTypeTrain) per le carte d'imbarco. Ogni tipo di pass determina il modo in cui il sistema operativo mobile renderizza l'intestazione della tessera, l'artwork principale e le righe dei campi.
Le 7 posizioni canoniche dei campi (field placement type)
Il modello Field e request payload collocano gli elementi dati in posizioni distinte del layout (HEADER, PRIMARY, SECONDARY, AUXILIARY, BACK, ADDITIONALINFO, FOOTER):
Posizione campo (request payload / field placement type) | Rendering Apple Wallet | Mappatura Google Wallet | Contenuto tipico |
|---|---|---|---|
headerFields (HEADER) | Angolo superiore destro accanto a logo (max 1–3 campi compatti) | Mappato sui metadati di stato/intestazione superiori | Saldo punti, badge livello VIP, numero varco |
primaryFields (PRIMARY) | Fascia centrale in evidenza sovrapposta o sotto strip | Metrica / titolo hero principale della tessera | Nome titolare, % di sconto, titolo evento |
secondaryFields (SECONDARY) | Riga subito sotto i campi primari (fino a 4 colonne) | Riga textModulesData di primo livello | ID socio, posto/fila/settore, contatore timbri |
auxiliaryFields (AUXILIARY) | Riga metadati aggiuntiva sotto i secondari (o sopra su eventTicket) | Riga secondaria textModulesData | Data di scadenza, punto vendita, promotore |
backFields (BACK) | Retro scorrevole del pass (supporta testi lunghi e link) | Vista espandibile Dettagli (textModulesData e linksModuleData) | Termini e condizioni, telefono assistenza, URL sito web |
additionalInfoFields (ADDITIONALINFO) | Dettagli complementari e blocchi sede su iOS 18+ | Moduli dettagli ausiliari | FAQ evento, istruzioni d'ingresso, note integrative |
footerFields (FOOTER) | Zona inferiore immediatamente adiacente al codice a barre | Etichetta a piè del codice a barre | Codice di sicurezza o istruzioni per inserimento manuale |
2. Colori e regole di serializzazione tra piattaforme
Il modello Color salva quattro proprietà semantiche fondamentali per ogni modello: backgroundColor, foregroundColor (testo dei valori dei campi), labelColor (etichette dei campi) e stripColor (tinta di sovrapposizione del testo sulle immagini strip).
-
Apple Wallet (
rgb(r, g, b)): Il parser dipass.jsonsu Apple Wallet impone rigorosamente stringhe tripletta RGB CSS senza canale alfa — ad esempiorgb(24, 24, 27). Valori esadecimali (#18181B) orgba()vengono normalizzati automaticamente dal serializzatore di Passinstance affinché sintassi non valide non entrino mai nei bundle.pkpass. -
Google Wallet (
#RRGGBB): Le classiwalletobjectsdi Google Wallet richiedono stringhe esadecimali a 6 caratteri (#18181B). Passinstance traduce in modo trasparente i token colore del modello per entrambe le piattaforme. -
Verifica del contrasto WCAG: L'editor visuale valuta in tempo reale i rapporti di contrasto di luminanza tra
backgroundColoreforegroundColor/labelColor, avvisando gli operatori se la tipografia scende sotto le soglie di leggibilità WCAG AA.
Importante: Apple Wallet richiede rigorosamente i colori in formato
rgb(r, g, b)e rifiuta codici esadecimali o canali alfa inpass.json. Quando si richiama la REST API di Passinstance è possibile fornirergb(r, g, b)oppure#RRGGBB: il backend normalizza e serializza automaticamente il formato esatto richiesto da ciascuna piattaforma.
3. I 13 slot asset visivi e le varianti Retina
Passinstance gestisce 13 slot immagini distinti sul modello Template. Quando si carica un PNG sorgente ad alta risoluzione, la pipeline asset ridimensiona e impacchetta automaticamente le varianti retina @1x, @2x e @3x per Apple Wallet, ospitando al contempo gli URL CDN pubblici richiesti da Google Wallet:
| Chiave slot asset | Piattaforma destinazione | Dimensioni @1x | Dimensioni @2x | Dimensioni @3x | Scopo e posizionamento nel layout |
|---|---|---|---|---|---|
icon | Apple Wallet | 29 x 29 px | 58 x 58 px | 87 x 87 px | Icona obbligatoria per notifiche in schermata di blocco e allegati e-mail |
logo | Apple Wallet | 160 x 50 px | 320 x 100 px | 480 x 150 px | Logo del brand in alto a sinistra accanto a logoText e campi header |
primaryLogo | Unificato / Fallback | 160 x 50 px | 320 x 100 px | 480 x 150 px | Marchio canonico ereditato tra tutte le piattaforme Wallet |
googlePayLogo | Google Wallet | 660 x 660 px (min) | — | — | Logo del programma con maschera circolare nell'intestazione Google Wallet (rapporto 1:1) |
strip | Apple (storeCard, coupon, eventTicket) | 375 x 123 px (eventTicket: 375 x 98 px) | 750 x 246 px | 1125 x 369 px | Banner orizzontale full-bleed dietro o sopra i campi primari |
background | Apple (eventTicket, generic) | 180 x 220 px | 360 x 440 px | 540 x 660 px | Texture di sfondo sfocata sull'intera tessera |
thumbnail | Apple (generic, membership, eventTicket) | 90 x 90 px | 180 x 180 px | 270 x 270 px | Foto ritratto quadrata o badge prodotto sul lato destro |
footer | Apple (boardingPass, eventTicket) | 286 x 15 px | 572 x 30 px | 858 x 45 px | Banner sottile visualizzato immediatamente sopra il codice a barre |
artwork | Apple WWDC25 Poster Ticket | 375 x 480 px | 750 x 960 px | 1125 x 1440 px | Artwork poster ad alto impatto per i biglietti evento iOS |
venueMap | Apple WWDC25 Event Guide | 375 x 375 px | 750 x 750 px | 1125 x 1125 px | Mappa dei posti o planimetria scaricabile dentro Apple Event Guide |
secondaryLogo | Co-branding unificato | 160 x 50 px | 320 x 100 px | 480 x 150 px | Badge secondario per sponsor o brand partner |
androidBackground | Google Wallet | 1032 x 336 px | — | — | Override dedicato Google Wallet per heroImage (rapporto 3.07:1) |
androidLogo | Google Wallet | 660 x 660 px | — | — | Override esplicito del logo Google Wallet se diverso da googlePayLogo |
4. Formati di codice a barre supportati e regole di validazione
Il modello Barcode e request payload coordinano barcode format (formati Apple Wallet inclusi quelli geometrici PKBarcodeFormatSquare / PKBarcodeFormatRectangle e PKBarcodeFormatNone) e i valori canonici BarcodeType (QR_CODE, PDF_417, AZTEC, CODE_128, EAN_13, CODE_39, CODABAR, ITF), insieme ad altText (o barcodeAlternativeText), messageEncoding (ISO_8859_1, UTF_8, ISO_8859_15, WINDOWS_1252, SHIFT_JIS), appleFallbackType e addSecurityAnimation (riflesso dinamico anti-screenshot):
| Valore barcode format | Tipo canonico | Apple Wallet nativo | Google Wallet nativo | Caso d'uso tipico |
|---|---|---|---|---|
PKBarcodeFormatQR (PKBarcodeFormatSquare) | QR_CODE | Sì (PKBarcodeFormatQR) | Sì (QR_CODE) | Fedeltà retail, check-in eventi, scanner con fotocamera |
PKBarcodeFormatPDF417 (PKBarcodeFormatRectangle) | PDF_417 | Sì (PKBarcodeFormatPDF417) | Sì (PDF_417) | Carte d'imbarco aeree, biglietti trasporti, documenti ID |
PKBarcodeFormatAztec | AZTEC | Sì (PKBarcodeFormatAztec) | Sì (AZTEC) | Biglietti ferroviari, pass eventi ad alta densità |
PKBarcodeFormatCode128 | CODE_128 | Sì (PKBarcodeFormatCode128) | Sì (CODE_128) | Scanner laser POS da supermercato, tessere socio |
PKBarcodeFormatCode39 | CODE_39 | Fallback / Renderizzato | Sì (CODE_39) | Settore automotive, industriale e lettori badge |
PKBarcodeFormatCodabar | CODABAR | Fallback / Renderizzato | Sì (CODABAR) | Biblioteche, laboratori e logistica pacchi |
PKBarcodeFormatEAN13 | EAN_13 | Fallback / Renderizzato | Sì (EAN_13) | Coupon retail e casse POS UPC/EAN |
PKBarcodeFormatI2of5 | ITF (accetta ITF_14 a 14 cifre su Google) | Fallback / Renderizzato | Sì (ITF_14 per 14 cifre) | Imballaggi, ingrosso e biglietti numerici interlacciati |
PKBarcodeFormatNone | NONE | Nessun barcode mostrato | Nessun barcode mostrato | Pass esclusivamente NFC (nfcNoBarcode: true) |
5. Geofencing, iBeacon, identificativi e rilevanza temporale
I pass compaiono automaticamente nella schermata di blocco del cliente quando si verificano trigger fisici o temporali:
-
Posizioni GPS (modello
Location): Fino a 10 coordinate per modello (latitude,longitude,altitudeopzionale,maxDistancein metri erelevantTextmostrato sulla schermata di blocco). -
Beacon Bluetooth Low Energy (modello
Beacon): Fino a 10 Apple iBeacon (proximityUUID, identificativi a 16 bitmajoreminor, erelevantText) per il rilevamento di micro-prossimità indoor all'ingresso dei negozi o ai tornelli. -
Rilevanza temporale (
RelevantDate): Timestamp ISO 8601 (relevantDate) edexpirationDateche mettono in evidenza biglietti evento o voucher a tempo all'avvicinarsi dell'orario previsto. -
Impostazioni per identificativi personalizzati e bundling: Configuri
customIdentifiersEnabled,externalIdentifierPattern,customIdentifierValidationPattern,bundleOnDownload,bundleEnabledemaxBundleSize(fino a10pass per bundle).
6. Riferimento API programmatica dei modelli (request payload)
Elencare i modelli del workspace
/api/v1/templates?page=1&limit=20&rowKind=PRODUCTION
Creare un nuovo modello (request payload)
POST /api/v1/templates Header: 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."
}
]
}
Risposta 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
}
Prosegua con Campi dinamici e personalizzazione per associare attributi personalizzati al layout del modello, oppure esplori Meccaniche pass e funzionalità.
