Skip to content
Hilfecenter-Anleitung · Pass-VorlagenOnboarding-Phase 2
4 Min. LesezeitGeprüft 2026-11-16

Dynamische Felder & Personalisierung

Verbinden Sie benutzerdefinierte Eigenschaften und Systemtokens über {variableName}-Autovervollständigung in Apple & Google Wallet.

In dieser Anleitung

Prüfen Sie passende Dashboard-Bereiche, Steuerelemente und Zoom-Hinweise zu diesem Thema.

Vergrößerter UI-Fokus1 / 2
Wichtige UI-Elemente

Autovervollständigung für dynamische Variablen (Zoom)

Tippen Sie „{“ in ein Wert-Feld, um benutzerdefinierte Attribute ({passStatus}) oder Systemfelder ({storedValue}, {userProvidedId}, {lastUsage}) einzufügen.

Überblick

Die Personalisierung von Wallet-Pässen für Tausende oder Millionen von Karteninhaberinnen und -inhabern basiert auf benutzerdefinierten Eigenschaften (auf der Vorlage deklarierte Schemadefinitionen) in Verbindung mit {variable}-Bindungen innerhalb des Field-Modells über die Zonen header, primary, secondary, auxiliary, back und footer. Bei der Pass-Erzeugung und bei Updates befüllt Passinstance diese Tokens aus dem structured JSON-Objekt attributes des Pass-Datensatzes und formatiert Daten, Zahlen, Währungen sowie Sperrbildschirm-Push-Mitteilungen nativ für Apple Wallet und Google Wallet.

Eingabe einer geschweiften Klammer öffnet die Variablen-Autovervollständigung
Eingabe einer geschweiften Klammer öffnet die Variablen-Autovervollständigung

Systemarchitektur: Dynamische Feldhydrierung & Indizierung

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
DYNAMISCHE FELDHYDRIERUNG & WALLET-SERIALISIERUNG
STUFE 01 PASS-DATENSATZ (Pass-Modell in database)
serialNumber: "PI-884920-AB"
attributes (structured JSON, indiziert über GIN attribute search index): { "firstName": "Sophia", "pointsBalance": 1250, "tier": "Platinum" }
STUFE 02 FELDHYDRIERUNGS- & FORMATIERUNGS-ENGINE
Löst {firstName}, {pointsBalance}, {serialNumber}, {expirationDate} auf
Wendet numberStyle, currencyCode (ISO 4217), dateStyle, timeStyle an
Bereinigt attributedValue (erlaubt <a href="..."> auf Apple-Rückseiten)
Fügt changeMessage mit %@-Token für iOS-Sperrbildschirm-Alerts ein
STUFE 03A APPLE WALLET (pass.json)
"secondaryFields": [{ "key": "points_field", "label": "POINTS BALANCE", "value": 1250, "numberStyle": "PKNumberStyleDecimal" "changeMessage": "New balance: %@"
}]
STUFE 03B GOOGLE WALLET (WalletObject)
"loyaltyPoints": { "label": "POINTS BALANCE", "balance": { "int": 1250 }
},
"textModulesData": [...]

Schritt-für-Schritt-Einrichtung im visuellen Editor

  1. 1
    Öffnen Sie in der Vorlage den Bereich Benutzerdefinierte Eigenschaften (Custom properties) und klicken Sie auf + Eigenschaft hinzufügen.
  2. 2
    Definieren Sie den exakten Property Key (z. B. firstName, memberTier, validUntil), den Datentyp (field data type: text, number, currency, date, dateTime, time), Validierungsregeln (Pflichtfeld / Eindeutig) sowie optionale Standard-Fallbackwerte.
  3. 3
    Wechseln Sie im visuellen Editor zurück zu Vorder-/Rückseiten-Felder.
  4. 4
    Klicken Sie in ein beliebiges Feldwert-Eingabefeld und tippen Sie {, um das Autovervollständigungsmenü mit Ihren benutzerdefinierten Attributen und integrierten Systemtokens (wie {serialNumber}, {externalId}, {stamps}, {balance}, {tierName}, {expirationDate}) zu öffnen.
  5. 5
    Falls sich Apple Wallet und Google Wallet beim Zeilenumbruch oder Wortlaut von Labels unterscheiden sollen, können Sie pro Feld optional ein Android Override festlegen.
Verknüpfter Variablen-Chip im Feld-Inspektor
Verknüpfter Variablen-Chip im Feld-Inspektor

Wichtig: Halten Sie Property Keys konsequent in Kleinbuchstaben nach dem camelCase-Schema (holderName, validUntil). Genau diese Schlüssel dienen als Eigenschaftsnamen im structured JSON-Objekt attributes bei der Pass-Ausgabe über /api/v1/passes oder bei der CSV-Spaltenzuordnung im Massenimport. Darüber hinaus muss jede auf einem Feld konfigurierte changeMessage den Platzhalter %@ enthalten (z. B. "Ihr neuer Punktestand lautet %@"), da iOS sonst die Sperrbildschirm-Benachrichtigung stillschweigend unterdrückt.

Vollständige Spezifikation des Field-Modells

Jedes über request payload an eine Vorlage angehängte Feld (headerFields, primaryFields, secondaryFields, auxiliaryFields, backFields, additionalInfoFields, footerFields, zugeordnet zu field placement type: HEADER, PRIMARY, SECONDARY, AUXILIARY, BACK, ADDITIONALINFO, FOOTER) unterstützt folgende Eigenschaften:

EigenschaftTypErlaubte Werte / FormatPlattformverhalten & Regeln
keystringPro Pass eindeutiger Bezeichner (z. B. balance_fld)Wird von iOS und Android zum Abgleich geänderter Feldwerte bei Push-Updates genutzt
labelstringStatische Beschriftung oder {variable}Wird in labelColor über bzw. neben dem Wert angezeigt
value`string \number`Statischer Text, Zahl, ISO-Datum oder {variable}Wird bei Ausgabe/Update aus Pass.attributes, externalId oder Systemtokens befüllt
changeMessagestringZeichenkette mit %@ (z. B. "Stufe auf %@ aktualisiert")Löst eine native iOS-Sperrbildschirm-Push-Meldung aus, wenn sich value ändert; %@ wird durch den neuen formatierten Wert ersetzt
textAlignmentPKTextAlignmentPKTextAlignmentLeft, PKTextAlignmentCenter, PKTextAlignmentRight, PKTextAlignmentNaturalSteuert die horizontale Ausrichtung in Spalten der Apple-Wallet-Vorderseite
dateStylePKDateStylePKDateStyleNone, PKDateStyleShort, PKDateStyleMedium, PKDateStyleLong, PKDateStyleFullFormatiert ISO-8601-Datumsangaben gemäß der Gerätesprache der Karteninhaberin/des -inhabers
timeStylePKDateStylePKDateStyleNone, PKDateStyleShort, PKDateStyleMedium, PKDateStyleLong, PKDateStyleFullFormatiert Zeitkomponenten in der lokalen Zeitzone des Geräts
numberStylePKNumberStylePKNumberStyleDecimal, PKNumberStylePercent, PKNumberStyleScientific, PKNumberStyleSpellOutFormatiert numerische Werte mit sprachspezifischen Tausender- und Dezimaltrennzeichen
dataDetectorTypesPKDataDetectorType[]PKDataDetectorTypePhoneNumber, PKDataDetectorTypeLink, PKDataDetectorTypeAddress, PKDataDetectorTypeCalendarEvent, PKDataDetectorTypeNoneAktiviert interaktive Tipp-Aktionen (Anrufen, URL öffnen, Karten öffnen, Kalendereintrag) auf Rückseitenfeldern
currencyCodestringDreistelliger ISO-4217-Code (EUR, USD, GBP, CHF)Formatiert Zahlenwerte als lokalisierte Währungsbeträge in Apple & Google Wallet
attributedValuestringHTML-Anchor-Tag (<a href="https://...">Label</a>)Wird in Apple-Wallet-backFields unterstützt, um klickbare Web-, tel:- oder mailto:-Links darzustellen

Regeln für attributedValue-Anchor-Tags in Apple Wallet

Apple Wallet rendert kein beliebiges HTML (<b>, <div>, <script>) innerhalb von Pass-Feldern. Ausschließlich <a href="...">...</a>-Anchor-Tags sind in attributedValue auf back-Feldern zulässig. Der Passinstance-Serializer (apple-pass-field.serializer.ts) entfernt nicht unterstützte HTML-Tags automatisch und wandelt gültige URLs für Google Wallet in anklickbare linksModuleData-Einträge um.

structured JSON-attributes auf Pass-Ebene & database-GIN-Indizierung

Beim Erstellen oder Aktualisieren eines Passes werden benutzerdefinierte Schlüssel-Wert-Paare in der structured JSON-Spalte attributes der Tabelle pass gespeichert. Um Abfragen im Sub-Millisekundenbereich über Millionen von Pässen zu gewährleisten, pflegt Passinstance einen dedizierten database-Generalized-Inverted-Index (attribute search index) auf pass.attributes.

Dieser Index beschleunigt:

  • Schnelle Kohorten-Abfragen über GET /api/v1/passes (Filterung nach benutzerdefinierten Eigenschaften wie attributes.tier = "VIP" oder attributes.city = "Berlin").
  • Echtzeit-Zielgruppensegmentierung in PassProjectSegment und der Workflow-Automatisierung.
  • Dynamische Variablenauflösung ohne aufwendige relationale Tabellen-Joins.

API-Beispiel: Dynamische Felder auf einer Vorlage konfigurieren

HTTP-Anfrage

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>"
      }
    ]
  }
}

HTTP-Antwort (200 OK)

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

Erfahren Sie im nächsten Schritt, wie Sie Freigabeprüfungen validieren und Entwürfe produktiv schalten: Vorlagenversionen & Veröffentlichung.

Bereit für Ihr erstes Wallet-Kartenprogramm?

Erstellen Sie Ihren Workspace, konfigurieren Sie Ihre Vorlage und testen Sie eine echte Karte in Apple Wallet und Google Wallet, bevor Sie skalieren.