Skip to content
Guida del Centro assistenza · Modelli di pass
6 min di letturaVerificato 2026-11-16

Importare da Apple Pass Designer

Importa cartelle .passdesign, file Property List (.plist) e pacchetti non firmati direttamente nei modelli nativi di Passinstance.

In questa guida

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

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
MOTORE DI IMPORTAZIONE APPLE PASS DESIGNER
FASE 01 ARTEFATTI SORGENTE DI APPLE PASS DESIGNER
Bundle .passdesign (pacchetto documento macOS Pass Designer)
.plist / .xml (formato Apple Property List)
.pkpass / .zip (bundle Apple Wallet firmato o non firmato)
pass.json (dizionario grezzo della specifica Apple PassKit)
FASE 02 PARSER DI IMPORTAZIONE E SICUREZZA
template-import-export.util.ts (parsePlistXmlToObject, parseXmlNodeTree)
Parser XML rinforzato: nessuna risoluzione entità esterne (anti-XXE)
Limite profondità: MAX_PLIST_DEPTH = 32 (previene overflow ricorsivo)
Limiti sicurezza Zip: MAX_ZIP_ENTRIES = 250, MAX_ZIP_ENTRY_BYTES = 1 MB
Modalità non firmata: isUnsignedPackage: true (ignora la firma Apple)
FASE 03 NORMALIZZATORE SCHEMA DA PASSKIT A PASSINSTANCE
Stili ApplePassKind (storeCard, coupon, eventTicket, ecc.)
Tipi PlistTipi JS (dictObject, arrayArray, realNumber)
Colori: normalizza rgb(r, g, b) Apple e converte in hex per Google Wallet
Barcode: normalizza PKBarcodeFormat* e assegna il fallback watchOS
Estrazione asset: salva i PNG retina @1x, @2x, @3x su storage S3
FASE 04 MODELLO CANONICO PASSINSTANCE (Entità Template)
Anteprima interattiva live nel simulatore Apple Wallet e Google Wallet
Pronto per emissione immediata, importazione batch CSV o iscrizione PassFlow

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 / EstensioneDescrizioneContenuti estratti
.passdesignCartella bundle di Apple Pass Designer o archivio compresso.Geometria completa del pass, layout visivo dei campi, colori e tutti gli asset PNG retina.
.plist / .xmlFormato XML Apple Property List.Strutture dei campi, coppie etichetta/valore, tipi di trasporto, codici a barre e regole di rilevanza.
.pkpassArchivio 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.jsonDizionario 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. 1
    Protezione XXE (zero risoluzione di entità esterne): il parser ignora completamente le dichiarazioni <!DOCTYPE>, le definizioni di entità esterne (SYSTEM o PUBLIC) e i riferimenti a schemi XML. Ciò elimina le vulnerabilità XML External Entity (XXE) e Server-Side Request Forgery (SSRF).
  2. 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. 3
    Prevenzione Zip Bomb: durante l'estrazione di archivi zip .passdesign o .pkpass, il motore limita il numero totale di voci a MAX_ZIP_ENTRIES = 250 e la dimensione non compressa per singolo file a MAX_ZIP_ENTRY_BYTES = 1 MB (1048576 byte).
  4. 4
    Protezione da Prototype Pollution: le chiavi di proprietà corrispondenti a __proto__, constructor o prototype vengono 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 / PlistEquivalente modello PassinstanceComportamento di normalizzazione
<dict>Object JavaScriptMappato su gruppi di campi, oggetti colore o dizionari di posizione.
<array>Array JavaScriptMappato sugli array di campi (headerFields, primaryFields, ecc.).
<string>stringRipulisce gli spazi superflui e decodifica le entità XML (&amp;, &lt;, &gt;).
<integer> / <real>numberConvertito in numeri interi o a virgola mobile.
<true/> / <false/>booleanConvertito in primitive booleane JavaScript standard.
<date>string ISO 8601Normalizzato in timestamp UTC ISO-8601 (YYYY-MM-DDTHH:MM:SSZ).
<data>string Base64Decodificato da Base64 in buffer binari per le immagini.

Normalizzazione dallo stile Apple al PassKind

Stile pass ApplePassKind PassinstanceInvarianti di layout e campi
storeCardstoreCardLayout frontale con immagine strip; fino a 4 campi secondari/ausiliari.
couponcouponLayout frontale con immagine strip; i campi ausiliari vengono spostati nei secondari.
eventTicketeventTicketSupporta texture di sfondo, immagine strip e blocchi venue companion di iOS 18.
boardingPassboardingPassAnalizza transitType (PKTransitTypeAir, PKTransitTypeTrain, ecc.) e i campi primari di partenza/arrivo.
genericgenericLayout multiuso standard con miniatura opzionale.

Importazione dalla Dashboard (passo dopo passo)

  1. 1
    Vai su Modelli nella Dashboard di Passinstance e fai clic su + Nuovo modello.
  2. 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.

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

  1. 4
    Prosegui con il Passaggio 2 (Tipo di pass) e il Passaggio 3 (App Wallet) per verificare o abilitare il supporto a Google Wallet.
  2. 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)

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"

Risposta HTTP (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
}

Risoluzione dei problemi di importazione Apple Pass

Sintomo / ErroreCausa principaleSoluzione
Unsupported file formatL'estensione del file non rientra nell'elenco supportato.Assicurati che il file termini con .passdesign, .plist, .xml, .pkpass, .zip o .json.
Missing required icon assetIl 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 exceededUn 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 noticeIl 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.

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.