Как выпускать персональные Wallet-карты через API

Wallet pass API позволяет вашему бэкенду выпускать персональные Wallet-карты для каждого клиента — с его именем, балансом, штрихкодом и локациями — и обновлять их, как только меняются данные. Вы 1 раз создаёте шаблон, передаёте персональные значения для каждого пользователя и получаете ссылку на установку для Apple Wallet или ссылку на сохранение для Google Wallet.

API нужен не каждой команде. Примеры сделаны на Wallet passes API от Pushwoosh: каждая карта привязана к User ID, который управляет и вашими push, email и сценариями. Для инженерной команды, которая выбирает инфраструктуру, это 1 API и 1 профиль на iOS и Android, а не отдельная интеграция под каждую платформу.

Когда API выигрывает у конструктора

Конструктор — правильный инструмент, чтобы спроектировать карту и сделать небольшую или разовую отправку. API берёт работу на себя, когда карты зависят от данных в ваших собственных системах.

Прежде чем писать код, посмотрите на последнюю колонку. Если триггер — действие клиента, которое Pushwoosh уже отслеживает, шаг Issue Wallet Pass (выпуск Wallet-карты) в Customer Journey часто делает собственный код ненужным.

Шаблоны и персональные значения

Схема одинакова на обеих платформах. Шаблон хранит макет, брендинг и структуру полей. Персональные значения заполняют его в момент выпуска.

Персональные значения — то, что отличается от клиента к клиенту: имя, номер участника, баллы, уровень, значение штрихкода, срок действия, ближайший магазин. Всё остальное берётся из шаблона, поэтому изменение дизайна применяется к каждой новой карте, не затрагивая вашу интеграцию.

Персональные значения — это персональные данные. Если среди ваших клиентов есть жители ЕС, учитывайте GDPR и заранее решите, какие поля действительно нужны на карте.

В сценарии шаг Issue Wallet Pass принимает кампании карт Apple и Google (apple_campaign_id, google_campaign_id) и personal_values для заполнения. 1 шаг может выпустить обе версии на один и тот же User ID.

Как это работает в Apple Wallet

Всё, что умеет конструктор карт Apple, доступно и в Apple Wallet PassKit API: создание, обновление, список, загрузка и удаление карт.

Типичная интеграция состоит из 4 шагов.

Нужен сертификат Pass Type ID (.p12) на каждое приложение и аккаунт Apple Developer ($99 в год). Настройка описана в документации по конфигурации iOS Wallet pass.

Как это работает в Google Wallet

Google Wallet API покрывает тот же жизненный цикл для карт Google.

Нужен Issuer ID из Google Pay & Wallet Console, а сервисный аккаунт Pushwoosh должен быть приглашён в вашего издателя (issuer). Настраивается 1 раз на каждое приложение. Подробности — в документации по конфигурации Google Wallet.

Если ваше приложение работает на глобальном рынке, где пользователей iOS и Android примерно поровну, закладывайте обе интеграции в план с самого начала, а не добавляйте вторую платформу потом.

Обновления в масштабе

Именно на обновлениях API окупается. Система учёта баллов или бронирования может обновить карту в момент, когда меняется значение, и карта в Wallet клиента совпадает с вашим источником истины. Для e-commerce это баланс бонусов после каждого заказа, для FinTech — статус карты или кешбэк сразу после транзакции.

3 правила помогают безопасно проводить большие обновления:

• Начинайте с текущей карты. Обновление Apple принимает объект карты целиком, поэтому получите карту и поменяйте только изменившиеся значения. Обновление Google частично изменяет (patch) объект.
• Решайте об уведомлениях для каждого поля. В Apple Wallet уведомление на экране блокировки показывают только поля с сообщением об изменении. В Google notifyOnUpdate просит Google прислать собственное уведомление, которое срабатывает только для карт лояльности, билетов на мероприятия и посадочных талонов, максимум 3 на карту за 24 часа. notifyMessage отправляет ваш собственный текст уведомления Android для любого типа карты.
• Уведомляйте только о самой карте. Apple и Google разрешают уведомления о карте, а не промо.

Примеры кода

Оба API используют базовый URL https://apple-passkit.svc-nue.pushwoosh.com и ваш токен доступа к Pushwoosh API в заголовке Authorization: Token <api-token>. Тела запросов ниже — примеры из справочника API.

Создать карту Apple Wallet: POST /api/pass/create. Ответ возвращает serialNumber карты.

{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "description": "Acme loyalty card",
    "logoText": "Acme",
    "backgroundColor": "rgb(60, 65, 76)",
    "foregroundColor": "rgb(255, 255, 255)",
    "labelColor": "rgb(255, 255, 255)",
    "storeCard": {
      "primaryFields": [
        { "key": "balance", "label": "BALANCE", "value": "1200 pts" }
      ],
      "secondaryFields": [
        { "key": "member", "label": "MEMBER", "value": "Jane Doe" }
      ]
    },
    "barcodes": [
      {
        "format": "PKBarcodeFormatQR",
        "message": "1234567890",
        "messageEncoding": "iso-8859-1"
      }
    ]
  },
  "images": [
    { "imageType": "icon", "data": "<base64>", "contentType": "image/png" },
    { "imageType": "logo", "data": "<base64>", "contentType": "image/png" }
  ]
}

Создать карту Google Wallet: POST /api/google/pass/create. Ответ возвращает serialNumber и saveLink.

{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "hexBackgroundColor": "#3c414c",
    "logoUrl": "https://cdn.acme.com/logo.png",
    "loyalty": {
      "programName": "Acme Rewards",
      "accountName": "Jane Doe",
      "accountId": "1234567890",
      "pointsLabel": "Points",
      "pointsBalance": "1200",
      "rewardsTier": "Gold"
    },
    "barcode": {
      "format": "QR_CODE",
      "value": "1234567890"
    }
  }
}

Чтобы обновить карту, отправьте новое содержимое с серийным номером: POST /api/pass/update/{serialNumber} для Apple, POST /api/google/pass/update/{serialNumber} для Google.

Конструктор, API или сценарий: короткое правило

Конструктор — чтобы проектировать и тестировать. Шаг сценария — когда триггер уже есть в Pushwoosh как событие клиента, например регистрация или первая покупка. API — когда триггер или данные живут в вашем бэкенде.

Большинство команд в итоге используют все 3, и это нормально: конструктор для дизайна, сценарии для ключевых моментов жизненного цикла, API для баланса и статуса в реальном времени. Ошибка — заставлять 1 из них делать работу остальных.

Персонализируйте каждую карту в масштабе с Pushwoosh

Pushwoosh даёт визуальный конструктор, шаг сценария и API для нативных карт Apple Wallet и Google Wallet без отдельного поставщика карт посередине. Каждая карта использует тот же User ID, что и ваши push, in-app, email и SMS, поэтому 1 набор данных управляет всеми каналами. Платформа сертифицирована по SOC 2 Type 2 и ISO 27001:2022, соответствует GDPR, а дата-центры расположены в ЕС и США.

Персонализация в масштабе — это не больше шаблонов. Это 1 источник истины, который отражает каждая карта в каждом Wallet.

FAQ