Overzicht
Het personaliseren van wallet-passen voor duizenden of miljoenen pashouders steunt op Aangepaste eigenschappen (schemadefinities op uw sjabloon) in combinatie met {variable}-koppelingen binnen het Field-model over de zones header, primary, secondary, auxiliary, back en footer. Tijdens het genereren en bijwerken van passen vult Passinstance deze tokens vanuit het structured JSON-woordenboek attributes van het pasrecord en formatteert het datums, getallen, valuta's en pushmeldingen op het toegangsscherm native voor Apple Wallet en Google Wallet.

Systeemarchitectuur: dynamische veldvulling & indexering
Stapsgewijze instelling in de visuele editor
-
1
Open het gedeelte Aangepaste eigenschappen van het sjabloon en klik op + Eigenschap toevoegen.
-
2
Definieer de exacte Eigenschapssleutel (bijvoorbeeld
firstName,memberTier,validUntil), het Gegevenstype (field data type:text,number,currency,date,dateTime,time), de validatieregels Verplicht / Uniek en eventuele standaard terugvalwaarden. -
3
Ga terug naar Voor- & achterkantvelden in de visuele editor.
-
4
Klik in een willekeurige veldwaarde en typ
{om het menu voor automatische aanvulling te openen met zowel uw Aangepaste eigenschappen als ingebouwde Systeemtokens (zoals{serialNumber},{externalId},{stamps},{balance},{tierName},{expirationDate}). -
5
Waar Apple Wallet en Google Wallet verschillen in labelafbreking, kunt u optioneel per veld een Android-overschrijving instellen.

Belangrijk: Houd Eigenschapssleutels in lowercase
camelCase(holderName,validUntil). Die exacte sleutels worden de API-eigenschapsnamen binnen het structured JSON-objectattributesbij het uitgeven van passen via/api/v1/passesof bij het toewijzen van CSV-kolommen tijdens batchimports. Daarnaast moet elkechangeMessageop een veld de tijdelijke aanduiding%@bevatten (bijv."Uw puntensaldo is nu %@"), anders onderdrukt iOS de updatemelding op het toegangsscherm zonder waarschuwing.
Volledige specificatie van het Field-model
Elk veld dat via request payload (headerFields, primaryFields, secondaryFields, auxiliaryFields, backFields, additionalInfoFields, footerFields gekoppeld aan field placement type: HEADER, PRIMARY, SECONDARY, AUXILIARY, BACK, ADDITIONALINFO, FOOTER) aan een sjabloon wordt toegevoegd, ondersteunt de volgende eigenschappen:
| Eigenschap | Type | Toegestane waarden / formaat | Platformgedrag & regels | |
|---|---|---|---|---|
key | string | Unieke identificatie per pas (bijv. balance_fld) | Gebruikt door iOS en Android om veldwaarden te vergelijken tijdens pushupdates | |
label | string | Statisch bijschrift of {variable} | Weergegeven in labelColor boven of onder de waarde | |
value | `string \ | number` | Statische tekst, getal, ISO-datum of {variable} | Gevuld bij uitgifte/update vanuit Pass.attributes, externalId of systeemtokens |
changeMessage | string | Tekst met %@ (bijv. "Niveau verhoogd naar %@") | Activeert een native iOS-pushmelding op het toegangsscherm wanneer value wijzigt; %@ wordt vervangen door de nieuwe opgemaakte waarde | |
textAlignment | PKTextAlignment | PKTextAlignmentLeft, PKTextAlignmentCenter, PKTextAlignmentRight, PKTextAlignmentNatural | Bepaalt de horizontale uitlijning in Apple Wallet-veldkolommen op de voorkant | |
dateStyle | PKDateStyle | PKDateStyleNone, PKDateStyleShort, PKDateStyleMedium, PKDateStyleLong, PKDateStyleFull | Formatteert ISO 8601-datumstrings volgens de taalinstelling van het apparaat | |
timeStyle | PKDateStyle | PKDateStyleNone, PKDateStyleShort, PKDateStyleMedium, PKDateStyleLong, PKDateStyleFull | Formatteert tijdelementen in de lokale tijdzone van de pashouder | |
numberStyle | PKNumberStyle | PKNumberStyleDecimal, PKNumberStylePercent, PKNumberStyleScientific, PKNumberStyleSpellOut | Formatteert numerieke veldwaarden met lokale duizend- en decimaalscheidingstekens | |
dataDetectorTypes | PKDataDetectorType[] | PKDataDetectorTypePhoneNumber, PKDataDetectorTypeLink, PKDataDetectorTypeAddress, PKDataDetectorTypeCalendarEvent, PKDataDetectorTypeNone | Schakelt interactieve tikacties in (bellen, URL openen, Kaarten openen, agenda-afspraak toevoegen) op achterkantvelden | |
currencyCode | string | ISO 4217 3-lettercode (EUR, USD, GBP, CHF) | Formatteert numerieke waarden als gelokaliseerde valutabedragen in Apple & Google Wallet | |
attributedValue | string | HTML-ankerstring (<a href="https://...">Label</a>) | Ondersteund op backFields van Apple Wallet om klikbare web-, tel:- of mailto:-links weer te geven |
Regels voor attributedValue-ankertags in Apple Wallet
Apple Wallet rendert geen willekeurige HTML (<b>, <div>, <script>) binnen pasvelden. Alleen <a href="...">...</a>-ankertags zijn toegestaan in attributedValue op back-velden. De serializer van Passinstance (apple-pass-field.serializer.ts) verwijdert niet-ondersteunde HTML-tags automatisch en zet geldige URL's om in klikbare linksModuleData-items op Google Wallet.
structured JSON attributes op pasniveau & database GIN-indexering
Wanneer een pas wordt aangemaakt of bijgewerkt, worden aangepaste sleutel-waardeparen opgeslagen in de structured JSON-kolom attributes van de tabel pass. Om filtering over miljoenen passen binnen milliseconden uit te voeren, onderhoudt Passinstance een speciale database Generalized Inverted Index (attribute search index) op pass.attributes.
Deze index maakt het volgende mogelijk:
-
Razendsnelle cohortquery's via
GET /api/v1/passes(filteren op aangepaste eigenschappen zoalsattributes.tier = "VIP"ofattributes.city = "Berlin"). -
Realtime doelgroepsegmentatie in
PassProjectSegmenten Workflowautomatisering. -
Dynamische variabele-invulling zonder kostbare relationele tabeljoins.
API-voorbeeld: dynamische velden configureren op een sjabloon
HTTP-verzoek
PATCH /api/v1/templates/tmpl_01hxyz987654321 Headers: 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-respons (200 OK)
{
"success": true,
"data": {
"id": "tmpl_01hxyz987654321",
"rowKind": "DRAFT",
"updatedAt": "2026-11-15T11:20:00.000Z"
},
"statusCode": 200
}
Leer vervolgens hoe u publicatiecontroles valideert en concepten promoveert in Sjabloonversies & publicatie.
