Skip to content
Helpcentrum-gids · Pass-sjablonenOnboardingfase 2
4 min leestijdGecontroleerd 2026-11-16

Dynamische velden & personalisatie

Koppel aangepaste kenmerken en systeemtokens via {variableName}-aanvulling in Apple en Google Wallet.

In deze gids

Interactieve UI-weergaven

Openen in onboardinggids (6 fasen)

Bekijk de exacte dashboardpanelen, knoppen en ingezoomde toelichtingen bij deze gids.

Ingezoomde UI-focus1 / 2
Belangrijke UI-onderdelen

Automatisch aanvullen van dynamische variabelen (Ingesneden)

Typ '{' in een Waarde-veld om aangepaste attributen ({passStatus}) of systeemvelden ({storedValue}, {userProvidedId}, {lastUsage}) te zoeken en in te voegen.

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.

Het typen van een accolade activeert automatische variabele-aanvulling
Het typen van een accolade activeert automatische variabele-aanvulling

Systeemarchitectuur: dynamische veldvulling & indexering

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
DYNAMISCHE VELDVULLING & WALLET-SERIALISATIE
FASE 01 PASRECORD (Pass-model in database)
serialNumber: "PI-884920-AB"
attributes (structured JSON geïndexeerd via GIN attribute search index): { "firstName": "Sophia", "pointsBalance": 1250, "tier": "Platinum" }
FASE 02 ENGINE VOOR VELDVULLING & OPMAAK
Vervangt {firstName}, {pointsBalance}, {serialNumber}, {expirationDate}
Past numberStyle, currencyCode (ISO 4217), dateStyle, timeStyle toe
Schoont attributedValue op (staat <a href="..."> toe op Apple-achterkant)
Voegt changeMessage met %@-token in voor iOS-toegangsschermmeldingen
FASE 03A APPLE WALLET (pass.json)
"secondaryFields": [{ "key": "points_field", "label": "POINTS BALANCE", "value": 1250, "numberStyle": "PKNumberStyleDecimal" "changeMessage": "New balance: %@"
}]
FASE 03B GOOGLE WALLET (WalletObject)
"loyaltyPoints": { "label": "POINTS BALANCE", "balance": { "int": 1250 }
},
"textModulesData": [...]

Stapsgewijze instelling in de visuele editor

  1. 1
    Open het gedeelte Aangepaste eigenschappen van het sjabloon en klik op + Eigenschap toevoegen.
  2. 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. 3
    Ga terug naar Voor- & achterkantvelden in de visuele editor.
  4. 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. 5
    Waar Apple Wallet en Google Wallet verschillen in labelafbreking, kunt u optioneel per veld een Android-overschrijving instellen.
Gekoppelde variabelechip in de veldinspector
Gekoppelde variabelechip in de veldinspector

Belangrijk: Houd Eigenschapssleutels in lowercase camelCase (holderName, validUntil). Die exacte sleutels worden de API-eigenschapsnamen binnen het structured JSON-object attributes bij het uitgeven van passen via /api/v1/passes of bij het toewijzen van CSV-kolommen tijdens batchimports. Daarnaast moet elke changeMessage op 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:

EigenschapTypeToegestane waarden / formaatPlatformgedrag & regels
keystringUnieke identificatie per pas (bijv. balance_fld)Gebruikt door iOS en Android om veldwaarden te vergelijken tijdens pushupdates
labelstringStatisch 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
changeMessagestringTekst met %@ (bijv. "Niveau verhoogd naar %@")Activeert een native iOS-pushmelding op het toegangsscherm wanneer value wijzigt; %@ wordt vervangen door de nieuwe opgemaakte waarde
textAlignmentPKTextAlignmentPKTextAlignmentLeft, PKTextAlignmentCenter, PKTextAlignmentRight, PKTextAlignmentNaturalBepaalt de horizontale uitlijning in Apple Wallet-veldkolommen op de voorkant
dateStylePKDateStylePKDateStyleNone, PKDateStyleShort, PKDateStyleMedium, PKDateStyleLong, PKDateStyleFullFormatteert ISO 8601-datumstrings volgens de taalinstelling van het apparaat
timeStylePKDateStylePKDateStyleNone, PKDateStyleShort, PKDateStyleMedium, PKDateStyleLong, PKDateStyleFullFormatteert tijdelementen in de lokale tijdzone van de pashouder
numberStylePKNumberStylePKNumberStyleDecimal, PKNumberStylePercent, PKNumberStyleScientific, PKNumberStyleSpellOutFormatteert numerieke veldwaarden met lokale duizend- en decimaalscheidingstekens
dataDetectorTypesPKDataDetectorType[]PKDataDetectorTypePhoneNumber, PKDataDetectorTypeLink, PKDataDetectorTypeAddress, PKDataDetectorTypeCalendarEvent, PKDataDetectorTypeNoneSchakelt interactieve tikacties in (bellen, URL openen, Kaarten openen, agenda-afspraak toevoegen) op achterkantvelden
currencyCodestringISO 4217 3-lettercode (EUR, USD, GBP, CHF)Formatteert numerieke waarden als gelokaliseerde valutabedragen in Apple & Google Wallet
attributedValuestringHTML-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 zoals attributes.tier = "VIP" of attributes.city = "Berlin").
  • Realtime doelgroepsegmentatie in PassProjectSegment en 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

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)

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

Klaar om uw eerste kaartprogramma te lanceren?

Maak uw workspace aan, configureer uw sjabloon en test een echte kaart in Apple Wallet en Google Wallet voordat u opschaalt.