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

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

Купон в Apple Wallet — это coupon-тип .pkpass. По структуре похож на storeCard, но тип coupon даёт особый визуальный стиль: перфорированный край снизу карточки. Именно это делает купон визуально купоном, а не обычной картой.

Структура 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. Отправляет push APN → устройство скачивает обновлённый .pkpass с voided: true

Между шагом 4 и 5 может быть задержка в 10–30 секунд — это нормально. Главное, что проверка происходит на сервере, а не на устройстве.

Персонализация и массовая рассылка

Каждый купон — уникальный .pkpass под конкретного пользователя. Серверный генератор получает userId, создаёт архив на лету, подписывает и отдаёт ссылку на скачивание. Ссылку можно встроить в email или push-уведомление.

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

При открытии на iOS Safari предложит «Добавить в Wallet» автоматически, если MIME-type ответа — 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. Стоимость рассчитывается индивидуально.