Skip to content
Hilfecenter-Anleitung · Pass-VorlagenOnboarding-Phase 2
7 Min. LesezeitGeprüft 2026-11-16

Vorlagen-Design & Konfiguration

Nutzen Sie den visuellen Editor für Kartentypen, Markenfarben mit WCAG-Kontrastprüfung, Logos, Banner und Barcodes.

In dieser Anleitung

Prüfen Sie passende Dashboard-Bereiche, Steuerelemente und Zoom-Hinweise zu diesem Thema.

Vergrößerter UI-Fokus1 / 2
Wichtige UI-Elemente

Markenfarben & WCAG-Kontrast (Zoom)

Label-, Wert- und Hintergrundfarben samt Ein-Klick-Kontrastkorrektur, Farbtausch, ungültigen Pass-Farben und Wallet-Anpassung.

Ü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.

Markenfarben und Kontrastprüfung im Editor
Markenfarben und Kontrastprüfung im Editor

Systemarchitektur: Vorlagen-Serialisierungs-Pipeline

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
VORLAGENDESIGN & SERIALISIERUNGS-PIPELINE
STUFE 01 VISUELLER EDITOR / REST-API (/api/v1/templates)
6+ Feldzonen
(HeaderBack)
13 Bild-Slots
(@1x, @2x, @3x)
Farbschema
(RGB / Hex)
11 Barcodes &
Geofencing
STUFE 02 VORLAGEN-VALIDIERUNGS- & COMPILER-ENGINE
Prüft Geometrie-Regeln von pass type (storeCard, eventTicket usw.)
Konvertiert Farbenrgb(r, g, b) für Apple & #RRGGBB für Google
Erzeugt Retina-Asset-Varianten (@1x, @2x, @3x) im cloud object storage
Prüft WCAG-2.1-AA-Kontrast & Barcode-Kodierung (iso-8859-1/utf-8)
STUFE 03A APPLE WALLET (.pkpass-Bundle)
Serialisierung des pass.json-Dicts
icon.png, logo@2x.png, strip.png
locations[], beacons[], nfc{}
STUFE 03B GOOGLE WALLET (Class-Ressource)
LoyaltyClass / EventTicketClass
hexBackgroundColor & heroImage
callbackOptions & Smart Tap Config

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 WalletZuordnung in Google WalletTypischer Inhalt
headerFields (HEADER)Oben rechts neben dem logo (max. 1–3 kompakte Felder)Obere Status-/Header-MetadatenPunktestand, VIP-Stufen-Badge, Gate-Nummer
primaryFields (PRIMARY)Prominentes Hauptfeld auf bzw. unter dem strip-BannerHauptmetrik / KartentitelName der Karteninhaberin/des -inhabers, Rabatt in %, Event-Titel
secondaryFields (SECONDARY)Zeile direkt unter den Primary Fields (bis zu 4 Spalten)Obere textModulesData-ZeileMitgliedsnummer, Bereich/Reihe/Platz, Stempelzähler
auxiliaryFields (AUXILIARY)Zusätzliche Metadatenzeile unter Secondary (oder darüber bei eventTicket)Sekundäre textModulesData-ZeileAblaufdatum, 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 18Zusätzliche Detail-ModuleEvent-FAQ, Einlasshinweise, ergänzende Angaben
footerFields (FOOTER)Unterer Bereich direkt über bzw. neben dem BarcodeBarcode-FußzeilenbeschriftungSicherheitscode 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)): Der pass.json-Parser von Apple Wallet verlangt zwingend CSS-RGB-Tripel ohne Alpha-Kanal — zum Beispiel rgb(24, 24, 27). Hex-Strings (#18181B) oder rgba()-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 backgroundColor und foregroundColor / labelColor in 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 in pass.json ab. Über die Passinstance REST-API können Sie wahlweise rgb(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üsselZielplattform@1x-Abmessungen@2x-Abmessungen@3x-AbmessungenZweck & Layout-Platzierung
iconApple Wallet29 x 29 px58 x 58 px87 x 87 pxPflicht-Icon für Sperrbildschirm-Hinweise & E-Mail-Anhänge
logoApple Wallet160 x 50 px320 x 100 px480 x 150 pxMarkenlogo oben links neben logoText und header-Feldern
primaryLogoEinheitlich / Fallback160 x 50 px320 x 100 px480 x 150 pxKanonisches Markenlogo als Fallback über Wallet-Ziele hinweg
googlePayLogoGoogle Wallet660 x 660 px (min.)——Kreisförmig maskiertes Programm-Logo im Google-Wallet-Header (1:1-Format)
stripApple (storeCard, coupon, eventTicket)375 x 123 px (eventTicket: 375 x 98 px)750 x 246 px1125 x 369 pxRandloses horizontales Hero-Banner hinter bzw. über den Primary Fields
backgroundApple (eventTicket, generic)180 x 220 px360 x 440 px540 x 660 pxWeichgezeichnetes Vollbild-Hintergrundmotiv
thumbnailApple (generic, membership, eventTicket)90 x 90 px180 x 180 px270 x 270 pxQuadratisches Porträtfoto oder Produkt-Badge auf der rechten Seite
footerApple (boardingPass, eventTicket)286 x 15 px572 x 30 px858 x 45 pxSchmales Banner unmittelbar über dem Barcode
artworkApple WWDC25 Poster-Ticket375 x 480 px750 x 960 px1125 x 1440 pxGroßflächige Poster-Event-Grafik für iOS Event Tickets
venueMapApple WWDC25 Event Guide375 x 375 px750 x 750 px1125 x 1125 pxHerunterladbarer Sitz-/Lageplan im iOS Event Guide
secondaryLogoEinheitliches Co-Branding160 x 50 px320 x 100 px480 x 150 pxLogo für Sponsoren oder Partnerunternehmen
androidBackgroundGoogle Wallet1032 x 336 px——Dedizierte Überschreibung für das Google-Wallet-heroImage (3.07:1-Format)
androidLogoGoogle Wallet660 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-WertKanonischer TypNativ in Apple WalletNativ in Google WalletTypischer Anwendungsfall
PKBarcodeFormatQR (PKBarcodeFormatSquare)QR_CODEJa (PKBarcodeFormatQR)Ja (QR_CODE)Handels-Treueprogramme, Event-Check-in, Kamera-Scanner
PKBarcodeFormatPDF417 (PKBarcodeFormatRectangle)PDF_417Ja (PKBarcodeFormatPDF417)Ja (PDF_417)Airline-Bordkarten, ÖPNV-Tickets, Ausweise
PKBarcodeFormatAztecAZTECJa (PKBarcodeFormatAztec)Ja (AZTEC)Bahntickets, hochdichte Event-Pässe
PKBarcodeFormatCode128CODE_128Ja (PKBarcodeFormatCode128)Ja (CODE_128)Laser-Kassenscanner im Supermarkt, Mitgliedskarten
PKBarcodeFormatCode39CODE_39Fallback / GerendertJa (CODE_39)Automotive-, Industrie- und Werksausweisleser
PKBarcodeFormatCodabarCODABARFallback / GerendertJa (CODABAR)Bibliotheken, Labore und Logistikpakete
PKBarcodeFormatEAN13EAN_13Fallback / GerendertJa (EAN_13)Einzelhandels-Coupons und POS-UPC/EAN-Kassen
PKBarcodeFormatI2of5ITF (akzeptiert 14-stelliges ITF_14 bei Google)Fallback / GerendertJa (ITF_14 bei 14 Ziffern)Verpackung, Großhandel und fortlaufend nummerierte Tickets
PKBarcodeFormatNoneNONEKein Barcode angezeigtKein Barcode angezeigtReine 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, optional altitude, maxDistance in Metern sowie relevantText für den Sperrbildschirm).
  • Bluetooth-Low-Energy-Beacons (Beacon-Modell): Bis zu 10 Apple iBeacons (proximityUUID, 16-Bit-major- und minor-Werte sowie relevantText) zur Indoor-Mikrolokalisierung an Eingängen oder Drehkreuzen.
  • Zeitliche Relevanz (RelevantDate): ISO-8601-Zeitstempel (relevantDate) und expirationDate, die Event-Tickets oder befristete Gutscheine pünktlich zum Termin auf dem Sperrbildschirm hervorheben.
  • Benutzerdefinierte Identifikatoren & Bündelung: Konfigurieren Sie customIdentifiersEnabled, externalIdentifierPattern, customIdentifierValidationPattern, bundleOnDownload, bundleEnabled und maxBundleSize (bis zu 10 Pässe pro Bündel).

6. Programmatische Vorlagen-API-Referenz (request payload)

Workspace-Vorlagen auflisten

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

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)

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
}

Fahren Sie fort mit Dynamische Felder & Personalisierung, um benutzerdefinierte Attribute mit Ihrem Vorlagenlayout zu verknüpfen, oder informieren Sie sich über Pass-Mechaniken & Funktionen.

Bereit für Ihr erstes Wallet-Kartenprogramm?

Erstellen Sie Ihren Workspace, konfigurieren Sie Ihre Vorlage und testen Sie eine echte Karte in Apple Wallet und Google Wallet, bevor Sie skalieren.