Panoramica: come funziona l'integrazione con Apple Wallet
Passinstance genera bundle nativi .pkpass di Apple Wallet (Apple Wallet Packager) conformi alla specifica di pacchetto PassKit di Apple per iOS e watchOS. Ogni pass viene assemblato al momento come archivio ZIP firmato crittograficamente e distribuito con MIME type application/vnd.apple.pkpass.

Struttura interna di un archivio .pkpass
Un bundle .pkpass di Apple Wallet è un normale archivio ZIP contenente cinque livelli strutturali essenziali:
| File / Directory | Formato e codifica | Ruolo in Apple Wallet |
|---|---|---|
pass.json | JSON UTF-8 | Definisce stile del pass (storeCard, coupon, eventTicket, boardingPass, generic), passTypeIdentifier, teamIdentifier, serialNumber, authenticationToken, webServiceURL, campi, codici a barre, posizioni e dizionario nfc. |
Asset visivi (.png) | PNG (@1x, @2x, @3x) | Fino a 13 slot immagini del modello trasformati nei nomi file Apple PassKit (icon.png, logo.png, strip.png, thumbnail.png, background.png, footer.png, artwork.png, venueMap.png) alle diverse risoluzioni retina. |
<lang>.lproj/pass.strings | Tabella stringhe UTF-8 | Traduzioni localizzate chiave-valore (es. de.lproj/pass.strings, fr.lproj/pass.strings) abbinate alla lingua di sistema dell'iPhone. |
manifest.json | JSON UTF-8 | Dizionario piatto che mappa ogni percorso file relativo nel bundle (esclusi manifest.json e signature) al rispettivo hash esadecimale SHA-1 a 40 caratteri. |
signature | DER binario (PKCS#7) | Firma crittografica PKCS#7 detached di manifest.json, firmata dalla propria chiave privata Apple Pass Type ID e collegata al certificato intermedio Apple WWDR G4/G6. |
Importante: Apple Wallet richiede rigorosamente che i valori colore in
pass.json(backgroundColor,foregroundColor,labelColor) siano serializzati come stringhergb(r, g, b).apple-pass-field.serializer.tsdi Passinstance converte automaticamente i valori esadecimali inrgb(r, g, b)ed elimina eventuali canali alfa affinché iOS non rifiuti mai un bundle durante la verifica della firma e dello schema.
Esempio di struttura del payload pass.json
{
"formatVersion": 1,
"passTypeIdentifier": "pass.com.yourbrand.loyalty",
"serialNumber": "PI-8849-2026-X9",
"teamIdentifier": "9A8B7C6D5E",
"organizationName": "Phenix Roasters",
"description": "Phenix VIP Rewards Card",
"webServiceURL": "https://api.passinstance.com",
"authenticationToken": "b7f9e2c1a4d80931f6e5c2b8a1049d7e",
"foregroundColor": "rgb(255, 255, 255)",
"backgroundColor": "rgb(18, 24, 38)",
"labelColor": "rgb(148, 163, 184)",
"storeCard": {
"headerFields": [
{
"key": "tier",
"label": "TIER",
"value": "Gold"
}
],
"primaryFields": [
{
"key": "points",
"label": "POINTS BALANCE",
"value": 1450,
"changeMessage": "Your points balance updated to %@"
}
],
"backFields": [
{
"key": "support_link",
"label": "MEMBER PORTAL",
"value": "Visit https://yourbrand.com/member",
"attributedValue": "<a href=\"https://yourbrand.com/member\">Open Member Portal</a>"
}
]
},
"barcodes": [
{
"format": "PKBarcodeFormatQR",
"message": "PI-8849-2026-X9",
"messageEncoding": "iso-8859-1",
"altText": "PI-8849-2026-X9"
}
]
}
Endpoint Web Service di Apple Wallet (/v1)
Ogni pass attivo contiene webServiceURL e un authenticationToken di almeno 16 caratteri. I dispositivi iOS e watchOS comunicano direttamente con gli endpoint /v1 di Passinstance tramite l'header HTTP Authorization: ApplePass <authenticationToken>:
| Metodo | Percorso endpoint | Stati HTTP | Scopo |
|---|---|---|---|
| POST | /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber | 201 Created, 200 OK, 401 Unauthorized | Registra il pushToken dell'iPhone o dell'Apple Watch per gli aggiornamenti APNs e contrassegna il pass come installato. |
| GET | /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier | 200 OK, 204 No Content | Restituisce { serialNumbers: [...], lastUpdated: "<tag>" } per i pass modificati da ?passesUpdatedSince=. |
| GET | /v1/passes/:passTypeIdentifier/:serialNumber | 200 OK, 304 Not Modified, 401 Unauthorized | Genera e trasmette il bundle .pkpass firmato più recente quando risvegliato da una push APNs o dal trascinamento manuale di aggiornamento. |
| DELETE | /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber | 200 OK, 401 Unauthorized | Annulla la registrazione del dispositivo quando il titolare elimina il pass da Apple Wallet. |
| POST | /v1/log | 200 OK | Riceve array diagnostici { "logs": [...] } dai dispositivi iOS qualora un .pkpass non superi la validazione lato client. |
Approfondisca le specifiche tecniche in Piattaforma Apple Wallet, Certificati Apple Wallet e Protocollo contactless Apple VAS.
