Генерація та оновлення Wallet Pass (pkpass) на сервері мобільного додатку

Генерація та оновлення Wallet Pass (pkpass) на сервері для мобільних додатків

Файл .pkpass — це ZIP-архів з JSON-описом, зображеннями та підписом. Apple Wallet приймає лише пасси, підписані сертифікатом з Apple Developer Program. Це серверна операція: сертифікат зберігається на бекенді, клієнт отримує готовий файл .pkpass та відкриває його.

Структура pkpass

pass.pkpass/
├── pass.json          # опис паса
├── manifest.json      # хеші SHA1 усіх файлів
├── signature          # підпис PKCS#7 manifest.json
├── icon.png           # 29x29 pt
├── [email protected]        # 58x58 pt
├── [email protected]        # 87x87 pt
├── logo.png           # до 160x50 pt
└── background.png     # опціонально, тільки для boardingPass

pass.json: ключові поля

{
  "formatVersion": 1,
  "passTypeIdentifier": "pass.com.yourcompany.membercard",
  "serialNumber": "user-12345-2024",
  "teamIdentifier": "ABCD1234EF",
  "organizationName": "Your Company",
  "description": "Карта члена",
  "foregroundColor": "rgb(255, 255, 255)",
  "backgroundColor": "rgb(15, 82, 186)",
  "storeCard": {
    "primaryFields": [
      {
        "key": "member_name",
        "label": "Член",
        "value": "Іван Петров"
      }
    ],
    "secondaryFields": [
      {
        "key": "points",
        "label": "Балів",
        "value": "1 250",
        "changeMessage": "Балів оновлено: %@"
      }
    ],
    "auxiliaryFields": [
      {
        "key": "tier",
        "label": "Статус",
        "value": "Gold"
      }
    ],
    "backFields": [
      {
        "key": "terms",
        "label": "Умови",
        "value": "Балів дійсні 12 місяців з моменту нарахування."
      }
    ]
  },
  "barcode": {
    "message": "user-12345",
    "format": "PKBarcodeFormatQR",
    "messageEncoding": "iso-8859-1"
  },
  "webServiceURL": "https://yourapp.com/wallet/",
  "authenticationToken": "vxwxd7J8AlNNFPS8k0a0FfUFtq0ewzV"
}

Поля webServiceURL + authenticationToken забезпечують механізм push-оновлень. Apple Wallet реєструє пристрій на вашому сервері та запитує оновлений пас при змінах.

Серверна генерація на Python

import hashlib
import json
import zipfile
import io
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.serialization import pkcs12
from cryptography.hazmat.backends import default_backend
from cryptography import x509
from cryptography.hazmat.primitives.serialization import pkcs7

def generate_pkpass(pass_data: dict, images: dict[str, bytes]) -> bytes:
    # 1. Сериализуємо pass.json
    pass_json = json.dumps(pass_data, ensure_ascii=False).encode('utf-8')

    # 2. Будуємо manifest — SHA1 усіх файлів
    manifest = {}
    files = {"pass.json": pass_json, **images}
    for filename, content in files.items():
        manifest[filename] = hashlib.sha1(content).hexdigest()

    manifest_json = json.dumps(manifest).encode('utf-8')

    # 3. Підписуємо manifest PKCS#7 detached signature
    with open("pass-cert.p12", "rb") as f:
        p12_data = f.read()

    private_key, certificate, chain = pkcs12.load_key_and_certificates(
        p12_data, b"p12_password", default_backend()
    )

    # Завантажуємо Apple WWDR проміжний сертифікат
    with open("AppleWWDRCA.cer", "rb") as f:
        wwdr_cert = x509.load_der_x509_certificate(f.read(), default_backend())

    signature = pkcs7.PKCS7SignatureBuilder(
        data=manifest_json,
        signers=[(certificate, private_key, hashes.SHA256())]
    ).add_certificate(wwdr_cert).sign(
        encoding=serialization.Encoding.DER,
        options=[pkcs7.PKCS7Options.DetachedSignature]
    )

    # 4. Упаковуємо в ZIP
    buffer = io.BytesIO()
    with zipfile.ZipFile(buffer, 'w', zipfile.ZIP_DEFLATED) as zf:
        zf.writestr("pass.json", pass_json)
        zf.writestr("manifest.json", manifest_json)
        zf.writestr("signature", signature)
        for filename, content in images.items():
            zf.writestr(filename, content)

    return buffer.getvalue()

Сертифікат Pass Type ID створюється у Apple Developer Portal → Certificates, Identifiers & Profiles → Identifiers → Pass Type IDs.

Endpoint для завантаження

@app.get("/wallet/pass/{user_id}")
async def download_pass(user_id: str, token: str = Query(...)):
    user = db.get_user(user_id)
    if not verify_token(user, token):
        raise HTTPException(403)

    pass_data = build_pass_json(user)
    images = load_pass_images()
    pkpass_bytes = generate_pkpass(pass_data, images)

    return Response(
        content=pkpass_bytes,
        media_type="application/vnd.apple.pkpass",
        headers={"Content-Disposition": f"attachment; filename={user_id}.pkpass"}
    )

iOS: відкриття pkpass

import PassKit

func downloadAndAddPass(url: URL) {
    URLSession.shared.dataTask(with: url) { data, _, error in
        guard let data, error == nil else { return }

        do {
            let pass = try PKPass(data: data)
            DispatchQueue.main.async {
                let vc = PKAddPassesViewController(pass: pass)!
                self.present(vc, animated: true)
            }
        } catch {
            print("Invalid pass: \(error)")
        }
    }.resume()
}

Push-оновлення через APNs

При змінах даних (балів видано, статус змінено), сервер:

1. Отримує pushToken пристрою з бази даних (Apple Wallet зареєстрував його при додаванні паса)
2. Надсилає пустий push через APNs на passkit production endpoint
3. Wallet робить GET /wallet/v1/passes/{passTypeIdentifier}/{serialNumber} з Bearer-токеном

Відповідь — оновлений .pkpass. Wallet застосовує зміни та відображає changeMessage якщо встановлено у pass.json.

Тривалість

2–3 дні. Серверна генерація з підписом, endpoint завантаження, iOS-інтеграція — 2 дні. Push-оновлення через APNs — додатково 0,5–1 день. Вартість розраховується індивідуально.