Überblick
Eine Pass-Vorlage (Template-Modell) definiert die strukturelle Geometrie, das visuelle Markenbild, die Feldlayout-Zonen, die Barcode-Symbologie sowie standortbasierte Relevanzregeln, die sich alle unter einem Programm ausgegebenen Pässe teilen. Passinstance kompiliert eine einzige kanonische Vorlagenkonfiguration sowohl in native Apple-Wallet-Archive (.pkpass) als auch in Google-Wallet-Cloud-Definitionen (Class / Object).
Öffnen Sie eine beliebige Vorlage im Dashboard und wechseln Sie in Vorlage bearbeiten, um Design- und Wallet-Regeln Seite an Seite mit einer Live-Vorschau für Apple Wallet und Google Wallet zu konfigurieren, oder verwalten Sie Vorlagen programmatisch über /api/v1/templates.

Systemarchitektur: Vorlagen-Serialisierungs-Pipeline
1. Identität, Pass-Typen & Feldlayout-Zonen
Wählen Sie beim Erstellen einer Vorlage das zugrunde liegende pass type / PassKind (storeCard, coupon, eventTicket, boardingPass, membership, studentId, generic, posterGeneric oder businessCard), optional kombiniert mit theme preference (posterGeneric, posterEventTicket, bannerEventTicket, semanticBoardingPass, DARK) sowie transit type (PKTransitTypeAir, PKTransitTypeBoat, PKTransitTypeBus, PKTransitTypeGeneric, PKTransitTypeTrain) für Bordkarten. Jeder Pass-Typ steuert, wie das mobile Betriebssystem Kartenkopf, Titelgrafik und Feldzeilen darstellt.
Die 7 kanonischen Feldpositionen (field placement type)
Das Modell Field und request payload platzieren Datenelemente in definierten Layout-Zonen (HEADER, PRIMARY, SECONDARY, AUXILIARY, BACK, ADDITIONALINFO, FOOTER):
Feldposition (request payload / field placement type) | Darstellung in Apple Wallet | Zuordnung in Google Wallet | Typischer Inhalt |
|---|---|---|---|
headerFields (HEADER) | Oben rechts neben dem logo (max. 1–3 kompakte Felder) | Obere Status-/Header-Metadaten | Punktestand, VIP-Stufen-Badge, Gate-Nummer |
primaryFields (PRIMARY) | Prominentes Hauptfeld auf bzw. unter dem strip-Banner | Hauptmetrik / Kartentitel | Name der Karteninhaberin/des -inhabers, Rabatt in %, Event-Titel |
secondaryFields (SECONDARY) | Zeile direkt unter den Primary Fields (bis zu 4 Spalten) | Obere textModulesData-Zeile | Mitgliedsnummer, Bereich/Reihe/Platz, Stempelzähler |
auxiliaryFields (AUXILIARY) | Zusätzliche Metadatenzeile unter Secondary (oder darüber bei eventTicket) | Sekundäre textModulesData-Zeile | Ablaufdatum, Filiale, Veranstalter |
backFields (BACK) | Scrollbare Rückseite des Passes (für längere Texte & Links) | Erweiterte Details-Ansicht (textModulesData & linksModuleData) | AGB, Support-Rufnummer, Website-URLs |
additionalInfoFields (ADDITIONALINFO) | Begleitdetails & Veranstaltungsort-Blöcke ab iOS 18 | Zusätzliche Detail-Module | Event-FAQ, Einlasshinweise, ergänzende Angaben |
footerFields (FOOTER) | Unterer Bereich direkt über bzw. neben dem Barcode | Barcode-Fußzeilenbeschriftung | Sicherheitscode oder Hinweis zur manuellen Eingabe |
2. Farben & plattformspezifische Serialisierungsregeln
Das Color-Modell speichert vier semantische Farbeigenschaften je Vorlage: backgroundColor, foregroundColor (Farbe der Feldwerte), labelColor (Farbe der Feldbeschriftungen) und stripColor (Textfarbe über Strip-Grafiken).
-
Apple Wallet (
rgb(r, g, b)): Derpass.json-Parser von Apple Wallet verlangt zwingend CSS-RGB-Tripel ohne Alpha-Kanal — zum Beispielrgb(24, 24, 27). Hex-Strings (#18181B) oderrgba()-Werte werden vom Passinstance-Serializer automatisch normalisiert, sodass niemals ungültige Farbsyntax in.pkpass-Pakete gelangt. -
Google Wallet (
#RRGGBB): Google-Wallet-walletobjects-Klassen erfordern sechsstellige Hexadezimal-Farbwerte (#18181B). Passinstance übersetzt Ihre Farbtokens transparent für beide Plattformen. -
WCAG-Kontrastprüfung: Der visuelle Editor berechnet die Helligkeitskontraste zwischen
backgroundColorundforegroundColor/labelColorin Echtzeit und warnt, wenn Schriften unter die Lesbarkeitsgrenzwerte nach WCAG AA fallen.
Wichtig: Apple Wallet akzeptiert Farben ausschließlich im Format
rgb(r, g, b)und lehnt Hex-Codes oder Alpha-Kanäle inpass.jsonab. Über die Passinstance REST-API können Sie wahlweisergb(r, g, b)oder#RRGGBBübergeben — das Backend normalisiert und serialisiert automatisch das exakt erforderliche Format jeder Plattform.
3. Die 13 visuellen Asset-Slots & Retina-Varianten
Passinstance verwaltet 13 spezialisierte Bild-Slots auf dem Template-Modell. Beim Upload eines hochauflösenden Quell-PNGs skaliert und verpackt die Asset-Pipeline automatisch @1x-, @2x- und @3x-Retina-Varianten für Apple Wallet und stellt zugleich die für Google Wallet erforderlichen öffentlichen CDN-URLs bereit:
| Asset-Slot-Schlüssel | Zielplattform | @1x-Abmessungen | @2x-Abmessungen | @3x-Abmessungen | Zweck & Layout-Platzierung |
|---|---|---|---|---|---|
icon | Apple Wallet | 29 x 29 px | 58 x 58 px | 87 x 87 px | Pflicht-Icon für Sperrbildschirm-Hinweise & E-Mail-Anhänge |
logo | Apple Wallet | 160 x 50 px | 320 x 100 px | 480 x 150 px | Markenlogo oben links neben logoText und header-Feldern |
primaryLogo | Einheitlich / Fallback | 160 x 50 px | 320 x 100 px | 480 x 150 px | Kanonisches Markenlogo als Fallback über Wallet-Ziele hinweg |
googlePayLogo | Google Wallet | 660 x 660 px (min.) | — | — | Kreisförmig maskiertes Programm-Logo im Google-Wallet-Header (1:1-Format) |
strip | Apple (storeCard, coupon, eventTicket) | 375 x 123 px (eventTicket: 375 x 98 px) | 750 x 246 px | 1125 x 369 px | Randloses horizontales Hero-Banner hinter bzw. über den Primary Fields |
background | Apple (eventTicket, generic) | 180 x 220 px | 360 x 440 px | 540 x 660 px | Weichgezeichnetes Vollbild-Hintergrundmotiv |
thumbnail | Apple (generic, membership, eventTicket) | 90 x 90 px | 180 x 180 px | 270 x 270 px | Quadratisches Porträtfoto oder Produkt-Badge auf der rechten Seite |
footer | Apple (boardingPass, eventTicket) | 286 x 15 px | 572 x 30 px | 858 x 45 px | Schmales Banner unmittelbar über dem Barcode |
artwork | Apple WWDC25 Poster-Ticket | 375 x 480 px | 750 x 960 px | 1125 x 1440 px | Großflächige Poster-Event-Grafik für iOS Event Tickets |
venueMap | Apple WWDC25 Event Guide | 375 x 375 px | 750 x 750 px | 1125 x 1125 px | Herunterladbarer Sitz-/Lageplan im iOS Event Guide |
secondaryLogo | Einheitliches Co-Branding | 160 x 50 px | 320 x 100 px | 480 x 150 px | Logo für Sponsoren oder Partnerunternehmen |
androidBackground | Google Wallet | 1032 x 336 px | — | — | Dedizierte Überschreibung für das Google-Wallet-heroImage (3.07:1-Format) |
androidLogo | Google Wallet | 660 x 660 px | — | — | Explizite Google-Wallet-Logo-Überschreibung abweichend von googlePayLogo |
4. Unterstützte Barcode-Formate & Validierungsregeln
Das Barcode-Modell und request payload koordinieren barcode format (Apple-Wallet-Formate inklusive der geometrischen Varianten PKBarcodeFormatSquare / PKBarcodeFormatRectangle und PKBarcodeFormatNone) sowie die kanonischen BarcodeType-Werte (QR_CODE, PDF_417, AZTEC, CODE_128, EAN_13, CODE_39, CODABAR, ITF), zusammen mit altText (bzw. barcodeAlternativeText), messageEncoding (ISO_8859_1, UTF_8, ISO_8859_15, WINDOWS_1252, SHIFT_JIS), appleFallbackType und addSecurityAnimation (dynamischer Anti-Screenshot-Schimmer):
| barcode format-Wert | Kanonischer Typ | Nativ in Apple Wallet | Nativ in Google Wallet | Typischer Anwendungsfall |
|---|---|---|---|---|
PKBarcodeFormatQR (PKBarcodeFormatSquare) | QR_CODE | Ja (PKBarcodeFormatQR) | Ja (QR_CODE) | Handels-Treueprogramme, Event-Check-in, Kamera-Scanner |
PKBarcodeFormatPDF417 (PKBarcodeFormatRectangle) | PDF_417 | Ja (PKBarcodeFormatPDF417) | Ja (PDF_417) | Airline-Bordkarten, ÖPNV-Tickets, Ausweise |
PKBarcodeFormatAztec | AZTEC | Ja (PKBarcodeFormatAztec) | Ja (AZTEC) | Bahntickets, hochdichte Event-Pässe |
PKBarcodeFormatCode128 | CODE_128 | Ja (PKBarcodeFormatCode128) | Ja (CODE_128) | Laser-Kassenscanner im Supermarkt, Mitgliedskarten |
PKBarcodeFormatCode39 | CODE_39 | Fallback / Gerendert | Ja (CODE_39) | Automotive-, Industrie- und Werksausweisleser |
PKBarcodeFormatCodabar | CODABAR | Fallback / Gerendert | Ja (CODABAR) | Bibliotheken, Labore und Logistikpakete |
PKBarcodeFormatEAN13 | EAN_13 | Fallback / Gerendert | Ja (EAN_13) | Einzelhandels-Coupons und POS-UPC/EAN-Kassen |
PKBarcodeFormatI2of5 | ITF (akzeptiert 14-stelliges ITF_14 bei Google) | Fallback / Gerendert | Ja (ITF_14 bei 14 Ziffern) | Verpackung, Großhandel und fortlaufend nummerierte Tickets |
PKBarcodeFormatNone | NONE | Kein Barcode angezeigt | Kein Barcode angezeigt | Reine NFC-Pässe (nfcNoBarcode: true) |
5. Geofencing, iBeacons, Identifikatoren & Datumsrelevanz
Pässe erscheinen automatisch auf dem Sperrbildschirm des Smartphones, wenn räumliche oder zeitliche Relevanzkriterien greifen:
-
GPS-Standorte (
Location-Modell): Bis zu 10 Koordinaten pro Vorlage (latitude,longitude, optionalaltitude,maxDistancein Metern sowierelevantTextfür den Sperrbildschirm). -
Bluetooth-Low-Energy-Beacons (
Beacon-Modell): Bis zu 10 Apple iBeacons (proximityUUID, 16-Bit-major- undminor-Werte sowierelevantText) zur Indoor-Mikrolokalisierung an Eingängen oder Drehkreuzen. -
Zeitliche Relevanz (
RelevantDate): ISO-8601-Zeitstempel (relevantDate) undexpirationDate, die Event-Tickets oder befristete Gutscheine pünktlich zum Termin auf dem Sperrbildschirm hervorheben. -
Benutzerdefinierte Identifikatoren & Bündelung: Konfigurieren Sie
customIdentifiersEnabled,externalIdentifierPattern,customIdentifierValidationPattern,bundleOnDownload,bundleEnabledundmaxBundleSize(bis zu10Pässe pro Bündel).
6. Programmatische Vorlagen-API-Referenz (request payload)
Workspace-Vorlagen auflisten
/api/v1/templates?page=1&limit=20&rowKind=PRODUCTION
Neue Vorlage erstellen (request payload)
POST /api/v1/templates Header: 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-Antwort (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
}
Fahren Sie fort mit Dynamische Felder & Personalisierung, um benutzerdefinierte Attribute mit Ihrem Vorlagenlayout zu verknüpfen, oder informieren Sie sich über Pass-Mechaniken & Funktionen.
