Panoramica
Designer e sviluppatori iOS che realizzano prototipi di pass digitali con gli strumenti di sviluppo macOS — come l'app ufficiale Apple Pass Designer, Xcode o editor desktop di terze parti — possono importare i propri progetti direttamente in Passinstance. Non è necessario reinserire manualmente le coordinate dei campi, i valori colore, i tipi di codice a barre né caricare gli asset grafici uno alla volta.
Passinstance offre l'importazione automatizzata per:
-
Archivi di Apple Pass Designer (bundle
.passdesign). -
Documenti XML Apple Property List (
.plisto.xml). -
Pacchetti Apple Wallet firmati o non firmati (archivi zip
.pkpass). -
File di metadati grezzi Apple PassKit (
pass.json).
Il motore di importazione estrae gli asset grafici (icon.png, logo.png, strip.png, thumbnail.png), analizza il layout strutturale e lo normalizza in un modello Passinstance completamente modificabile, compatibile sia con Apple Wallet sia con Google Wallet.
Architettura di sistema: motore di importazione Apple PassKit e Plist
Formati di file ed estensioni supportati
Il modulo di caricamento file nel Template Creation Wizard accetta le seguenti estensioni conformi alla regex /\.(passdesign|plist|xml|pkpass|zip|json)$/i:
| Formato / Estensione | Descrizione | Contenuti estratti |
|---|---|---|
.passdesign | Cartella bundle di Apple Pass Designer o archivio compresso. | Geometria completa del pass, layout visivo dei campi, colori e tutti gli asset PNG retina. |
.plist / .xml | Formato XML Apple Property List. | Strutture dei campi, coppie etichetta/valore, tipi di trasporto, codici a barre e regole di rilevanza. |
.pkpass | Archivio pass standard di Apple Wallet (firmato o non firmato). | pass.json, directory di localizzazione (.lproj) e asset grafici. La firma digitale (signature) e il manifest (manifest.json) vengono ignorati in sicurezza. |
pass.json | Dizionario canonico Apple PassKit. | Struttura JSON standard di Apple PassKit. |
Sicurezza XML e protezione delle entità (parsePlistXmlToObject)
Durante l'importazione di documenti Apple .plist o .xml, Passinstance utilizza un parser XML interno rinforzato (parsePlistXmlToObject in template-import-export.util.ts) con rigorosi invarianti di sicurezza:
-
1
Protezione XXE (zero risoluzione di entità esterne): il parser ignora completamente le dichiarazioni
<!DOCTYPE>, le definizioni di entità esterne (SYSTEMoPUBLIC) e i riferimenti a schemi XML. Ciò elimina le vulnerabilità XML External Entity (XXE) e Server-Side Request Forgery (SSRF). -
2
Salvaguardia su ricorsione e profondità: la profondità di ricorsione è limitata a
MAX_PLIST_DEPTH = 32. Dizionari o array annidati che superano questa soglia vengono interrotti con un'eccezione di validazione per prevenire attacchi di stack overflow. -
3
Prevenzione Zip Bomb: durante l'estrazione di archivi zip
.passdesigno.pkpass, il motore limita il numero totale di voci aMAX_ZIP_ENTRIES = 250e la dimensione non compressa per singolo file aMAX_ZIP_ENTRY_BYTES = 1 MB(1048576byte). -
4
Protezione da Prototype Pollution: le chiavi di proprietà corrispondenti a
__proto__,constructoroprototypevengono rimosse durante la costruzione del dizionario.
Riferimento alla mappatura dei tipi Apple PassKit
L'utility di importazione mappa automaticamente i tipi Apple Property List e le strutture PassKit sui modelli Passinstance:
| Tipo Apple PassKit / Plist | Equivalente modello Passinstance | Comportamento di normalizzazione |
|---|---|---|
<dict> | Object JavaScript | Mappato su gruppi di campi, oggetti colore o dizionari di posizione. |
<array> | Array JavaScript | Mappato sugli array di campi (headerFields, primaryFields, ecc.). |
<string> | string | Ripulisce gli spazi superflui e decodifica le entità XML (&, <, >). |
<integer> / <real> | number | Convertito in numeri interi o a virgola mobile. |
<true/> / <false/> | boolean | Convertito in primitive booleane JavaScript standard. |
<date> | string ISO 8601 | Normalizzato in timestamp UTC ISO-8601 (YYYY-MM-DDTHH:MM:SSZ). |
<data> | string Base64 | Decodificato da Base64 in buffer binari per le immagini. |
Normalizzazione dallo stile Apple al PassKind
| Stile pass Apple | PassKind Passinstance | Invarianti di layout e campi |
|---|---|---|
storeCard | storeCard | Layout frontale con immagine strip; fino a 4 campi secondari/ausiliari. |
coupon | coupon | Layout frontale con immagine strip; i campi ausiliari vengono spostati nei secondari. |
eventTicket | eventTicket | Supporta texture di sfondo, immagine strip e blocchi venue companion di iOS 18. |
boardingPass | boardingPass | Analizza transitType (PKTransitTypeAir, PKTransitTypeTrain, ecc.) e i campi primari di partenza/arrivo. |
generic | generic | Layout multiuso standard con miniatura opzionale. |
Importazione dalla Dashboard (passo dopo passo)
-
1
Vai su Modelli nella Dashboard di Passinstance e fai clic su + Nuovo modello.
-
2
Nel Passaggio 1 (Dettagli) del
Template Creation Wizard:
- Fai clic su Importa pass esistente oppure trascina il file .passdesign, .plist, .pkpass o pass.json nell'area di caricamento.
-
3
La procedura guidata analizza il file all'istante ed estrae:
- Nome e descrizione del modello: precompilati da description o organizationName. - Tipo di pass: rilevato automaticamente in base al dizionario dello stile Apple. - Colori: colori di sfondo, primo piano ed etichette popolati nella palette cromatica. - Immagini: asset retina (icon.png, logo.png, strip.png) caricati nell'archivio asset del workspace. - Layout dei campi: campi di intestazione, primari, secondari, ausiliari e sul retro collocati nelle rispettive zone.
-
4
Prosegui con il Passaggio 2 (Tipo di pass) e il Passaggio 3 (App Wallet) per verificare o abilitare il supporto a Google Wallet.
-
5
Nel Passaggio 4 (Completamento), assegna un certificato Apple Pass Type per abilitare la firma crittografica, quindi fai clic su Fine.
Importazione tramite REST API
Puoi inoltre importare pacchetti Apple Pass Designer in modo programmatico tramite POST /api/v1/templates/import.
Richiesta HTTP (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"
Risposta HTTP (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
}
Risoluzione dei problemi di importazione Apple Pass
| Sintomo / Errore | Causa principale | Soluzione |
|---|---|---|
Unsupported file format | L'estensione del file non rientra nell'elenco supportato. | Assicurati che il file termini con .passdesign, .plist, .xml, .pkpass, .zip o .json. |
Missing required icon asset | Il pacchetto Apple non contiene icon.png o icon@2x.png. | Apple PassKit richiede un'icona per ogni pass. Aggiungi un'icona PNG 76x76 o 114x114 al pacchetto prima dell'importazione. |
Zip entry size exceeded | Un asset grafico nell'archivio supera 1 MB. | Ottimizza le immagini raster con strumenti di compressione PNG oppure carica gli asset separatamente dopo la creazione del modello. |
Unsigned package notice | Il file .pkpass importato non contiene una firma crittografica valida. | Comportamento normale per i pacchetti di prototipo (isUnsignedPackage: true). Passinstance accetta archivi non firmati e firma i pass con il certificato Apple del workspace al momento dell'emissione. |
Approfondisci Creare un modello da JSON per importazioni di schema grezzo oppure Design e configurazione dei modelli per rifinire lo stile visivo nell'editor.
