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.

Architettura di sistema: popolamento campi dinamici e indicizzazione
Configurazione passo per passo nell'editor visuale
-
1
Apra la sezione Proprietà personalizzate del modello e clicchi su + Aggiungi proprietà.
-
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
Torni ai Campi fronte / retro nell'editor visuale.
-
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
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.

Importante: Mantenga le Chiavi proprietà in formato
camelCaseminuscolo (holderName,validUntil). Quelle esatte chiavi diventano i nomi delle proprietà API nell'oggetto structured JSONattributesquando si emettono pass tramite/api/v1/passeso si mappano colonne CSV nelle importazioni batch. Inoltre, qualsiasichangeMessageconfigurato 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à | Tipo | Valori ammessi / Formato | Comportamento e regole di piattaforma | |
|---|---|---|---|---|
key | string | Identificativo univoco per pass (es. balance_fld) | Utilizzato da iOS e Android per calcolare le differenze tra aggiornamenti push | |
label | string | Testo 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 |
changeMessage | string | Stringa contenente %@ (es. "Tier upgraded to %@") | Attiva un avviso push nativo iOS in schermata di blocco quando value cambia; %@ viene sostituito dal nuovo valore formattato | |
textAlignment | PKTextAlignment | PKTextAlignmentLeft, PKTextAlignmentCenter, PKTextAlignmentRight, PKTextAlignmentNatural | Controlla l'allineamento orizzontale nelle colonne dei campi frontali Apple Wallet | |
dateStyle | PKDateStyle | PKDateStyleNone, PKDateStyleShort, PKDateStyleMedium, PKDateStyleLong, PKDateStyleFull | Formatta le stringhe data ISO 8601 secondo la lingua/area geografica del dispositivo del titolare | |
timeStyle | PKDateStyle | PKDateStyleNone, PKDateStyleShort, PKDateStyleMedium, PKDateStyleLong, PKDateStyleFull | Formatta i componenti orari nel fuso orario locale del titolare | |
numberStyle | PKNumberStyle | PKNumberStyleDecimal, PKNumberStylePercent, PKNumberStyleScientific, PKNumberStyleSpellOut | Formatta i valori numerici con separatori locali di migliaia e decimali | |
dataDetectorTypes | PKDataDetectorType[] | PKDataDetectorTypePhoneNumber, PKDataDetectorTypeLink, PKDataDetectorTypeAddress, PKDataDetectorTypeCalendarEvent, PKDataDetectorTypeNone | Abilita azioni interattive al tocco (chiama, apri URL, apri Mappe, aggiungi evento a calendario) sui campi sul retro | |
currencyCode | string | Codice ISO 4217 a 3 lettere (EUR, USD, GBP, CHF) | Formatta valori numerici come importi valutari localizzati in Apple e Google Wallet | |
attributedValue | string | Stringa 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 comeattributes.tier = "VIP"oattributes.city = "Berlin"). -
Segmentazione dell'audience in tempo reale in
PassProjectSegmente 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
{
"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)
{
"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.
