Skip to content
Guida del Centro assistenza · Modelli di passFase di onboarding 2
8 min di letturaVerificato 2026-11-16

Design e configurazione modelli

Padroneggia l'Editor Visivo: formati tessera, colori con verifica contrasto WCAG, loghi, banner e codici a barre.

In questa guida

Guide visive interattive UI

Apri nella guida in 6 fasi

Esplora schermate reali della dashboard e dettagli ingranditi collegati a questa guida.

Focus UI ingrandito1 / 2
Elementi chiave dell'interfaccia

Colori del brand e contrasto WCAG (Ingrandito)

Imposta colori con auto-correzione contrasto WCAG, scambio colori, sfondo pass annullati e adattamento Wallet.

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.

Colori brand nell'editor e verifica contrasto
Colori brand nell'editor e verifica contrasto

Architettura di sistema: pipeline di serializzazione dei modelli

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
PIPELINE DI DESIGN E SERIALIZZAZIONE MODELLO
FASE 01 EDITOR VISUALE / REST API (/api/v1/templates)
6 Zone di campo
(HeaderBack)
13 Slot immagini
(@1x, @2x, @3x)
Schema colori
(RGB / Hex)
11 Barcode e
Geofencing
FASE 02 MOTORE DI VALIDAZIONE E COMPILAZIONE MODELLO
Applica i vincoli geometrici pass type (storeCard, eventTicket, ecc.)
Converte i token colorergb(r, g, b) per Apple e #RRGGBB per Google
Genera derivati asset retina (@1x, @2x, @3x) su Object Store S3
Verifica contrasto WCAG 2.1 AA e codifica barcode (iso-8859-1/utf-8)
FASE 03A APPLE WALLET (Bundle .pkpass)
Serializzazione dizionario pass.json
icon.png, logo@2x.png, strip.png
locations[], beacons[], nfc{}
FASE 03B GOOGLE WALLET (Risorsa Class)
LoyaltyClass / EventTicketClass
hexBackgroundColor e heroImage
callbackOptions e config Smart Tap

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 WalletMappatura Google WalletContenuto tipico
headerFields (HEADER)Angolo superiore destro accanto a logo (max 1–3 campi compatti)Mappato sui metadati di stato/intestazione superioriSaldo punti, badge livello VIP, numero varco
primaryFields (PRIMARY)Fascia centrale in evidenza sovrapposta o sotto stripMetrica / titolo hero principale della tesseraNome titolare, % di sconto, titolo evento
secondaryFields (SECONDARY)Riga subito sotto i campi primari (fino a 4 colonne)Riga textModulesData di primo livelloID socio, posto/fila/settore, contatore timbri
auxiliaryFields (AUXILIARY)Riga metadati aggiuntiva sotto i secondari (o sopra su eventTicket)Riga secondaria textModulesDataData 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 ausiliariFAQ evento, istruzioni d'ingresso, note integrative
footerFields (FOOTER)Zona inferiore immediatamente adiacente al codice a barreEtichetta a piè del codice a barreCodice 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 di pass.json su Apple Wallet impone rigorosamente stringhe tripletta RGB CSS senza canale alfa — ad esempio rgb(24, 24, 27). Valori esadecimali (#18181B) o rgba() vengono normalizzati automaticamente dal serializzatore di Passinstance affinché sintassi non valide non entrino mai nei bundle .pkpass.
  • Google Wallet (#RRGGBB): Le classi walletobjects di 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 backgroundColor e foregroundColor / 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 in pass.json. Quando si richiama la REST API di Passinstance è possibile fornire rgb(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 assetPiattaforma destinazioneDimensioni @1xDimensioni @2xDimensioni @3xScopo e posizionamento nel layout
iconApple Wallet29 x 29 px58 x 58 px87 x 87 pxIcona obbligatoria per notifiche in schermata di blocco e allegati e-mail
logoApple Wallet160 x 50 px320 x 100 px480 x 150 pxLogo del brand in alto a sinistra accanto a logoText e campi header
primaryLogoUnificato / Fallback160 x 50 px320 x 100 px480 x 150 pxMarchio canonico ereditato tra tutte le piattaforme Wallet
googlePayLogoGoogle Wallet660 x 660 px (min)——Logo del programma con maschera circolare nell'intestazione Google Wallet (rapporto 1:1)
stripApple (storeCard, coupon, eventTicket)375 x 123 px (eventTicket: 375 x 98 px)750 x 246 px1125 x 369 pxBanner orizzontale full-bleed dietro o sopra i campi primari
backgroundApple (eventTicket, generic)180 x 220 px360 x 440 px540 x 660 pxTexture di sfondo sfocata sull'intera tessera
thumbnailApple (generic, membership, eventTicket)90 x 90 px180 x 180 px270 x 270 pxFoto ritratto quadrata o badge prodotto sul lato destro
footerApple (boardingPass, eventTicket)286 x 15 px572 x 30 px858 x 45 pxBanner sottile visualizzato immediatamente sopra il codice a barre
artworkApple WWDC25 Poster Ticket375 x 480 px750 x 960 px1125 x 1440 pxArtwork poster ad alto impatto per i biglietti evento iOS
venueMapApple WWDC25 Event Guide375 x 375 px750 x 750 px1125 x 1125 pxMappa dei posti o planimetria scaricabile dentro Apple Event Guide
secondaryLogoCo-branding unificato160 x 50 px320 x 100 px480 x 150 pxBadge secondario per sponsor o brand partner
androidBackgroundGoogle Wallet1032 x 336 px——Override dedicato Google Wallet per heroImage (rapporto 3.07:1)
androidLogoGoogle Wallet660 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 formatTipo canonicoApple Wallet nativoGoogle Wallet nativoCaso d'uso tipico
PKBarcodeFormatQR (PKBarcodeFormatSquare)QR_CODESì (PKBarcodeFormatQR)Sì (QR_CODE)Fedeltà retail, check-in eventi, scanner con fotocamera
PKBarcodeFormatPDF417 (PKBarcodeFormatRectangle)PDF_417Sì (PKBarcodeFormatPDF417)Sì (PDF_417)Carte d'imbarco aeree, biglietti trasporti, documenti ID
PKBarcodeFormatAztecAZTECSì (PKBarcodeFormatAztec)Sì (AZTEC)Biglietti ferroviari, pass eventi ad alta densità
PKBarcodeFormatCode128CODE_128Sì (PKBarcodeFormatCode128)Sì (CODE_128)Scanner laser POS da supermercato, tessere socio
PKBarcodeFormatCode39CODE_39Fallback / RenderizzatoSì (CODE_39)Settore automotive, industriale e lettori badge
PKBarcodeFormatCodabarCODABARFallback / RenderizzatoSì (CODABAR)Biblioteche, laboratori e logistica pacchi
PKBarcodeFormatEAN13EAN_13Fallback / RenderizzatoSì (EAN_13)Coupon retail e casse POS UPC/EAN
PKBarcodeFormatI2of5ITF (accetta ITF_14 a 14 cifre su Google)Fallback / RenderizzatoSì (ITF_14 per 14 cifre)Imballaggi, ingrosso e biglietti numerici interlacciati
PKBarcodeFormatNoneNONENessun barcode mostratoNessun barcode mostratoPass 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, altitude opzionale, maxDistance in metri e relevantText mostrato sulla schermata di blocco).
  • Beacon Bluetooth Low Energy (modello Beacon): Fino a 10 Apple iBeacon (proximityUUID, identificativi a 16 bit major e minor, e relevantText) per il rilevamento di micro-prossimità indoor all'ingresso dei negozi o ai tornelli.
  • Rilevanza temporale (RelevantDate): Timestamp ISO 8601 (relevantDate) ed expirationDate che 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, bundleEnabled e maxBundleSize (fino a 10 pass per bundle).

6. Riferimento API programmatica dei modelli (request payload)

Elencare i modelli del workspace

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

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)

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
}

Prosegua con Campi dinamici e personalizzazione per associare attributi personalizzati al layout del modello, oppure esplori Meccaniche pass e funzionalità.

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.