Skip to content
Hilfecenter-Anleitung · Pass-Vorlagen
5 Min. LesezeitGeprüft 2026-11-16

Aus Apple Pass Designer importieren

.passdesign-Ordner, Property-List-Dateien (.plist) und nicht signierte Pakete direkt in native Passinstance-Vorlagen importieren.

In dieser Anleitung

Überblick

Designerinnen, Designer und iOS-Entwicklungsteams, die digitale Pässe mit macOS-Entwicklungswerkzeugen — wie Apples offiziellem Pass Designer, Xcode oder Desktop-Pass-Editoren von Drittanbietern — prototypisieren, können ihre Entwürfe direkt in Passinstance importieren. Sie müssen Feldkoordinaten, Farbwerte und Barcode-Typen nicht manuell neu eingeben oder Bild-Assets einzeln hochladen.

Passinstance bietet automatisierten Import für:

  • Apple-Pass-Designer-Archive (.passdesign-Bundles).
  • Apple-Property-List-XML-Dokumente (.plist oder .xml).
  • Unsignierte oder signierte Apple-Wallet-Pakete (.pkpass-ZIP-Archive).
  • Rohe Apple-PassKit-Metadatendateien (pass.json).

Die Import-Engine extrahiert Bild-Assets (icon.png, logo.png, strip.png, thumbnail.png), parst das strukturelle Layout und normalisiert es in eine vollständig bearbeitbare Passinstance-Vorlage, die sowohl mit Apple Wallet als auch mit Google Wallet kompatibel ist.

Systemarchitektur: Apple-PassKit- & Plist-Import-Engine

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
APPLE-PASS-DESIGNER-IMPORT-ENGINE
STUFE 01 APPLE-PASS-DESIGNER-QUELLARTEFAKTE
.passdesign-Bundle (macOS Pass Designer Dokumentpaket)
.plist / .xml (Apple-Property-List-Format)
.pkpass / .zip (Signiertes oder unsigniertes Apple-Wallet-Bundle)
pass.json (Rohes Apple-PassKit-Spezifikationswörterbuch)
STUFE 02 IMPORT- & SICHERHEITS-PARSER
template-import-export.util.ts (parsePlistXmlToObject, parseXmlNodeTree)
Gehärteter XML-Parser: Keine Auflösung externer Entitäten (XXE-Schutz)
Tiefenbegrenzung: MAX_PLIST_DEPTH = 32 (verhindert Rekursionsüberlauf)
ZIP-Sicherheitslimits: MAX_ZIP_ENTRIES = 250, MAX_ZIP_ENTRY_BYTES = 1 MB
Unsignierter Modus: isUnsignedPackage: true (ohne Apple-Signaturpflicht)
STUFE 03 PASSKIT-ZU-PASSINSTANCE-SCHEMA-NORMALIZER
Apple-StilePassKind (storeCard, coupon, eventTicket usw.)
Plist-TypenJS-Typen (dictObject, arrayArray, realNumber)
Farben: Normalisiert Apple rgb(r, g, b) & wandelt in Google-Wallet-Hex um
Barcodes: Normalisiert PKBarcodeFormat* & weist watchOS-Fallback zu
Asset-Extraktion: Überträgt @1x, @2x, @3x-Retina-PNGs in S3-Speicher
STUFE 04 KANONISCHE PASSINSTANCE-VORLAGE (Template-Entität)
Interaktive Live-Vorschau im Apple-Wallet- & Google-Wallet-Simulator
Sofort bereit für Pass-Ausgabe, CSV-Stapelimport oder PassFlow-Registrierung

Unterstützte Dateiformate & Erweiterungen

Der Datei-Uploader im Template Creation Wizard akzeptiert die folgenden Dateiendungen gemäß dem regulären Ausdruck /\.(passdesign|plist|xml|pkpass|zip|json)$/i:

