Overzicht
Een Passjabloon (Template-model) bepaalt de structurele geometrie, visuele huisstijl, veldzones, barcodesymbologie en locatiegebaseerde relevantieregels die worden gedeeld door alle passen die onder een programma worden uitgegeven. Passinstance compileert één canonieke sjabloonconfiguratie naar zowel native Apple Wallet (.pkpass)-archieven als Google Wallet (Class / Object)-clouddefinities.
Open een sjabloon in het Dashboard en kies Sjabloon bewerken om het ontwerp en de wallet-regels naast elkaar te configureren met een live voorvertoning voor Apple Wallet en Google Wallet, of beheer sjablonen programmatisch via /api/v1/templates.

Systeemarchitectuur: sjabloonserialisatiepipeline
1. Identiteit, pastypen & veldlay-outzones
Bij het aanmaken van een sjabloon kiest u het onderliggende pass type / PassKind (storeCard, coupon, eventTicket, boardingPass, membership, studentId, generic, posterGeneric of businessCard), optioneel gecombineerd met theme preference (posterGeneric, posterEventTicket, bannerEventTicket, semanticBoardingPass, DARK) en transit type (PKTransitTypeAir, PKTransitTypeBoat, PKTransitTypeBus, PKTransitTypeGeneric, PKTransitTypeTrain) voor instapkaarten. Elk pastype bepaalt hoe het mobiele besturingssysteem de paskop, hero-afbeelding en veldregels weergeeft.
De 7 canonieke veldposities (field placement type)
Het Field-model en request payload plaatsen gegevenselementen in afzonderlijke lay-outposities (HEADER, PRIMARY, SECONDARY, AUXILIARY, BACK, ADDITIONALINFO, FOOTER):
Veldpositie (request payload / field placement type) | Apple Wallet-weergave | Google Wallet-toewijzing | Typische inhoud |
|---|---|---|---|
headerFields (HEADER) | Rechterbovenhoek naast logo (max. 1–3 compacte velden) | Toegewezen aan bovenste status-/koptekstmetadata | Puntensaldo, VIP-niveaulabel, poortnummer |
primaryFields (PRIMARY) | Opvallende hoofdbanner over of onder strip | Primaire hoofdwaarde / titel op de kaart | Naam pashouder, korting %, evenementtitel |
secondaryFields (SECONDARY) | Rij direct onder primaire velden (tot 4 kolommen) | Bovenste rij in textModulesData | Lidnummer, stoel/rij/vak, stempelteller |
auxiliaryFields (AUXILIARY) | Aanvullende metadatarij onder secundaire velden (of erboven bij eventTicket) | Secundaire rij in textModulesData | Vervaldatum, filiaal, organisator |
backFields (BACK) | Scrolbare achterkant van de pas (ondersteunt lange tekst & links) | Uitvouwbare Details-weergave (textModulesData & linksModuleData) | Algemene voorwaarden, supportnummer, website-URL's |
additionalInfoFields (ADDITIONALINFO) | iOS 18+ begeleidende details & locatieblokken | Aanvullende detailmodules | Evenement-FAQ, toegangsinstructies, aanvullende voorwaarden |
footerFields (FOOTER) | Onderste zone direct naast de barcode | Voettekstlabel bij de barcode | Beveiligingscode of instructies voor handmatige invoer |
2. Kleuren & platformregels voor serialisatie
Het Color-model bewaart vier semantische kleureigenschappen per sjabloon: backgroundColor, foregroundColor (tekstkleur van veldwaarden), labelColor (tekstkleur van veldlabels) en stripColor (kleurtint voor tekstoverlay op stripafbeeldingen).
-
Apple Wallet (
rgb(r, g, b)): Depass.json-parser van Apple Wallet vereist strikt CSS RGB-tripletstrings zonder alfakanaal—bijvoorbeeldrgb(24, 24, 27). Hexstrings (#18181B) ofrgba()-waarden worden automatisch genormaliseerd door de serializer van Passinstance, zodat ongeldige kleursyntaxis nooit in.pkpass-bundels terechtkomt. -
Google Wallet (
#RRGGBB): Google Walletwalletobjects-klassen vereisen 6-cijferige hexadecimale kleurstrings (#18181B). Passinstance vertaalt uw sjabloonkleurtokens transparant voor beide platformen. -
WCAG-contrastcontrole: De visuele editor berekent in realtime de luminantiecontrastverhouding tussen
backgroundColorenforegroundColor/labelColoren waarschuwt zodra typografie onder WCAG AA-leesbaarheidsdrempels zakt.
Belangrijk: Apple Wallet vereist strikt kleuren in
rgb(r, g, b)-formaat en weigert hexcodes of alfakanalen inpass.json. Bij aanroepen via de Passinstance REST API kunt u zowelrgb(r, g, b)als#RRGGBBaanleveren—de backend normaliseert en serialiseert automatisch het exacte vereiste formaat per platform.
3. De 13 visuele assetposities & retinavarianten
Passinstance beheert 13 afzonderlijke afbeeldingsposities op het Template-model. Wanneer u een bron-PNG met hoge resolutie uploadt, schaalt de assetpipeline automatisch @1x-, @2x- en @3x-retinavarianten voor Apple Wallet en host zij de openbare CDN-URL's die Google Wallet vereist:
| Assetpositiesleutel | Doelplatform | @1x-afmetingen | @2x-afmetingen | @3x-afmetingen | Doel & plaatsing in lay-out |
|---|---|---|---|---|---|
icon | Apple Wallet | 29 x 29 px | 58 x 58 px | 87 x 87 px | Verplicht pictogram voor toegangsschermmeldingen en e-mailbijlagen |
logo | Apple Wallet | 160 x 50 px | 320 x 100 px | 480 x 150 px | Merklogo linksboven naast logoText en header-velden |
primaryLogo | Geünificeerd / Terugval | 160 x 50 px | 320 x 100 px | 480 x 150 px | Canoniek merklogo dat over wallet-doelen wordt overgenomen |
googlePayLogo | Google Wallet | 660 x 660 px (min) | — | — | Circulair uitgesneden programmalogo in de Google Wallet-kop (1:1) |
strip | Apple (storeCard, coupon, eventTicket) | 375 x 123 px (eventTicket: 375 x 98 px) | 750 x 246 px | 1125 x 369 px | Randloze horizontale herobanner achter of boven primaire velden |
background | Apple (eventTicket, generic) | 180 x 220 px | 360 x 440 px | 540 x 660 px | Vervaagde achtergrondtextuur over de volledige pas |
thumbnail | Apple (generic, membership, eventTicket) | 90 x 90 px | 180 x 180 px | 270 x 270 px | Vierkante portretfoto of productbadge aan de rechterzijde |
footer | Apple (boardingPass, eventTicket) | 286 x 15 px | 572 x 30 px | 858 x 45 px | Smalle banner direct boven de barcode |
artwork | Apple WWDC25 Poster Ticket | 375 x 480 px | 750 x 960 px | 1125 x 1440 px | Opvallend posterontwerp voor iOS Event Tickets |
venueMap | Apple WWDC25 Event Guide | 375 x 375 px | 750 x 750 px | 1125 x 1125 px | Downloadbare plattegrond/zaalindeling binnen de iOS Event Guide |
secondaryLogo | Geünificeerde co-branding | 160 x 50 px | 320 x 100 px | 480 x 150 px | Secundair sponsor- of partnerlogo |
androidBackground | Google Wallet | 1032 x 336 px | — | — | Specifieke heroImage-banneroverschrijving voor Google Wallet (3.07:1) |
androidLogo | Google Wallet | 660 x 660 px | — | — | Expliciete logo-overschrijving voor Google Wallet indien afwijkend van googlePayLogo |
4. Ondersteunde barcodeformaten & validatieregels
Het Barcode-model en request payload coördineren barcode format (Apple Wallet-formaten inclusief geometrische PKBarcodeFormatSquare / PKBarcodeFormatRectangle en PKBarcodeFormatNone) en canonieke BarcodeType-waarden (QR_CODE, PDF_417, AZTEC, CODE_128, EAN_13, CODE_39, CODABAR, ITF), naast altText (of barcodeAlternativeText), messageEncoding (ISO_8859_1, UTF_8, ISO_8859_15, WINDOWS_1252, SHIFT_JIS), appleFallbackType en addSecurityAnimation (dynamische antischreenshot-glans):
| barcode format-waarde | Canoniek type | Native Apple Wallet | Native Google Wallet | Typische branchetoepassing |
|---|---|---|---|---|
PKBarcodeFormatQR (PKBarcodeFormatSquare) | QR_CODE | Ja (PKBarcodeFormatQR) | Ja (QR_CODE) | Detailloyaliteit, evenement-check-in, camerascanners |
PKBarcodeFormatPDF417 (PKBarcodeFormatRectangle) | PDF_417 | Ja (PKBarcodeFormatPDF417) | Ja (PDF_417) | Instapkaarten, ov-tickets, identiteitsbewijzen |
PKBarcodeFormatAztec | AZTEC | Ja (PKBarcodeFormatAztec) | Ja (AZTEC) | Treintickets, evenementpassen met hoge datadichtheid |
PKBarcodeFormatCode128 | CODE_128 | Ja (PKBarcodeFormatCode128) | Ja (CODE_128) | Supermarkt-laser-POS-scanners, ledenpassen |
PKBarcodeFormatCode39 | CODE_39 | Terugval / gerenderd | Ja (CODE_39) | Automotive, industrie en badgelezers |
PKBarcodeFormatCodabar | CODABAR | Terugval / gerenderd | Ja (CODABAR) | Bibliotheken, laboratoria en logistieke pakketten |
PKBarcodeFormatEAN13 | EAN_13 | Terugval / gerenderd | Ja (EAN_13) | Winkelcoupons en UPC/EAN-kassascanners |
PKBarcodeFormatI2of5 | ITF (accepteert 14-cijferige ITF_14 op Google) | Terugval / gerenderd | Ja (ITF_14 bij 14 cijfers) | Verpakkingen, groothandel en numerieke tickets |
PKBarcodeFormatNone | NONE | Geen barcode weergegeven | Geen barcode weergegeven | Exclusief NFC-gebaseerde passen (nfcNoBarcode: true) |
5. Geofencing, iBeacons, identificaties & datumrelevantie
Passen verschijnen automatisch op het toegangsscherm van de klant wanneer fysieke of tijdgebonden relevantietriggers overeenkomen:
-
GPS-locaties (
Location-model): Maximaal 10 coördinaten per sjabloon (latitude,longitude, optioneelaltitude,maxDistancein meters enrelevantTextvoor op het toegangsscherm). -
Bluetooth Low Energy Beacons (
Beacon-model): Maximaal 10 Apple iBeacons (proximityUUID, 16-bitsmajor- enminor-identificaties enrelevantText) voor nauwkeurige binnenhuisdetectie bij winkelingangen of tourniquets. -
Tijdgebonden relevantie (
RelevantDate): ISO 8601-tijdstempel (relevantDate) enexpirationDatedie evenementtickets of tijdelijke vouchers automatisch tonen vlak voor het geplande tijdstip. -
Aangepaste identificatie- & bundelinstellingen: Configureer
customIdentifiersEnabled,externalIdentifierPattern,customIdentifierValidationPattern,bundleOnDownload,bundleEnabledenmaxBundleSize(tot10passen per bundel).
6. Programmatische sjabloon-API-referentie (request payload)
Workspace-sjablonen opvragen
/api/v1/templates?page=1&limit=20&rowKind=PRODUCTION
Een nieuw sjabloon maken (request payload)
POST /api/v1/templates Headers: X-API-Key: <API_KEY> | Content-Type: application/json
{
"name": "Artisan Coffee Club - Gold",
"kind": "storeCard",
"status": "DRAFT",
"organizationName": "Artisan Roasters GmbH",
"description": "Artisan Coffee Loyalty Card",
"colors": {
"backgroundColor": "rgb(20, 35, 28)",
"foregroundColor": "rgb(255, 255, 255)",
"labelColor": "rgb(167, 243, 208)",
"stripColor": "rgb(255, 255, 255)"
},
"barcode": {
"format": "PKBarcodeFormatQR",
"messageEncoding": "UTF_8",
"altText": "{serialNumber}",
"addSecurityAnimation": true
},
"locations": [
{
"latitude": 52.520008,
"longitude": 13.404954,
"maxDistance": 150,
"relevantText": "Welcome back to Artisan Roasters! Tap to scan your card."
}
]
}
HTTP-respons (201 Created)
{
"success": true,
"data": {
"id": "tmpl_01hxyz987654321",
"groupId": "grp_01hxyz987654321",
"versionNumber": 1,
"rowKind": "DRAFT",
"status": "DRAFT",
"name": "Artisan Coffee Club - Gold",
"kind": "storeCard",
"colors": {
"backgroundColor": "rgb(20, 35, 28)",
"foregroundColor": "rgb(255, 255, 255)",
"labelColor": "rgb(167, 243, 208)",
"stripColor": "rgb(255, 255, 255)"
},
"createdAt": "2026-11-15T10:15:00.000Z"
},
"statusCode": 201
}
Ga verder naar Dynamische velden & personalisatie om aangepaste eigenschappen aan uw sjabloonlay-out te koppelen, of bekijk Pasmechanieken & functies.
