Skip to content
Helpcentrum-gids · Pass-sjablonen
5 min leestijdGecontroleerd 2026-11-16

Importeren uit Apple Pass Designer

Importeer .passdesign-mappen, Property List (.plist)-bestanden en niet-ondertekende pakketten rechtstreeks in native Passinstance-templates.

In deze gids

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 (.plist of .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

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
APPLE PASS DESIGNER IMPORTENGINE
FASE 01 APPLE PASS DESIGNER-BRONARTEFACTEN
.passdesign-bundel (macOS Pass Designer-documentpakket)
.plist / .xml (Apple Property List-formaat)
.pkpass / .zip (Ondertekende of niet-ondertekende Apple Wallet-bundel)
pass.json (Ruwe Apple PassKit-specificatiedictionary)
FASE 02 IMPORT- & BEVEILIGINGSPARSER
template-import-export.util.ts (parsePlistXmlToObject, parseXmlNodeTree)
Geharde XML-parser: Geen externe entiteitsoplossing (voorkomt XXE-aanvallen)
Dieptebewaking: MAX_PLIST_DEPTH = 32 (voorkomt recursie-overflow)
Zip-veiligheidslimieten: MAX_ZIP_ENTRIES = 250, MAX_ZIP_ENTRY_BYTES = 1 MB
Modus niet-ondertekend pakket: isUnsignedPackage: true (zonder Apple-sign)
FASE 03 PASSKIT-NAAR-PASSINSTANCE SCHEMANORMALIZER
Apple-stijlenPassKind (storeCard, coupon, eventTicket, enz.)
Plist-typenJS-typen (dictObject, arrayArray, realNumber)
Kleuren: Normaliseert Apple rgb(r, g, b) en converteert voor Google hex
Barcodes: Normaliseert PKBarcodeFormat* en wijst watchOS-fallback toe
Asset-extractie: Slaat @1x, @2x, @3x retina-PNG's op in S3-opslag
FASE 04 CANONIEK PASSINSTANCE-SJABLOON (Template-entiteit)
Live interactief voorbeeld in de Apple Wallet- & Google Wallet-simulator
Klaar voor directe pasuitgifte, CSV-batchimport of PassFlow-registratie

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 / extensieBeschrijvingGeëxtraheerde inhoud
.passdesignApple Pass Designer-bundelmap of gecomprimeerd archief.Volledige pasgeometrie, visuele veldindelingen, kleuren en alle retina-PNG-assets.
.plist / .xmlApple Property List XML-formaat.Veldstructuren, label-/waardeparen, vervoerstypen, barcodes en relevantieregels.
.pkpassStandaard Apple Wallet-pasarchief (ondertekend of niet-ondertekend).pass.json, lokalisatiemappen (.lproj) en afbeeldingsassets. Digitale handtekening (signature) en manifest (manifest.json) worden veilig genegeerd.
pass.jsonCanonieke 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. 1
    XXE-bescherming (geen externe entiteitsoplossing): De parser negeert <!DOCTYPE>-declaraties, externe entiteitsdefinities (SYSTEM of PUBLIC) en XML-schemareferenties volledig. Dit sluit XML External Entity (XXE)-injectie en Server-Side Request Forgery (SSRF)-kwetsbaarheden uit.
  2. 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. 3
    Preventie van zip-bommen: Bij het uitpakken van .passdesign- of .pkpass-zipbestanden beperkt de engine het totaal aantal bestanden tot MAX_ZIP_ENTRIES = 250 en de ongecomprimeerde grootte per bestand tot MAX_ZIP_ENTRY_BYTES = 1 MB (1048576 bytes).
  4. 4
    Bescherming tegen prototype-vervuiling: Eigenschapssleutels die overeenkomen met __proto__, constructor of prototype worden 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-typeEquivalent in Passinstance-modelNormalisatiegedrag
<dict>JavaScript ObjectKoppelt aan veldgroepen, kleurobjecten of locatiedictionaries.
<array>JavaScript ArrayKoppelt aan veldarrays (headerFields, primaryFields, enz.).
<string>stringSchoont witruimte op en zet XML-entiteiten terug (&amp;, &lt;, &gt;).
<integer> / <real>numberOmgezet naar floating-point- of gehele getallen.
<true/> / <false/>booleanOmgezet naar standaard JavaScript-booleanprimitieven.
<date>ISO 8601 stringGenormaliseerd naar UTC ISO-8601-tijdstempels (YYYY-MM-DDTHH:MM:SSZ).
<data>Base64 stringBase64-gedecodeerd naar binaire assetbuffers voor afbeeldingen.

Normalisatie van Pass Style naar Pass Kind

Apple Pass StylePassinstance PassKindIndelings- & veldinvarianten
storeCardstoreCardVoorzijde-indeling met stripafbeelding; tot 4 secundaire/hulpvelden.
couponcouponVoorzijde-indeling met stripafbeelding; hulpvelden worden omgeleid naar secundaire velden.
eventTicketeventTicketOndersteunt achtergrondtextuur, stripafbeelding en iOS 18-locatiebegeleidingsblokken.
boardingPassboardingPassParseert transitType (PKTransitTypeAir, PKTransitTypeTrain, enz.) en primaire vertrek-/aankomstvelden.
genericgenericStandaard multifunctionele kaartindeling met optionele miniatuurafbeelding.

Importeren via het Dashboard (stapsgewijs)

  1. 1
    Ga naar Sjablonen in het Passinstance Dashboard en klik op + Nieuw sjabloon.
  2. 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.

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

  1. 4
    Ga door naar Stap 2 (Pastype) en Stap 3 (Wallet-apps) om Google Wallet-ondersteuning te controleren of in te schakelen.
  2. 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)

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-respons (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
}

Probleemoplossing bij Apple Pass-import

Symptoom / foutmeldingOorzaakOplossing
Unsupported file formatDe 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 assetHet 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 exceededEen 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 noticeHet 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.

Klaar om uw eerste kaartprogramma te lanceren?

Maak uw workspace aan, configureer uw sjabloon en test een echte kaart in Apple Wallet en Google Wallet voordat u opschaalt.