Format / EndungBeschreibungExtrahierte Inhalte
.passdesignApple-Pass-Designer-Bundle-Ordner oder komprimiertes Archiv.Vollständige Pass-Geometrie, visuelle Feldlayouts, Farben sowie alle Retina-PNG-Assets.
.plist / .xmlApple-Property-List-XML-Format.Feldstrukturen, Label-/Wertepaare, Transit-Typen, Barcodes und Relevanzregeln.
.pkpassStandardmäßiges Apple-Wallet-Pass-Archiv (signiert oder unsigniert).pass.json, Lokalisierungsordner (.lproj) und Bild-Assets. Digitale Signatur (signature) und Manifest (manifest.json) werden sicher ignoriert.
pass.jsonKanonisches Apple-PassKit-Wörterbuch.Standardmäßige Apple-PassKit-JSON-Struktur.

XML-Sicherheit & Entity-Schutz (parsePlistXmlToObject)

Beim Einlesen von Apple-.plist- oder .xml-Dokumenten verwendet Passinstance einen gehärteten internen XML-Parser (parsePlistXmlToObject in template-import-export.util.ts) mit strengen Sicherheitsinvarianten:

  1. 1
    XXE-Schutz (Keine Auflösung externer Entitäten): Der Parser ignoriert <!DOCTYPE>-Deklarationen, externe Entity-Definitionen (SYSTEM oder PUBLIC) sowie XML-Schema-Referenzen vollständig. Dadurch werden XML-External-Entity-Angriffe (XXE) und Server-Side Request Forgery (SSRF) ausgeschlossen.
  2. 2
    Rekursions- & Tiefenschutz: Die Rekursionstiefe ist auf MAX_PLIST_DEPTH = 32 begrenzt. Verschachtelte Wörterbücher oder Arrays, die diesen Schwellenwert überschreiten, werden mit einer Validierungsausnahme abgebrochen, um Stack-Overflow-Angriffe zu verhindern.
  3. 3
    Zip-Bomb-Prävention: Beim Entpacken von .passdesign- oder .pkpass-ZIP-Dateien begrenzt die Engine die Gesamtanzahl der Einträge auf MAX_ZIP_ENTRIES = 250 und die unkomprimierte Größe pro Datei auf MAX_ZIP_ENTRY_BYTES = 1 MB (1048576 Bytes).
  4. 4
    Schutz vor Prototype Pollution: Eigenschaftsschlüssel, die __proto__, constructor oder prototype entsprechen, werden beim Aufbau der Wörterbücher entfernt.

Referenz für die Apple-PassKit-Typzuordnung

Das Import-Dienstprogramm bildet Apple-Property-List-Typen und PassKit-Strukturen automatisch auf Passinstance-Modelle ab:

Apple-PassKit- / Plist-TypPassinstance-Modell-ÄquivalentNormalisierungsverhalten
<dict>JavaScript ObjectWird auf Feldgruppen, Farbobjekte oder Standort-Wörterbücher abgebildet.
<array>JavaScript ArrayWird auf Feld-Arrays (headerFields, primaryFields usw.) abgebildet.
<string>stringBereinigt Leerzeichen und dekodiert XML-Entitäten (&amp;, &lt;, &gt;).
<integer> / <real>numberWird in Gleitkomma- oder Ganzzahlen konvertiert.
<true/> / <false/>booleanWird in reguläre boolesche JavaScript-Werte konvertiert.
<date>ISO-8601 stringWird auf UTC-ISO-8601-Zeitstempel (YYYY-MM-DDTHH:MM:SSZ) normalisiert.
<data>Base64 stringWird per Base64 in binäre Asset-Puffer für Bilder dekodiert.

Normalisierung von Pass-Stil zu Pass-Art

Apple-Pass-StilPassinstance PassKindLayout- & Feldinvarianten
storeCardstoreCardVorderseitenlayout mit Strip-Bild; bis zu 4 Sekundär-/Zusatzfelder.
couponcouponVorderseitenlayout mit Strip-Bild; Zusatzfelder werden in Sekundärfelder umgeleitet.
eventTicketeventTicketUnterstützt Hintergrundtextur, Strip-Bild sowie iOS-18-Venue-Companion-Blöcke.
boardingPassboardingPassParst transitType (PKTransitTypeAir, PKTransitTypeTrain usw.) sowie primäre Abflug-/Ankunftsfelder.
genericgenericVielseitiges Standard-Kartenlayout mit optionalem Vorschaubild.

