Overzicht
Ontwerpers en iOS-ontwikkelaars die prototypes van digitale passen bouwen met macOS-ontwikkeltools — zoals Apple's officiële Pass Designer, Xcode of desktopbuilders van derden — kunnen hun ontwerpen rechtstreeks importeren in Passinstance. U hoeft veldcoördinaten, kleurwaarden en barcodetypen niet handmatig over te nemen en afbeeldingsassets niet één voor één opnieuw te uploaden.
Passinstance biedt geautomatiseerde import voor:
-
Apple Pass Designer-archieven (
.passdesign-bundels). -
Apple Property List XML-documenten (
.plistof.xml). -
Niet-ondertekende of ondertekende Apple Wallet-pakketten (
.pkpass-ziparchieven). -
Ruwe Apple PassKit-metadatabestanden (
pass.json).
De importengine extraheert afbeeldingsassets (icon.png, logo.png, strip.png, thumbnail.png), parseert de structurele indeling en normaliseert alles tot een volledig bewerkbaar Passinstance-sjabloon dat compatibel is met zowel Apple Wallet als Google Wallet.
Systeemarchitectuur: Apple PassKit- & Plist-importengine
Ondersteunde bestandsformaten & extensies
De bestandsuploader in de Template Creation Wizard accepteert de volgende extensies die voldoen aan de regex /\.(passdesign|plist|xml|pkpass|zip|json)$/i:
| Formaat / extensie | Beschrijving | Geëxtraheerde inhoud |
|---|---|---|
.passdesign | Apple Pass Designer-bundelmap of gecomprimeerd archief. | Volledige pasgeometrie, visuele veldindelingen, kleuren en alle retina-PNG-assets. |
.plist / .xml | Apple Property List XML-formaat. | Veldstructuren, label-/waardeparen, vervoerstypen, barcodes en relevantieregels. |
.pkpass | Standaard Apple Wallet-pasarchief (ondertekend of niet-ondertekend). | pass.json, lokalisatiemappen (.lproj) en afbeeldingsassets. Digitale handtekening (signature) en manifest (manifest.json) worden veilig genegeerd. |
pass.json | Canonieke Apple PassKit-dictionary. | Standaard Apple PassKit JSON-structuur. |
XML-beveiliging & entiteitsveiligheid (parsePlistXmlToObject)
Bij het verwerken van Apple .plist- of .xml-documenten gebruikt Passinstance een geharde interne XML-parser (parsePlistXmlToObject in template-import-export.util.ts) met strikte beveiligingsinvarianten:
-
1
XXE-bescherming (geen externe entiteitsoplossing): De parser negeert
<!DOCTYPE>-declaraties, externe entiteitsdefinities (SYSTEMofPUBLIC) en XML-schemareferenties volledig. Dit sluit XML External Entity (XXE)-injectie en Server-Side Request Forgery (SSRF)-kwetsbaarheden uit. -
2
Beveiliging tegen recursie & overmatige diepte: De recursiediepte is begrensd op
MAX_PLIST_DEPTH = 32. Geneste dictionaries of arrays die deze grens overschrijden worden afgebroken met een validatiefout om stack-overflow-aanvallen te voorkomen. -
3
Preventie van zip-bommen: Bij het uitpakken van
.passdesign- of.pkpass-zipbestanden beperkt de engine het totaal aantal bestanden totMAX_ZIP_ENTRIES = 250en de ongecomprimeerde grootte per bestand totMAX_ZIP_ENTRY_BYTES = 1 MB(1048576bytes). -
4
Bescherming tegen prototype-vervuiling: Eigenschapssleutels die overeenkomen met
__proto__,constructorofprototypeworden tijdens het opbouwen van dictionaries verwijderd.
Referentie voor Apple PassKit-typekoppelingen
De importutility koppelt Apple Property List-typen en PassKit-structuren automatisch aan Passinstance-modellen:
| Apple PassKit- / Plist-type | Equivalent in Passinstance-model | Normalisatiegedrag |
|---|---|---|
<dict> | JavaScript Object | Koppelt aan veldgroepen, kleurobjecten of locatiedictionaries. |
<array> | JavaScript Array | Koppelt aan veldarrays (headerFields, primaryFields, enz.). |
<string> | string | Schoont witruimte op en zet XML-entiteiten terug (&, <, >). |
<integer> / <real> | number | Omgezet naar floating-point- of gehele getallen. |
<true/> / <false/> | boolean | Omgezet naar standaard JavaScript-booleanprimitieven. |
<date> | ISO 8601 string | Genormaliseerd naar UTC ISO-8601-tijdstempels (YYYY-MM-DDTHH:MM:SSZ). |
<data> | Base64 string | Base64-gedecodeerd naar binaire assetbuffers voor afbeeldingen. |
Normalisatie van Pass Style naar Pass Kind
| Apple Pass Style | Passinstance PassKind | Indelings- & veldinvarianten |
|---|---|---|
storeCard | storeCard | Voorzijde-indeling met stripafbeelding; tot 4 secundaire/hulpvelden. |
coupon | coupon | Voorzijde-indeling met stripafbeelding; hulpvelden worden omgeleid naar secundaire velden. |
eventTicket | eventTicket | Ondersteunt achtergrondtextuur, stripafbeelding en iOS 18-locatiebegeleidingsblokken. |
boardingPass | boardingPass | Parseert transitType (PKTransitTypeAir, PKTransitTypeTrain, enz.) en primaire vertrek-/aankomstvelden. |
generic | generic | Standaard multifunctionele kaartindeling met optionele miniatuurafbeelding. |
Importeren via het Dashboard (stapsgewijs)
-
1
Ga naar Sjablonen in het Passinstance Dashboard en klik op + Nieuw sjabloon.
-
2
In Stap 1 (Details) van de
Template Creation Wizard:
- Klik op Bestaande pas importeren of sleep uw .passdesign-, .plist-, .pkpass- of pass.json-bestand in de uploadzone.
-
3
De wizard parseert het bestand direct en extraheert:
- Sjabloonnaam & beschrijving: Vooraf ingevuld op basis van description of organizationName. - Pastype (PassKind): Automatisch herkend op basis van de Apple-passtijldictionary. - Kleuren: Achtergrond-, voorgrond- en labelkleuren worden overgenomen in het kleurenpalet. - Afbeeldingen: Retina-assets (icon.png, logo.png, strip.png) worden geüpload naar de assetopslag van de werkruimte. - Veldindelingen: Koptekst-, primaire, secundaire, hulp- en achterzijdevelden worden in de bijbehorende zones geplaatst.
-
4
Ga door naar Stap 2 (Pastype) en Stap 3 (Wallet-apps) om Google Wallet-ondersteuning te controleren of in te schakelen.
-
5
Wijs in Stap 4 (Voltooiing) een Apple Pass Type-certificaat toe voor cryptografische ondertekening en klik op Voltooien.
Importeren via de REST API
U kunt Apple Pass Designer-pakketten ook programmatisch importeren via POST /api/v1/templates/import.
HTTP-verzoek (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-respons (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
}
Probleemoplossing bij Apple Pass-import
| Symptoom / foutmelding | Oorzaak | Oplossing |
|---|---|---|
Unsupported file format | De bestandsextensie komt niet voor op de lijst met ondersteunde formaten. | Zorg dat uw bestand eindigt op .passdesign, .plist, .xml, .pkpass, .zip of .json. |
Missing required icon asset | Het Apple-pakket bevatte geen icon.png of icon@2x.png. | Apple PassKit vereist een icoon voor elke pas. Voeg een PNG-icoon van 76x76 of 114x114 pixels toe aan uw pakket vóór het importeren. |
Zip entry size exceeded | Een afbeeldingsasset in het archief was groter dan 1 MB. | Optimaliseer rasterafbeeldingen met PNG-compressietools of upload assets afzonderlijk na het aanmaken van het sjabloon. |
Unsigned package notice | Het geïmporteerde .pkpass-bestand bevatte geen geldige cryptografische handtekening. | Normaal voor prototypepakketten (isUnsignedPackage: true). Passinstance accepteert niet-ondertekende archieven en ondertekent passen bij uitgifte met het Apple-certificaat van uw werkruimte. |
Bekijk Een sjabloon maken vanuit JSON voor ruwe schema-imports of Sjabloonontwerp & configuratie om de visuele vormgeving in de editor aan te passen.
