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

Campi dinamici e personalizzazione

Collega proprietà personalizzate e token di sistema tramite {variableName} nelle aree Apple e Google Wallet.

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

Completamento automatico variabili dinamiche (Zoom)

Digita «{» in qualsiasi campo Valore per cercare e inserire attributi personalizzati ({passStatus}) o campi di sistema ({storedValue}, {userProvidedId}).

Panoramica

La personalizzazione dei pass Wallet per migliaia o milioni di titolari si basa sulle Proprietà personalizzate (definizioni di schema dichiarate sul modello) abbinate ad associazioni {variable} all'interno del modello Field nelle zone header, primary, secondary, auxiliary, back e footer. Al momento della generazione e dell'aggiornamento del pass, Passinstance popola questi token dal dizionario structured JSON attributes del record pass e formatta date, numeri, valute e notifiche push in schermata di blocco in modo nativo per Apple Wallet e Google Wallet.

Digitare la parentesi graffa apre l'autocompletamento delle variabili
Digitare la parentesi graffa apre l'autocompletamento delle variabili

Architettura di sistema: popolamento campi dinamici e indicizzazione

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
POPOLAMENTO CAMPI DINAMICI E SERIALIZZAZIONE WALLET
FASE 01 RECORD PASS (Modello Pass in database)
serialNumber: "PI-884920-AB"
attributes (structured JSON indicizzato tramite GIN attribute search index): { "firstName": "Sophia", "pointsBalance": 1250, "tier": "Platinum" }
FASE 02 MOTORE DI POPOLAMENTO E FORMATTAZIONE CAMPI
Risolve {firstName}, {pointsBalance}, {serialNumber}, {expirationDate}
Applica numberStyle, currencyCode (ISO 4217), dateStyle, timeStyle
Sanifica attributedValue (consente <a href="..."> sui campi retro Apple)
Inserisce changeMessage con token %@ per avvisi push su lock-screen iOS
FASE 03A APPLE WALLET (pass.json)
"secondaryFields": [{ "key": "points_field", "label": "POINTS BALANCE", "value": 1250, "numberStyle": "PKNumberStyleDecimal" "changeMessage": "New balance: %@"
}]
FASE 03B GOOGLE WALLET (WalletObject)
"loyaltyPoints": { "label": "POINTS BALANCE", "balance": { "int": 1250 }
},
"textModulesData": [...]

Configurazione passo per passo nell'editor visuale

  1. 1
    Apra la sezione Proprietà personalizzate del modello e clicchi su + Aggiungi proprietà.
  2. 2
    Definisca esattamente Chiave proprietà (ad esempio firstName, memberTier, validUntil), Tipo di dato (field data type: text, number, currency, date, dateTime, time), regole di validazione Obbligatorio / Univoco ed eventuali valori predefiniti di fallback.
  3. 3
    Torni ai Campi fronte / retro nell'editor visuale.
  4. 4
    Clicchi dentro il valore di qualsiasi campo e digiti { per aprire il menu di autocompletamento con i propri Attributi personalizzati e i Token di sistema integrati (come {serialNumber}, {externalId}, {stamps}, {balance}, {tierName}, {expirationDate}).
  5. 5
    Nei punti in cui Apple Wallet e Google Wallet gestiscono diversamente il ritorno a capo delle etichette, imposti opzionalmente un Override Android per singolo campo.
Chip di variabile associata nell'ispettore campi
Chip di variabile associata nell'ispettore campi

Importante: Mantenga le Chiavi proprietà in formato camelCase minuscolo (holderName, validUntil). Quelle esatte chiavi diventano i nomi delle proprietà API nell'oggetto structured JSON attributes quando si emettono pass tramite /api/v1/passes o si mappano colonne CSV nelle importazioni batch. Inoltre, qualsiasi changeMessage configurato su un campo deve includere il segnaposto %@ (ad esempio "Your points balance is now %@"), altrimenti iOS sopprimerà silenziosamente la notifica di aggiornamento sulla schermata di blocco.

Specifica completa del modello Field

Ogni campo associato a un modello tramite request payload (headerFields, primaryFields, secondaryFields, auxiliaryFields, backFields, additionalInfoFields, footerFields mappati su field placement type: HEADER, PRIMARY, SECONDARY, AUXILIARY, BACK, ADDITIONALINFO, FOOTER) supporta le seguenti proprietà:

ProprietàTipoValori ammessi / FormatoComportamento e regole di piattaforma
keystringIdentificativo univoco per pass (es. balance_fld)Utilizzato da iOS e Android per calcolare le differenze tra aggiornamenti push
labelstringTesto statico o {variable}Mostrato in labelColor sopra o sotto il valore
value`string \number`Testo statico, numero, data ISO o {variable}Popolato in emissione/aggiornamento da Pass.attributes, externalId o token di sistema
changeMessagestringStringa contenente %@ (es. "Tier upgraded to %@")Attiva un avviso push nativo iOS in schermata di blocco quando value cambia; %@ viene sostituito dal nuovo valore formattato
textAlignmentPKTextAlignmentPKTextAlignmentLeft, PKTextAlignmentCenter, PKTextAlignmentRight, PKTextAlignmentNaturalControlla l'allineamento orizzontale nelle colonne dei campi frontali Apple Wallet
dateStylePKDateStylePKDateStyleNone, PKDateStyleShort, PKDateStyleMedium, PKDateStyleLong, PKDateStyleFullFormatta le stringhe data ISO 8601 secondo la lingua/area geografica del dispositivo del titolare
timeStylePKDateStylePKDateStyleNone, PKDateStyleShort, PKDateStyleMedium, PKDateStyleLong, PKDateStyleFullFormatta i componenti orari nel fuso orario locale del titolare
numberStylePKNumberStylePKNumberStyleDecimal, PKNumberStylePercent, PKNumberStyleScientific, PKNumberStyleSpellOutFormatta i valori numerici con separatori locali di migliaia e decimali
dataDetectorTypesPKDataDetectorType[]PKDataDetectorTypePhoneNumber, PKDataDetectorTypeLink, PKDataDetectorTypeAddress, PKDataDetectorTypeCalendarEvent, PKDataDetectorTypeNoneAbilita azioni interattive al tocco (chiama, apri URL, apri Mappe, aggiungi evento a calendario) sui campi sul retro
currencyCodestringCodice ISO 4217 a 3 lettere (EUR, USD, GBP, CHF)Formatta valori numerici come importi valutari localizzati in Apple e Google Wallet
attributedValuestringStringa anchor HTML (<a href="https://...">Label</a>)Supportato nei backFields di Apple Wallet per rendere cliccabili link web, tel: o mailto:

Regole per i tag anchor attributedValue in Apple Wallet

Apple Wallet non renderizza HTML arbitrario (<b>, <div>, <script>) all'interno dei campi del pass. Solo i tag anchor <a href="...">...</a> sono consentiti in attributedValue sui campi sul retro (back). Il serializzatore di Passinstance (apple-pass-field.serializer.ts) rimuove automaticamente i tag HTML non supportati e converte gli URL validi in voci cliccabili linksModuleData su Google Wallet.

attributes structured JSON a livello di pass e indicizzazione GIN database

Quando un pass viene creato o aggiornato, le coppie chiave-valore degli attributi personalizzati vengono memorizzate nella colonna structured JSON attributes della tabella pass. Per garantire filtraggi sotto il millisecondo su milioni di pass, Passinstance mantiene un indice dedicato database Generalized Inverted Index (attribute search index) su pass.attributes.

Questo indice alimenta:

  • Interrogazioni di coorti ad alta velocità tramite GET /api/v1/passes (filtrando per proprietà personalizzate come attributes.tier = "VIP" o attributes.city = "Berlin").
  • Segmentazione dell'audience in tempo reale in PassProjectSegment e Automazione Workflow.
  • Popolamento dinamico delle variabili senza costose join relazionali tra tabelle.

Esempio API: configurazione dei campi dinamici su un modello

Richiesta HTTP

PATCH /api/v1/templates/tmpl_01hxyz987654321 Header: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "fields": {
    "headerFields": [
      {
        "key": "wallet_balance",
        "label": "BALANCE",
        "value": "{creditBalance}",
        "currencyCode": "EUR",
        "textAlignment": "PKTextAlignmentRight",
        "changeMessage": "Your card balance was updated to %@"
      }
    ],
    "primaryFields": [
      {
        "key": "holder_name",
        "label": "MEMBER",
        "value": "{firstName} {lastName}",
        "textAlignment": "PKTextAlignmentLeft"
      }
    ],
    "secondaryFields": [
      {
        "key": "member_since",
        "label": "VALID UNTIL",
        "value": "{expirationDate}",
        "dateStyle": "PKDateStyleMedium",
        "timeStyle": "PKDateStyleNone"
      }
    ],
    "backFields": [
      {
        "key": "support_link",
        "label": "CUSTOMER CONCIERGE",
        "value": "https://artisan-roasters.example.com/support",
        "attributedValue": "<a href='https://artisan-roasters.example.com/support'>Contact VIP Concierge</a>"
      }
    ]
  }
}

Risposta HTTP (200 OK)

JSON
{
  "success": true,
  "data": {
    "id": "tmpl_01hxyz987654321",
    "rowKind": "DRAFT",
    "updatedAt": "2026-11-15T11:20:00.000Z"
  },
  "statusCode": 200
}

Prosegua per scoprire come validare i controlli preliminari e promuovere le bozze in Versioni modello e pubblicazione.

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.