Ü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 (
.plistoder.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
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 / Endung | Beschreibung | Extrahierte Inhalte |
|---|---|---|
.passdesign | Apple-Pass-Designer-Bundle-Ordner oder komprimiertes Archiv. | Vollständige Pass-Geometrie, visuelle Feldlayouts, Farben sowie alle Retina-PNG-Assets. |
.plist / .xml | Apple-Property-List-XML-Format. | Feldstrukturen, Label-/Wertepaare, Transit-Typen, Barcodes und Relevanzregeln. |
.pkpass | Standardmäß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.json | Kanonisches 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
XXE-Schutz (Keine Auflösung externer Entitäten): Der Parser ignoriert
<!DOCTYPE>-Deklarationen, externe Entity-Definitionen (SYSTEModerPUBLIC) sowie XML-Schema-Referenzen vollständig. Dadurch werden XML-External-Entity-Angriffe (XXE) und Server-Side Request Forgery (SSRF) ausgeschlossen. -
2
Rekursions- & Tiefenschutz: Die Rekursionstiefe ist auf
MAX_PLIST_DEPTH = 32begrenzt. Verschachtelte Wörterbücher oder Arrays, die diesen Schwellenwert überschreiten, werden mit einer Validierungsausnahme abgebrochen, um Stack-Overflow-Angriffe zu verhindern. -
3
Zip-Bomb-Prävention: Beim Entpacken von
.passdesign- oder.pkpass-ZIP-Dateien begrenzt die Engine die Gesamtanzahl der Einträge aufMAX_ZIP_ENTRIES = 250und die unkomprimierte Größe pro Datei aufMAX_ZIP_ENTRY_BYTES = 1 MB(1048576Bytes). -
4
Schutz vor Prototype Pollution: Eigenschaftsschlüssel, die
__proto__,constructoroderprototypeentsprechen, 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-Typ | Passinstance-Modell-Äquivalent | Normalisierungsverhalten |
|---|---|---|
<dict> | JavaScript Object | Wird auf Feldgruppen, Farbobjekte oder Standort-Wörterbücher abgebildet. |
<array> | JavaScript Array | Wird auf Feld-Arrays (headerFields, primaryFields usw.) abgebildet. |
<string> | string | Bereinigt Leerzeichen und dekodiert XML-Entitäten (&, <, >). |
<integer> / <real> | number | Wird in Gleitkomma- oder Ganzzahlen konvertiert. |
<true/> / <false/> | boolean | Wird in reguläre boolesche JavaScript-Werte konvertiert. |
<date> | ISO-8601 string | Wird auf UTC-ISO-8601-Zeitstempel (YYYY-MM-DDTHH:MM:SSZ) normalisiert. |
<data> | Base64 string | Wird per Base64 in binäre Asset-Puffer für Bilder dekodiert. |
Normalisierung von Pass-Stil zu Pass-Art
| Apple-Pass-Stil | Passinstance PassKind | Layout- & Feldinvarianten |
|---|---|---|
storeCard | storeCard | Vorderseitenlayout mit Strip-Bild; bis zu 4 Sekundär-/Zusatzfelder. |
coupon | coupon | Vorderseitenlayout mit Strip-Bild; Zusatzfelder werden in Sekundärfelder umgeleitet. |
eventTicket | eventTicket | Unterstützt Hintergrundtextur, Strip-Bild sowie iOS-18-Venue-Companion-Blöcke. |
boardingPass | boardingPass | Parst transitType (PKTransitTypeAir, PKTransitTypeTrain usw.) sowie primäre Abflug-/Ankunftsfelder. |
generic | generic | Vielseitiges Standard-Kartenlayout mit optionalem Vorschaubild. |
Import über das Dashboard (Schritt für Schritt)
-
1
Navigieren Sie im Passinstance-Dashboard zu Vorlagen und klicken Sie auf + Neue Vorlage.
-
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.
-
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.
-
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.
-
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)
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)
{
"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 / Fehler | Ursache | Lösung |
|---|---|---|
Unsupported file format | Die 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 asset | Das 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 exceeded | Ein 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 notice | Die 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.
