Skip to content
Guida del Centro assistenza · Integrazioni WalletFase di onboarding 4
3 min di letturaVerificato 2026-11-16

Apple Wallet

Come Passinstance genera archivi .pkpass, firma PKCS#7, registra dispositivi iOS/watchOS e gestisce callback.

In questa guida

Guide visive interattive UI

Apri nella guida in 6 fasi

Esplora schermate reali della dashboard e dettagli ingranditi collegati a questa guida.

Focus UI ingrandito
Elementi chiave dell'interfaccia

Anteprima pass dal vivo Dual-Wallet (Zoom)

Passa tra Apple e Google nel pannello di anteprima per confermare grafica, formattazione del saldo, leggibilità del QR code e allineamento dei campi.

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.

Anteprima live dei pass Apple Wallet vs Google Wallet
Anteprima live dei pass Apple Wallet vs Google Wallet
FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
IMPACCHETTAMENTO .PKPASS APPLE WALLET E WEB SERVICE
FASE 01 BUILDER ARCHIVIO PKPASS (Apple Wallet Packager)
1
Serializza pass.json (formatVersion: 1, colori rgb(r,g,b), campi, NFC)
2
Prepara gli asset Retina (icon.png, logo.png, strip.png @1x/@2x/@3x)
3
Compila i bundle localizzazione (<lang>.lproj/pass.strings in UTF-8)
4
Calcola il dizionario checksum SHA-1scrive manifest.json
5
Genera signature PKCS#7 detached (Cert Pass Type + Apple WWDR G4/G6)
6
Comprime archivio ZIPStream Content-Type: application/vnd.apple.pkpass
FASE 02 PROTOCOLLO WEB SERVICE APPLE WALLET (/v1)
Registra dispositivo: POST/v1/devices/:deviceLibId/registrations/:typeId/:sn
Controlla aggiornati: GET/v1/devices/:deviceLibId/registrations/:typeId
Scarica bundle: GET/v1/passes/:passTypeId/:serialNumber
Rimuovi pass: DELETE/v1/devices/:deviceLibId/registrations/:typeId/:sn
Log errori client: POST/v1/log

Struttura interna di un archivio .pkpass

Un bundle .pkpass di Apple Wallet è un normale archivio ZIP contenente cinque livelli strutturali essenziali:

File / DirectoryFormato e codificaRuolo in Apple Wallet
pass.jsonJSON UTF-8Definisce 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.stringsTabella stringhe UTF-8Traduzioni localizzate chiave-valore (es. de.lproj/pass.strings, fr.lproj/pass.strings) abbinate alla lingua di sistema dell'iPhone.
manifest.jsonJSON UTF-8Dizionario piatto che mappa ogni percorso file relativo nel bundle (esclusi manifest.json e signature) al rispettivo hash esadecimale SHA-1 a 40 caratteri.
signatureDER 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 stringhe rgb(r, g, b). apple-pass-field.serializer.ts di Passinstance converte automaticamente i valori esadecimali in rgb(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

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>:

MetodoPercorso endpointStati HTTPScopo
POST/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber201 Created, 200 OK, 401 UnauthorizedRegistra il pushToken dell'iPhone o dell'Apple Watch per gli aggiornamenti APNs e contrassegna il pass come installato.
GET/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier200 OK, 204 No ContentRestituisce { serialNumbers: [...], lastUpdated: "<tag>" } per i pass modificati da ?passesUpdatedSince=.
GET/v1/passes/:passTypeIdentifier/:serialNumber200 OK, 304 Not Modified, 401 UnauthorizedGenera 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/:serialNumber200 OK, 401 UnauthorizedAnnulla la registrazione del dispositivo quando il titolare elimina il pass da Apple Wallet.
POST/v1/log200 OKRiceve 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.

Documentazione prodotto e API correlata

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.