Vue d'ensemble
Personnaliser des cartes Wallet pour des milliers ou des millions de détenteurs repose sur les propriétés personnalisées (définitions de schéma déclarées sur votre modèle) associées à des liaisons {variable} dans le modèle Field à travers les zones header, primary, secondary, auxiliary, back et footer. Au moment de la génération et des mises à jour, Passinstance hydrate ces jetons à partir du dictionnaire structured JSON attributes du passe et formate nativement les dates, nombres, devises et notifications sur l'écran verrouillé pour Apple Wallet et Google Wallet.

Architecture système : hydratation des champs dynamiques & indexation
Configuration étape par étape dans l'éditeur visuel
-
1
Ouvrez la section Propriétés personnalisées (Custom properties) du modèle et cliquez sur + Add property.
-
2
Définissez la clé de propriété exacte (par exemple
firstName,memberTier,validUntil), le type de données (field data type :text,number,currency,date,dateTime,time), les règles de validation Required / Unique ainsi que d'éventuelles valeurs de repli par défaut. -
3
Revenez aux Champs recto / verso dans l'éditeur visuel.
-
4
Cliquez à l'intérieur de n'importe quelle valeur de champ et saisissez
{pour ouvrir le menu d'autocomplétion présentant vos attributs personnalisés ainsi que les jetons système intégrés (tels que{serialNumber},{externalId},{stamps},{balance},{tierName},{expirationDate}). -
5
Lorsque Apple Wallet et Google Wallet diffèrent sur la mise en page des libellés, configurez si nécessaire un remplacement Android (Android Override) par champ.

Important : Conservez vos clés de propriété en
camelCasecommençant par une minuscule (holderName,validUntil). Ces clés exactes deviennent les noms de propriétés dans l'objet structured JSONattributeslors de l'émission de passes via/api/v1/passesou du mapping de colonnes CSV lors des imports en lot. De plus, toutchangeMessageconfiguré sur un champ doit inclure le jeton de remplacement%@(ex."Votre solde de points est désormais de %@"), sinon iOS masquera silencieusement la notification de mise à jour sur l'écran verrouillé.
Spécification complète du modèle Field
Chaque champ rattaché à un modèle via request payload (headerFields, primaryFields, secondaryFields, auxiliaryFields, backFields, additionalInfoFields, footerFields correspondant à field placement type : HEADER, PRIMARY, SECONDARY, AUXILIARY, BACK, ADDITIONALINFO, FOOTER) prend en charge les propriétés suivantes :
| Propriété | Type | Valeurs / Format autorisés | Comportement & règles par plateforme | |
|---|---|---|---|---|
key | string | Identifiant unique par passe (ex. balance_fld) | Utilisé par iOS et Android pour comparer les valeurs de champs entre deux mises à jour push | |
label | string | Libellé fixe ou {variable} | Affiché en labelColor au-dessus ou au-dessous de la valeur | |
value | `string \ | number` | Texte fixe, nombre, date ISO ou {variable} | Hydraté à l'émission ou lors des mises à jour depuis Pass.attributes, externalId ou les jetons système |
changeMessage | string | Chaîne contenant %@ (ex. "Palier passé à %@") | Déclenche une notification push native sur l'écran verrouillé iOS quand value change ; %@ est remplacé par la nouvelle valeur formatée | |
textAlignment | PKTextAlignment | PKTextAlignmentLeft, PKTextAlignmentCenter, PKTextAlignmentRight, PKTextAlignmentNatural | Contrôle l'alignement horizontal dans les colonnes de champs au recto sur Apple Wallet | |
dateStyle | PKDateStyle | PKDateStyleNone, PKDateStyleShort, PKDateStyleMedium, PKDateStyleLong, PKDateStyleFull | Formate les chaînes de date ISO 8601 selon les réglages régionaux de l'appareil du détenteur | |
timeStyle | PKDateStyle | PKDateStyleNone, PKDateStyleShort, PKDateStyleMedium, PKDateStyleLong, PKDateStyleFull | Formate l'heure dans le fuseau horaire local du détenteur | |
numberStyle | PKNumberStyle | PKNumberStyleDecimal, PKNumberStylePercent, PKNumberStyleScientific, PKNumberStyleSpellOut | Formate les valeurs numériques avec les séparateurs de milliers et décimales adaptés à la locale | |
dataDetectorTypes | PKDataDetectorType[] | PKDataDetectorTypePhoneNumber, PKDataDetectorTypeLink, PKDataDetectorTypeAddress, PKDataDetectorTypeCalendarEvent, PKDataDetectorTypeNone | Active les actions interactives au toucher (appeler, ouvrir un lien, ouvrir Plans, ajouter au calendrier) sur les champs du verso | |
currencyCode | string | Code ISO 4217 à 3 lettres (EUR, USD, GBP, CHF) | Formate les montants numériques selon la devise localisée dans Apple et Google Wallet | |
attributedValue | string | Chaîne d'ancre HTML (<a href="https://...">Label</a>) | Pris en charge sur les champs backFields d'Apple Wallet pour afficher des liens web, tel: ou mailto: cliquables |
Règles des balises d'ancre attributedValue dans Apple Wallet
Apple Wallet n'interprète pas le HTML arbitraire (<b>, <div>, <script>) à l'intérieur des champs d'un passe. Seules les balises d'ancre <a href="...">...</a> sont autorisées dans attributedValue sur les champs back. Le sérialiseur de Passinstance (apple-pass-field.serializer.ts) supprime automatiquement les balises HTML non prises en charge et convertit les URLs valides en entrées cliquables linksModuleData sur Google Wallet.
Attributs structured JSON au niveau du passe & indexation GIN database
Lorsqu'un passe est créé ou mis à jour, les paires clé-valeur d'attributs personnalisés sont stockées dans la colonne structured JSON attributes de la table pass. Pour garantir un filtrage en moins d'une milliseconde sur des millions de passes, Passinstance maintient un index inversé généralisé database dédié (attribute search index) sur pass.attributes.
Cet index alimente :
-
Les requêtes rapides par cohorte via
GET /api/v1/passes(filtrage sur des propriétés personnalisées commeattributes.tier = "VIP"ouattributes.city = "Berlin"). -
La segmentation d'audience en temps réel dans
PassProjectSegmentet l'automatisation de workflows. -
L'hydratation dynamique des variables sans jointures relationnelles coûteuses.
Exemple API : configurer des champs dynamiques sur un modèle
Requête HTTP
PATCH /api/v1/templates/tmpl_01hxyz987654321 En-têtes : 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>"
}
]
}
}
Réponse HTTP (200 OK)
{
"success": true,
"data": {
"id": "tmpl_01hxyz987654321",
"rowKind": "DRAFT",
"updatedAt": "2026-11-15T11:20:00.000Z"
},
"statusCode": 200
}
Poursuivez avec Versions de modèles & publication pour apprendre à valider la liste de contrôle et publier vos brouillons.
