Інтеграція Apple Wallet для посадкових талонів у мобільному додатку

Інтеграція Apple Wallet для посадочних талонів в мобільних додатках

Посадочний талон у Apple Wallet — це архів типу boardingPass .pkpass з жорсткими вимогами до полів: transitType є обов'язковим, а структура primaryFields/auxiliaryFields впливає на те, що користувачі бачать на екрані блокування. Помилка у transitType або відсутність обов'язкових полів призведе до того, що Apple Wallet відобразить повідомлення "Invalid Pass Format".

Структура посадочного талону

{
  "formatVersion": 1,
  "passTypeIdentifier": "pass.com.yourairline.boarding",
  "serialNumber": "FLIGHT-SU123-20240615-IVANOV",
  "teamIdentifier": "ABCDE12345",
  "organizationName": "YourAirline",
  "description": "Посадочний талон SU 123",
  "foregroundColor": "rgb(255,255,255)",
  "backgroundColor": "rgb(0,60,130)",
  "boardingPass": {
    "transitType": "PKTransitTypeAir",
    "primaryFields": [
      { "key": "origin", "value": "SVO", "label": "Звідки" },
      { "key": "destination", "value": "LED", "label": "Куди" }
    ],
    "auxiliaryFields": [
      { "key": "flight", "value": "SU 123", "label": "Рейс" },
      { "key": "seat", "value": "14A", "label": "Місце" },
      { "key": "date", "value": "2024-06-15T07:30+03:00", "label": "Вильт",
        "dateStyle": "PKDateStyleShort", "timeStyle": "PKDateStyleShort" }
    ],
    "backFields": [
      { "key": "terms", "label": "Умови", "value": "Багаж 23 кг включено" }
    ],
    "barcode": {
      "message": "M1IVANOV/IVAN       ABCDEF SVO LED SU 0123 165Y014A0047 100",
      "format": "PKBarcodeFormatAztec",
      "messageEncoding": "iso-8859-1"
    }
  },
  "relevantDate": "2024-06-15T07:00+03:00"
}

Значення transitType: PKTransitTypeAir, PKTransitTypeTrain, PKTransitTypeBus, PKTransitTypeBoat, PKTransitTypeGeneric. Тип впливає на значок транспорту в заголовку паса.

Для авіації формат штрих-кода — PKBarcodeFormatAztec (стандарт IATA 2D Barcode). QR-коди також працюють, але коди Aztec читаються швидше при поганому освітленні.

relevantDate та геолокація

relevantDate відображає пас на екрані блокування за 15–30 хвилин до подіїї. Для аеропортів додайте locations:

"locations": [
  {
    "latitude": 55.9729,
    "longitude": 37.4146,
    "relevantText": "Реєстрація на рейс SU 123"
  }
]

Wallet сповістить користувачів, коли вони знаходяться біля аеропорту.

Динамічні поля: оновлення статусу рейсу в реальному часі

Основна потреба авіакомпаній — оновлювати поля в реальному часі. Wallet підтримує це через APN push:

1. Коли пас додається, пристрій реєструється через POST /v1/devices/{deviceLibraryIdentifier}/registrations/{passTypeIdentifier}/{serialNumber}
2. Коли дані змінюються (затримка рейсу, зміна воріт), сервер надсилає push до pushToken з запиту реєстрації
3. Пристрій запитує оновлений .pkpass та замінює старий

Payload APN push для Wallet мінімальний:

{
  "aps": {}
}

Порожний об'єкт aps говорить Wallet робити це. Текст сповіщення не потрібен.

Серверна генерація та підпис

Архів будується "на льоту" для кожного пасажира. Кожен пас є унікальним: serialNumber повинен ідентифікувати конкретний рейс та пасажира. Після зміни будь-якого файлу в архіві перерахуйте manifest.json та перегенеруйте signature.

На Node.js використовуйте passkit-generator:

import { PKPass } from "passkit-generator";

const pass = await PKPass.from({
  model: "./models/boarding-pass.pass",
  certificates: {
    wwdr: fs.readFileSync("./certs/wwdr.pem"),
    signerCert: fs.readFileSync("./certs/pass.pem"),
    signerKey: fs.readFileSync("./certs/pass.key"),
  },
  overrides: {
    serialNumber: `FLIGHT-SU123-${passengerId}`,
    description: `Посадочний талон ${flightNumber}`,
  },
});

pass.setBarcodes({
  message: bcbpData,
  format: "PKBarcodeFormatAztec",
  messageEncoding": "iso-8859-1",
});

const buffer = pass.getAsBuffer();

Тривалість

2–3 дні на серверну генерацію та підпис, реєстрацію пристроїв та push-оновлення статусу рейсу. Вартість розраховується індивідуально.