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

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

Купон у Apple Wallet — це архів типу coupon .pkpass. Структурно схожий на storeCard, але тип coupon забезпечує особливий візуальний стиль: перфорований нижній край карточки. Це те, що робить купон візуально схожим на купон, а не просто на звичайну карту.

Структура купону

{
  "formatVersion": 1,
  "passTypeIdentifier": "pass.com.yourshop.coupon",
  "serialNumber": "COUPON-SUMMER2024-USER789",
  "teamIdentifier": "ABCDE12345",
  "organizationName": "YourShop",
  "description": "Скидка 20% на літню колекцію",
  "foregroundColor": "rgb(255,255,255)",
  "backgroundColor": "rgb(200,50,50)",
  "coupon": {
    "primaryFields": [
      { "key": "offer", "value": "−20%", "label": "Скидка" }
    ],
    "secondaryFields": [
      {
        "key": "expires",
        "value": "2024-08-31T23:59+03:00",
        "label": "Дійсний до",
        "dateStyle": "PKDateStyleShort",
        "timeStyle": "PKDateStyleNone"
      }
    ],
    "auxiliaryFields": [
      { "key": "conditions", "value": "При покупці від 3 000 ₽", "label": "Умови" }
    ],
    "barcode": {
      "message": "COUPON-SUMMER2024-USER789",
      "format": "PKBarcodeFormatCode128",
      "messageEncoding": "iso-8859-1"
    }
  },
  "expirationDate": "2024-08-31T23:59+03:00",
  "voided": false
}

Поле voided: true — Wallet візуально «зачеркує» купон та переміщує його в архів. Встановлюється через push-оновлення після погашення.

Погашення купону

Логіка погашення — повністю на сервері. QR/штрих-код містить serialNumber або унікальний токен. Касир сканує код, сервер:

1. Перевіряє serialNumber у базі даних
2. Впевняється, що купон не істік та не погашений
3. Застосовує скидку
4. Встановлює прапор used = true
5. Надсилає APN push → пристрій завантажує оновлений .pkpass з voided: true

Між кроком 4 та 5 може виникнути затримка 10–30 секунд — це нормально. Ключовий момент — перевірка відбувається на сервері, а не на пристрої.

Персоналізація та масова розповсюджування

Кожен купон — унікальний .pkpass для конкретного користувача. Серверний генератор отримує userId, створює архів "на льоту", підписує його та надає посилання для завантаження. Посилання можна вбудувати в email або push-сповіщення.

Формат посилання: https://api.yourshop.com/wallet/coupons/{token}.pkpass

При відкриванні на iOS Safari він автоматично запропонує "Додати до Wallet", якщо MIME-тип application/vnd.apple.pkpass.

Геотаргетинг

Купон можна прив'язати до точок продажу:

"locations": [
  { "latitude": 55.7512, "longitude": 37.6184, "relevantText": "Магазин на Тверській" },
  { "latitude": 59.9386, "longitude": 30.3141, "relevantText": "Магазин на Невському" }
]

Wallet відобразить сповіщення з relevantText на екрані блокування, коли користувач знаходиться біля будь-якої локації (~100 метрів). Максимум 10 локацій на один пас.

Масова розповсюджування: кілька купонів за один запит

Коли потрібно видати купони всім користувачам в сегменті — генератор повинен працювати в фоновому режимі. Синхронна генерація 10 000 файлів .pkpass заблокує API-сервер.

Правильний підхід: job-очередь. Запит POST /campaigns/{id}/distribute ставить задачу в очередь (Sidekiq, Celery, BullMQ), воркери генерують пассі партіями та записують посилання в базу. Користувачі отримують push з кнопкою "Додати до Wallet" — не відразу, а по мірі генерації.

Кожна генерація повинна використовувати новий serialNumber та новий authenticationToken у pass.json. Ніколи не розповсюджуйте однакові пасси різним користувачам — системи оновлень будуть конфліктувати.

Тривалість

1–3 дні: серверна генерація купонів, API погашення, push-інвалідація через voided. Вартість розраховується індивідуально.