Import über das Dashboard (Schritt für Schritt)

  1. 1
    Navigieren Sie im Passinstance-Dashboard zu Vorlagen und klicken Sie auf + Neue Vorlage.
  2. 2
    In Schritt 1 (Details) des Template Creation Wizard:

- Klicken Sie auf Bestehenden Pass importieren oder ziehen Sie Ihre .passdesign-, .plist-, .pkpass- oder pass.json-Datei per Drag-and-drop in den Upload-Bereich.

  1. 3
    Der Assistent parst die Datei umgehend und extrahiert:

- Vorlagenname & Beschreibung: Vorbefüllt aus description oder organizationName. - Pass-Art: Automatisch erkannt anhand des Apple-Pass-Stil-Wörterbuchs. - Farben: Hintergrund-, Vordergrund- und Labelfarben werden direkt in die Farbpalette übernommen. - Bilder: Retina-Assets (icon.png, logo.png, strip.png) werden in den Asset-Speicher des Workspace hochgeladen. - Feldlayouts: Kopf-, Primär-, Sekundär-, Zusatz- und Rückseitenfelder werden in ihren vorgesehenen Zonen platziert.

  1. 4
    Fahren Sie mit Schritt 2 (Pass-Typ) und Schritt 3 (Wallet-Apps) fort, um die Google-Wallet-Unterstützung zu prüfen oder zu aktivieren.
  2. 5
    Weisen Sie in Schritt 4 (Abschluss) ein Apple-Pass-Type-Zertifikat für die kryptografische Signierung zu und klicken Sie auf Fertigstellen.

Import über die REST-API

Sie können Apple-Pass-Designer-Pakete auch programmgesteuert über POST /api/v1/templates/import importieren.

HTTP-Anfrage (multipart/form-data)

BASH
curl -X POST https://api.passinstance.com/api/v1/templates/import \
  -H "X-API-Key: <API_KEY>" \
  -F "file=@loyalty_pass.passdesign" \
  -F "name=Imported Loyalty Card"

HTTP-Antwort (201 Created)

JSON
{
  "success": true,
  "data": {
    "id": "tmpl_01h8x7j6k5m4n3p2q1",
    "name": "Imported Loyalty Card",
    "kind": "storeCard",
    "status": "PUBLISHED",
    "versionNumber": 1,
    "importedFrom": "apple_pass_designer",
    "imagesImported": ["icon", "logo", "strip"],
    "fieldsCount": 8,
    "createdAt": "2026-11-16T20:35:00.000Z"
  },
  "statusCode": 201
}

Fehlerbehebung beim Apple-Pass-Import

Symptom / FehlerUrsacheLösung
Unsupported file formatDie Dateiendung entspricht nicht der Liste unterstützter Formate.Stellen Sie sicher, dass Ihre Datei auf .passdesign, .plist, .xml, .pkpass, .zip oder .json endet.
Missing required icon assetDas Apple-Paket enthielt weder icon.png noch icon@2x.png.Apple PassKit verlangt für jeden Pass ein Icon. Fügen Sie Ihrem Paket vor dem Import eine PNG-Icon-Datei mit 76x76 oder 114x114 Pixeln hinzu.
Zip entry size exceededEin Bild-Asset im Archiv überschritt das Limit von 1 MB.Optimieren Sie Rasterbilder mit PNG-Komprimierungstools oder laden Sie Assets nach der Vorlagenerstellung separat hoch.
Unsigned package noticeDie importierte .pkpass-Datei enthielt keine gültige kryptografische Signatur.Normal bei Prototyp-Paketen (isUnsignedPackage: true). Passinstance akzeptiert unsignierte Archive und signiert Pässe bei der Ausgabe mit dem Apple-Zertifikat Ihres Workspace.

Entdecken Sie Vorlage aus JSON erstellen für direkte Schema-Importe oder Vorlagendesign & Konfiguration, um das visuelle Design im Editor anzupassen.

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.