Ü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.

Systemarchitektur: Dynamische Feldhydrierung & Indizierung
Schritt-für-Schritt-Einrichtung im visuellen Editor
-
1
Öffnen Sie in der Vorlage den Bereich Benutzerdefinierte Eigenschaften (Custom properties) und klicken Sie auf + Eigenschaft hinzufügen.
-
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
Wechseln Sie im visuellen Editor zurück zu Vorder-/Rückseiten-Felder.
-
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
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.

Wichtig: Halten Sie Property Keys konsequent in Kleinbuchstaben nach dem
camelCase-Schema (holderName,validUntil). Genau diese Schlüssel dienen als Eigenschaftsnamen im structured JSON-Objektattributesbei der Pass-Ausgabe über/api/v1/passesoder bei der CSV-Spaltenzuordnung im Massenimport. Darüber hinaus muss jede auf einem Feld konfiguriertechangeMessageden 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:
| Eigenschaft | Typ | Erlaubte Werte / Format | Plattformverhalten & Regeln | |
|---|---|---|---|---|
key | string | Pro Pass eindeutiger Bezeichner (z. B. balance_fld) | Wird von iOS und Android zum Abgleich geänderter Feldwerte bei Push-Updates genutzt | |
label | string | Statische 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 |
changeMessage | string | Zeichenkette 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 | |
textAlignment | PKTextAlignment | PKTextAlignmentLeft, PKTextAlignmentCenter, PKTextAlignmentRight, PKTextAlignmentNatural | Steuert die horizontale Ausrichtung in Spalten der Apple-Wallet-Vorderseite | |
dateStyle | PKDateStyle | PKDateStyleNone, PKDateStyleShort, PKDateStyleMedium, PKDateStyleLong, PKDateStyleFull | Formatiert ISO-8601-Datumsangaben gemäß der Gerätesprache der Karteninhaberin/des -inhabers | |
timeStyle | PKDateStyle | PKDateStyleNone, PKDateStyleShort, PKDateStyleMedium, PKDateStyleLong, PKDateStyleFull | Formatiert Zeitkomponenten in der lokalen Zeitzone des Geräts | |
numberStyle | PKNumberStyle | PKNumberStyleDecimal, PKNumberStylePercent, PKNumberStyleScientific, PKNumberStyleSpellOut | Formatiert numerische Werte mit sprachspezifischen Tausender- und Dezimaltrennzeichen | |
dataDetectorTypes | PKDataDetectorType[] | PKDataDetectorTypePhoneNumber, PKDataDetectorTypeLink, PKDataDetectorTypeAddress, PKDataDetectorTypeCalendarEvent, PKDataDetectorTypeNone | Aktiviert interaktive Tipp-Aktionen (Anrufen, URL öffnen, Karten öffnen, Kalendereintrag) auf Rückseitenfeldern | |
currencyCode | string | Dreistelliger ISO-4217-Code (EUR, USD, GBP, CHF) | Formatiert Zahlenwerte als lokalisierte Währungsbeträge in Apple & Google Wallet | |
attributedValue | string | HTML-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 wieattributes.tier = "VIP"oderattributes.city = "Berlin"). -
Echtzeit-Zielgruppensegmentierung in
PassProjectSegmentund 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
{
"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)
{
"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.
