Skip to content
Helpcentrum-gids · Wallet-integratiesOnboardingfase 4
3 min leestijdGecontroleerd 2026-11-16

Apple Wallet

Hoe Passinstance .pkpass-bestanden bouwt, signeert met PKCS#7, iOS/watchOS-toestellen registreert en updates afhandelt.

In deze gids

Interactieve UI-weergaven

Openen in onboardinggids (6 fasen)

Bekijk de exacte dashboardpanelen, knoppen en ingezoomde toelichtingen bij deze gids.

Ingezoomde UI-focus
Belangrijke UI-onderdelen

Dual-Wallet live pasvoorbeeld (Ingesneden)

Schakel tussen Apple en Google in het voorbeeldpaneel om artwork, saldo-opmaak, leesbaarheid van de QR-code en velduitlijning te controleren.

Overzicht: hoe de Apple Wallet-integratie werkt

Passinstance genereert native Apple Wallet .pkpass-bundels (Apple Wallet Packager) die voldoen aan Apple's PassKit-pakketspecificatie voor iOS en watchOS. Elke pas wordt on the fly samengesteld als een cryptografisch ondertekend ZIP-archief en aangeboden met het MIME-type application/vnd.apple.pkpass.

Live pasvoorbeeld van Apple Wallet vs. Google Wallet
Live pasvoorbeeld van Apple Wallet vs. Google Wallet
SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
APPLE WALLET .PKPASS-PAKKETTERING & WEB SERVICE
FASE 01 PKPASS-ARCHIEFBOUWER (Apple Wallet Packager)
1
pass.json serialiseren (formatVersion: 1, rgb(r,g,b), velden, NFC)
2
Retina-assets hydrateren (icon.png, logo.png, strip.png @1x/@2x/@3x)
3
Lokalisatiebundels compileren (<lang>.lproj/pass.strings in UTF-8)
4
SHA-1-checksumwoordenboek berekenenmanifest.json wegschrijven
5
Losse PKCS#7-signature genereren (Pass Type Cert + Apple WWDR G4/G6)
6
ZIP-archief comprimerenStreamen als Content-Type: application/vnd.apple.pkpass
FASE 02 APPLE WALLET WEB SERVICE-PROTOCOL (/v1)
Apparaat registreren: POST/v1/devices/:deviceLibId/registrations/:typeId/:sn
Bijgewerkte lijst ophalen: GET/v1/devices/:deviceLibId/registrations/:typeId
Bundel downloaden: GET/v1/passes/:passTypeId/:serialNumber
Pas uitschrijven: DELETE/v1/devices/:deviceLibId/registrations/:typeId/:sn
Clientfouten loggen: POST/v1/log

Interne structuur van een .pkpass-archief

Een Apple Wallet .pkpass-bundel is een standaard ZIP-archief dat bestaat uit vijf structurele kernlagen:

Bestand / mapFormaat en coderingRol in Apple Wallet
pass.jsonUTF-8 JSONDefinieert de passtijl (storeCard, coupon, eventTicket, boardingPass, generic), passTypeIdentifier, teamIdentifier, serialNumber, authenticationToken, webServiceURL, velden, barcodes, locaties en het nfc-woordenboek.
Visuele assets (.png)PNG (@1x, @2x, @3x)Tot 13 sjabloonafbeeldingsslots die worden gehydrateerd naar Apple PassKit-bestandsnamen (icon.png, logo.png, strip.png, thumbnail.png, background.png, footer.png, artwork.png, venueMap.png) over alle retina-resoluties.
<lang>.lproj/pass.stringsUTF-8 Strings-tabelGelokaliseerde sleutel-waardevertalingen (bijv. de.lproj/pass.strings, fr.lproj/pass.strings) afgestemd op de systeemtaal van de iPhone.
manifest.jsonUTF-8 JSONEen plat woordenboek dat elk relatief bestandspad in de bundel (met uitzondering van manifest.json en signature) koppelt aan de 40 tekens lange hexadecimale SHA-1-hash.
signatureBinair DER (PKCS#7)Losse cryptografische PKCS#7-handtekening van manifest.json, ondertekend met uw privésleutel voor de Apple Pass Type ID en gekoppeld aan het Apple WWDR G4/G6-tussencertificaat.

Belangrijk: Apple Wallet vereist strikt dat kleurwaarden in pass.json (backgroundColor, foregroundColor, labelColor) worden geserialiseerd als rgb(r, g, b)-strings. De apple-pass-field.serializer.ts van Passinstance zet hex-waarden automatisch om naar rgb(r, g, b) en verwijdert alfakanalen, zodat iOS een bundel nooit afwijst tijdens handtekening- en schemaverificatie.

Voorbeeld van een pass.json-payloadstructuur

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"
    }
  ]
}

Apple Wallet Web Service-endpoints (/v1)

Elke actieve pas bevat een webServiceURL en een authenticationToken van minimaal 16 tekens. iOS- en watchOS-apparaten communiceren rechtstreeks met de /v1-endpoints van Passinstance via de HTTP-header Authorization: ApplePass <authenticationToken>:

MethodeEndpoint-padHTTP-statuscodesDoel
POST/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber201 Created, 200 OK, 401 UnauthorizedRegistreert de pushToken van de iPhone of Apple Watch voor APNs-updates en markeert de pas als geïnstalleerd.
GET/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier200 OK, 204 No ContentRetourneert { serialNumbers: [...], lastUpdated: "<tag>" } voor passen die zijn gewijzigd sinds ?passesUpdatedSince=.
GET/v1/passes/:passTypeIdentifier/:serialNumber200 OK, 304 Not Modified, 401 UnauthorizedGenereert en streamt de nieuwste ondertekende .pkpass-bundel wanneer het apparaat wordt geactiveerd door een APNs-push of handmatig omlaag vegen om te vernieuwen.
DELETE/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber200 OK, 401 UnauthorizedSchrijft het apparaat uit wanneer de pashouder de pas verwijdert uit Apple Wallet.
POST/v1/log200 OKOntvangt diagnostische { "logs": [...] }-arrays van iOS-apparaten als een .pkpass faalt bij validatie aan de clientzijde.

Bekijk verdere technische specificaties bij Apple Wallet Platform, Apple Wallet-certificaten en Apple VAS-protocol voor contactloos gebruik.

Gerelateerde product- en ontwikkelaarsdocs

Klaar om uw eerste kaartprogramma te lanceren?

Maak uw workspace aan, configureer uw sjabloon en test een echte kaart in Apple Wallet en Google Wallet voordat u opschaalt.