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

Sjabloonontwerp & configuratie

Gebruik de Visuele Editor voor kaarttypen, merkkleuren met WCAG-contrastcontrole, logo's, banners en barcodes.

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

Merkkleuren & WCAG-contrast (Ingezoomd)

Stel label-, waarde- en achtergrondkleuren in met één-klik contrastfix, kleurwissel, ingetrokken-kleur en wallet-aanpassing.

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.

Merkkleuren en contrastcontrole in de editor
Merkkleuren en contrastcontrole in de editor

Systeemarchitectuur: sjabloonserialisatiepipeline

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
SJABLOONONTWERP- & SERIALISATIEPIPELINE
FASE 01 VISUELE EDITOR / REST API (/api/v1/templates)
6 Veldzones
(KopAchter)
13 Assetposities
(@1x, @2x, @3x)
Kleurschema
(RGB / Hex)
11 Barcode &
Geofencing
FASE 02 SJABLOONVALIDATIE- & COMPILERENGINE
Dwingt pass type-geometrie af (storeCard, eventTicket, enz.)
Converteert kleurtokensrgb(r, g, b) voor Apple & #RRGGBB voor Google
Genereert retina-assetvarianten (@1x, @2x, @3x) in cloud object storage
Controleert WCAG 2.1 AA-contrastverhoudingen & barcodecodering (iso-8859-1/utf-8)
FASE 03A APPLE WALLET (.pkpass-bundel)
pass.json-dictionaryserialisatie
icon.png, logo@2x.png, strip.png
locations[], beacons[], nfc{}
FASE 03B GOOGLE WALLET (Class-resource)
LoyaltyClass / EventTicketClass
hexBackgroundColor & heroImage
callbackOptions & Smart Tap-cfg

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-weergaveGoogle Wallet-toewijzingTypische inhoud
headerFields (HEADER)Rechterbovenhoek naast logo (max. 1–3 compacte velden)Toegewezen aan bovenste status-/koptekstmetadataPuntensaldo, VIP-niveaulabel, poortnummer
primaryFields (PRIMARY)Opvallende hoofdbanner over of onder stripPrimaire hoofdwaarde / titel op de kaartNaam pashouder, korting %, evenementtitel
secondaryFields (SECONDARY)Rij direct onder primaire velden (tot 4 kolommen)Bovenste rij in textModulesDataLidnummer, stoel/rij/vak, stempelteller
auxiliaryFields (AUXILIARY)Aanvullende metadatarij onder secundaire velden (of erboven bij eventTicket)Secundaire rij in textModulesDataVervaldatum, 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 & locatieblokkenAanvullende detailmodulesEvenement-FAQ, toegangsinstructies, aanvullende voorwaarden
footerFields (FOOTER)Onderste zone direct naast de barcodeVoettekstlabel bij de barcodeBeveiligingscode 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)): De pass.json-parser van Apple Wallet vereist strikt CSS RGB-tripletstrings zonder alfakanaal—bijvoorbeeld rgb(24, 24, 27). Hexstrings (#18181B) of rgba()-waarden worden automatisch genormaliseerd door de serializer van Passinstance, zodat ongeldige kleursyntaxis nooit in .pkpass-bundels terechtkomt.
  • Google Wallet (#RRGGBB): Google Wallet walletobjects-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 backgroundColor en foregroundColor / labelColor en 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 in pass.json. Bij aanroepen via de Passinstance REST API kunt u zowel rgb(r, g, b) als #RRGGBB aanleveren—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:

AssetpositiesleutelDoelplatform@1x-afmetingen@2x-afmetingen@3x-afmetingenDoel & plaatsing in lay-out
iconApple Wallet29 x 29 px58 x 58 px87 x 87 pxVerplicht pictogram voor toegangsschermmeldingen en e-mailbijlagen
logoApple Wallet160 x 50 px320 x 100 px480 x 150 pxMerklogo linksboven naast logoText en header-velden
primaryLogoGeünificeerd / Terugval160 x 50 px320 x 100 px480 x 150 pxCanoniek merklogo dat over wallet-doelen wordt overgenomen
googlePayLogoGoogle Wallet660 x 660 px (min)——Circulair uitgesneden programmalogo in de Google Wallet-kop (1:1)
stripApple (storeCard, coupon, eventTicket)375 x 123 px (eventTicket: 375 x 98 px)750 x 246 px1125 x 369 pxRandloze horizontale herobanner achter of boven primaire velden
backgroundApple (eventTicket, generic)180 x 220 px360 x 440 px540 x 660 pxVervaagde achtergrondtextuur over de volledige pas
thumbnailApple (generic, membership, eventTicket)90 x 90 px180 x 180 px270 x 270 pxVierkante portretfoto of productbadge aan de rechterzijde
footerApple (boardingPass, eventTicket)286 x 15 px572 x 30 px858 x 45 pxSmalle banner direct boven de barcode
artworkApple WWDC25 Poster Ticket375 x 480 px750 x 960 px1125 x 1440 pxOpvallend posterontwerp voor iOS Event Tickets
venueMapApple WWDC25 Event Guide375 x 375 px750 x 750 px1125 x 1125 pxDownloadbare plattegrond/zaalindeling binnen de iOS Event Guide
secondaryLogoGeünificeerde co-branding160 x 50 px320 x 100 px480 x 150 pxSecundair sponsor- of partnerlogo
androidBackgroundGoogle Wallet1032 x 336 px——Specifieke heroImage-banneroverschrijving voor Google Wallet (3.07:1)
androidLogoGoogle Wallet660 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-waardeCanoniek typeNative Apple WalletNative Google WalletTypische branchetoepassing
PKBarcodeFormatQR (PKBarcodeFormatSquare)QR_CODEJa (PKBarcodeFormatQR)Ja (QR_CODE)Detailloyaliteit, evenement-check-in, camerascanners
PKBarcodeFormatPDF417 (PKBarcodeFormatRectangle)PDF_417Ja (PKBarcodeFormatPDF417)Ja (PDF_417)Instapkaarten, ov-tickets, identiteitsbewijzen
PKBarcodeFormatAztecAZTECJa (PKBarcodeFormatAztec)Ja (AZTEC)Treintickets, evenementpassen met hoge datadichtheid
PKBarcodeFormatCode128CODE_128Ja (PKBarcodeFormatCode128)Ja (CODE_128)Supermarkt-laser-POS-scanners, ledenpassen
PKBarcodeFormatCode39CODE_39Terugval / gerenderdJa (CODE_39)Automotive, industrie en badgelezers
PKBarcodeFormatCodabarCODABARTerugval / gerenderdJa (CODABAR)Bibliotheken, laboratoria en logistieke pakketten
PKBarcodeFormatEAN13EAN_13Terugval / gerenderdJa (EAN_13)Winkelcoupons en UPC/EAN-kassascanners
PKBarcodeFormatI2of5ITF (accepteert 14-cijferige ITF_14 op Google)Terugval / gerenderdJa (ITF_14 bij 14 cijfers)Verpakkingen, groothandel en numerieke tickets
PKBarcodeFormatNoneNONEGeen barcode weergegevenGeen barcode weergegevenExclusief 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, optioneel altitude, maxDistance in meters en relevantText voor op het toegangsscherm).
  • Bluetooth Low Energy Beacons (Beacon-model): Maximaal 10 Apple iBeacons (proximityUUID, 16-bits major- en minor-identificaties en relevantText) voor nauwkeurige binnenhuisdetectie bij winkelingangen of tourniquets.
  • Tijdgebonden relevantie (RelevantDate): ISO 8601-tijdstempel (relevantDate) en expirationDate die evenementtickets of tijdelijke vouchers automatisch tonen vlak voor het geplande tijdstip.
  • Aangepaste identificatie- & bundelinstellingen: Configureer customIdentifiersEnabled, externalIdentifierPattern, customIdentifierValidationPattern, bundleOnDownload, bundleEnabled en maxBundleSize (tot 10 passen per bundel).

6. Programmatische sjabloon-API-referentie (request payload)

Workspace-sjablonen opvragen

GET /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

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)

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

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.