Creare pass nativi per Apple Wallet (file .pkpass) consente alle aziende di consegnare carte fedeltà, biglietti evento, carte d'imbarco, coupon e tessere socio direttamente su iPhone e Apple Watch senza costringere gli utenti a scaricare un'applicazione dedicata.
Questa guida completa per il 2026 illustra tutto ciò che sviluppatori e product manager devono conoscere su architettura Apple PassKit, firma crittografica, distribuzione e aggiornamenti push tramite APNs.
1. Anatomia di un pass Apple Wallet (.pkpass)
Un pass Apple Wallet è un archivio ZIP compresso con estensione .pkpass contenente JSON strutturato, immagini localizzate e manifest di firma crittografica verificati da Apple.
Struttura richiesta del pacchetto
mio-pass.pkpass
├── pass.json # Layout principale, definizione dei campi e metadati
├── logo.png # Logo del marchio in alto a sinistra (160x160 @2x)
├── logo@2x.png
├── icon.png # Icona per le notifiche su blocco schermo (58x58 @2x)
├── icon@2x.png
├── strip.png # Immagine principale per biglietti evento e coupon (375x144 @2x)
├── strip@2x.png
├── manifest.json # Hash crittografici di tutti i file nel pacchetto
└── signature # Firma crittografica PKCS#7 creata con il certificato Pass Type ID
2. Configurazione Apple Developer e firma con certificato
Per firmare nativamente pass Apple Wallet in produzione, Apple richiede credenziali di firma PKCS#12 emesse da un account Apple Developer attivo.
Passaggi della pipeline di firma:
-
1
Pass Type ID: Registra un identificativo univoco (es.
pass.com.tuaazienda.fedelta) nell'Apple Developer Portal. -
2
Certificate Signing Request (CSR): Genera una chiave privata RSA a 2048 bit e una CSR tramite OpenSSL o Accesso Portachiavi.
-
3
Certificato Pass Type: Scarica il file
.ceremesso ed esportalo come contenitore.p12insieme alla chiave privata. -
4
Certificato intermedio WWDR: Includi nella catena di fiducia il certificato intermedio Apple Worldwide Developer Relations G6.
[!NOTE]
Nota sulla firma in produzione: Per firmare ed emettere pass Apple Wallet in produzione, richiedi il tuo certificato Apple Developer Pass Type ID per la firma
.pkpassin produzione. Passinstance gestisce poi la compilazione PKCS#7, il certificato intermedio WWDR e la distribuzione del pacchetto.pkpass.
3. Configurazione dei campi in pass.json
Il file pass.json stabilisce lo stile del pass (storeCard, coupon, eventTicket, boardingPass, generic), i colori in formato rgb(r, g, b) e i campi dinamici:
{
"formatVersion": 1,
"passTypeIdentifier": "pass.com.passinstance.loyalty",
"serialNumber": "PASS-8842-2026",
"teamIdentifier": "ABC123XYZ",
"organizationName": "Artisan Coffee",
"description": "Tessera fedeltà Artisan Coffee",
"logoText": "Artisan Coffee",
"foregroundColor": "rgb(255, 255, 255)",
"backgroundColor": "rgb(10, 90, 84)",
"labelColor": "rgb(164, 243, 222)",
"storeCard": {
"primaryFields": [
{
"key": "stamps",
"label": "AVANZAMENTO PREMI",
"value": "8 su 10 Timbri"
}
],
"secondaryFields": [
{
"key": "holder",
"label": "SOCIO",
"value": "Jane Doe"
}
]
},
"barcodes": [
{
"format": "PKBarcodeFormatQR",
"message": "PASS-LOYALTY-8842",
"messageEncoding": "iso-8859-1"
}
],
"webServiceURL": "https://api.passinstance.com/api/v1/apple",
"authenticationToken": "<token_autenticazione>"
}

4. Coordinate di posizione native e avvisi su blocco schermo
I pass Apple Wallet supportano fino a 10 coordinate geografiche (locations / posizioni rilevanti) per attivare promemoria passivi sulla schermata di blocco quando il cliente si avvicina fisicamente al punto vendita o alla sede dell'evento.
"locations": [
{
"latitude": 45.464211,
"longitude": 9.191383,
"relevantText": "Bentornato! Mostra la tua tessera alla cassa per il 10% di sconto."
}
]
5. Invio di aggiornamenti su schermata di blocco (APNs)
Quando il saldo, il livello fedeltà o la scadenza di un pass cambiano, Apple Wallet aggiorna la tessera over-the-air tramite Apple Push Notification service (APNs):
-
1
Al momento dell'installazione, iOS invia una richiesta POST al tuo
webServiceURLregistrando ilpushTokendel dispositivo. -
2
Per aggiornare il pass, il server invia un payload push APNs vuoto verso i server Apple per quel
pushToken. -
3
iOS si risveglia in background, scarica l'ultima versione di
pass.jsondal server, aggiorna la tessera e mostra un avviso sullo schermo di blocco se è cambiato un campo dotato dichangeMessage.
6. Generazione rapida di pass Apple Wallet con Passinstance
Anziché mantenere pipeline OpenSSL dedicate, infrastruttura APNs ed endpoint di registrazione dispositivi, Passinstance automatizza l'intero ciclo operativo una volta collegato il tuo certificato:
import { Passinstance } from "@passinstance/sdk";
const client = new Passinstance({ apiKey: process.env.PASSINSTANCE_API_KEY });
// Emette un pass Apple Wallet con firma dal vivo
const pass = await client.passes.create({
templateId: "tpl_coffee_loyalty",
data: {
holderName: "Jane Doe",
stamps: "8 su 10 Timbri",
},
});
console.log("Link Aggiungi ad Apple Wallet:", pass.appleWalletUrl);

Punti chiave
-
Nessuna app richiesta: I clienti salvano il pass in un tocco da Safari, QR code, e-mail o link ospitato.
-
Sempre aggiornato: Le variazioni di saldo si sincronizzano su iPhone e Apple Watch.
-
Pertinenza geografica: Le coordinate configurate possono mostrare il pass sullo schermo di blocco vicino al punto vendita.





