Skip to content
Guide du centre d'aide · Modèles de passesPhase d'intégration 2
5 min de lectureVérifié 2026-11-16

Champs dynamiques & personnalisation

Reliez propriétés personnalisées et jetons système par saisie {variableName} sur les zones Apple et Google Wallet.

Dans ce guide

Visites interactives de l'interface

Ouvrir dans le guide en 6 phases

Inspectez les écrans exacts du tableau de bord et les zooms annotés liés à ce guide.

Focus interface zoomé1 / 2
Éléments clés de l'interface

Autocomplétion des variables dynamiques (Zoom)

Saisissez « { » dans le champ Valeur pour rechercher et insérer un attribut personnalisé ({passStatus}) ou un champ système ({storedValue}, {userProvidedId}).

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.

La saisie d'une accolade ouvrante déclenche l'autocomplétion des variables
La saisie d'une accolade ouvrante déclenche l'autocomplétion des variables

Architecture système : hydratation des champs dynamiques & indexation

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX D'ARCHITECTURE SYSTÈME : HYDRATATION DES CHAMPS & SÉRIALISATION WALLET
ÉTAPE 01 FICHE PASSE (Modèle Pass dans database)
serialNumber : "PI-884920-AB"
attributes (structured JSON indexé via GIN attribute search index) : { "firstName": "Sophia", "pointsBalance": 1250, "tier": "Platinum" }
ÉTAPE 02 MOTEUR D'HYDRATATION & DE FORMATAGE DES CHAMPS
Résout {firstName}, {pointsBalance}, {serialNumber}, {expirationDate}
Applique numberStyle, currencyCode (ISO 4217), dateStyle, timeStyle
Assainit attributedValue (autorise <a href="..."> au verso Apple)
Injecte changeMessage avec jeton %@ pour les alertes push verrouillage iOS
ÉTAPE 03A APPLE WALLET (pass.json)
"secondaryFields": [{ "key": "points_field", "label": "POINTS BALANCE", "value": 1250, "numberStyle": "PKNumberStyleDecimal" "changeMessage": "New balance: %@"
}]
ÉTAPE 03B GOOGLE WALLET (WalletObject)
"loyaltyPoints": { "label": "POINTS BALANCE", "balance": { "int": 1250 }
},
"textModulesData": [...]

Configuration étape par étape dans l'éditeur visuel

  1. 1
    Ouvrez la section Propriétés personnalisées (Custom properties) du modèle et cliquez sur + Add property.
  2. 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. 3
    Revenez aux Champs recto / verso dans l'éditeur visuel.
  4. 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. 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.
Pastille de variable liée dans l'inspecteur de champ
Pastille de variable liée dans l'inspecteur de champ

Important : Conservez vos clés de propriété en camelCase commençant par une minuscule (holderName, validUntil). Ces clés exactes deviennent les noms de propriétés dans l'objet structured JSON attributes lors de l'émission de passes via /api/v1/passes ou du mapping de colonnes CSV lors des imports en lot. De plus, tout changeMessage configuré 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éTypeValeurs / Format autorisésComportement & règles par plateforme
keystringIdentifiant unique par passe (ex. balance_fld)Utilisé par iOS et Android pour comparer les valeurs de champs entre deux mises à jour push
labelstringLibellé 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
changeMessagestringChaî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
textAlignmentPKTextAlignmentPKTextAlignmentLeft, PKTextAlignmentCenter, PKTextAlignmentRight, PKTextAlignmentNaturalContrôle l'alignement horizontal dans les colonnes de champs au recto sur Apple Wallet
dateStylePKDateStylePKDateStyleNone, PKDateStyleShort, PKDateStyleMedium, PKDateStyleLong, PKDateStyleFullFormate les chaînes de date ISO 8601 selon les réglages régionaux de l'appareil du détenteur
timeStylePKDateStylePKDateStyleNone, PKDateStyleShort, PKDateStyleMedium, PKDateStyleLong, PKDateStyleFullFormate l'heure dans le fuseau horaire local du détenteur
numberStylePKNumberStylePKNumberStyleDecimal, PKNumberStylePercent, PKNumberStyleScientific, PKNumberStyleSpellOutFormate les valeurs numériques avec les séparateurs de milliers et décimales adaptés à la locale
dataDetectorTypesPKDataDetectorType[]PKDataDetectorTypePhoneNumber, PKDataDetectorTypeLink, PKDataDetectorTypeAddress, PKDataDetectorTypeCalendarEvent, PKDataDetectorTypeNoneActive les actions interactives au toucher (appeler, ouvrir un lien, ouvrir Plans, ajouter au calendrier) sur les champs du verso
currencyCodestringCode ISO 4217 à 3 lettres (EUR, USD, GBP, CHF)Formate les montants numériques selon la devise localisée dans Apple et Google Wallet
attributedValuestringChaî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 comme attributes.tier = "VIP" ou attributes.city = "Berlin").
  • La segmentation d'audience en temps réel dans PassProjectSegment et 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

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)

JSON
{
  "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.

Prêt à lancer votre premier programme de cartes Wallet ?

Créez votre espace de travail, configurez votre modèle et testez une vraie carte dans Apple Wallet et Google Wallet avant de déployer à grande échelle.