PushKit — какво е, рамка за VoIP известия в iOS

Какво е PushKit

PushKit е рамка на Apple, представена в iOS 8, която осигурява доставяне на push известия с ниска латентност за VoIP приложения. За разлика от стандартния APNs (Apple Push Notification service), PushKit позволява на приложението да се събуди на заден план при получаване на входящо повикване, без да показва известие на потребителя. Това е критично за гласови и видео приложения — потребителят получава повикването незабавно, дори ако приложението е затворено. Според Apple WWDC 2024, PushKit обработва над 2 милиарда VoIP известия дневно по целия свят.

Как работи PushKit

Механизмът на работа се основава на директна връзка между устройството и push сървъра на Apple, заобикаляйки стандартния канал за известия. Когато сървърът на приложението изпрати VoIP известие, то преминава през специален PushKit сървър и се доставя на устройството с максимален приоритет. Системата събужда приложението на заден план и извиква делегатския метод pushRegistry:didReceiveIncomingPushWithPayload:forType:. Приложението получава полезния товар, обработва повикването и извиква completion handler за потвърждение. Целият цикъл от изпращане до обработка отнема не повече от 5 секунди, което е потвърдено от спецификацията на Apple.

Разлики между PushKit и APNs

Основната разлика между PushKit и APNs се състои в механизма на доставяне и обработка. APNs използва стандартен канал за известия с показване на банер, звук или значка, докато PushKit доставя данни директно в приложението без визуално известие. По-долу е дадена сравнителна таблица на ключовите характеристики.

PushKit също не поддържа богати медийни прикачени файлове и не може да се използва за обикновени маркетингови известия. Apple строго контролира използването на PushKit — приложението трябва да има ясна VoIP функционалност, в противен случай ще бъде отхвърлено при преглед. APNs остава универсално решение за всички останали сценарии.

Регистрация и получаване на VoIP известия

За да използва PushKit, приложението трябва да се регистрира чрез PKPushRegistry с тип pushType .voIP. Регистрацията се извършва веднъж при първото стартиране, след което системата генерира уникален push токен и го предава чрез делегата. Този токен се изпраща на сървъра на приложението за последващо изпращане на VoIP известия. По-долу е даден пример за регистрация на PushKit и получаване на токен в Swift.

Настройка на PushKit регистрация

import PushKit

let registry = PKPushRegistry(queue: DispatchQueue.main)
registry.delegate = self
registry.desiredPushTypes = [.voIP]

// MARK: - PKPushRegistryDelegate
func pushRegistry(
    _ registry: PKPushRegistry,
    didUpdate pushCredentials: PKPushCredentials,
    for type: PKPushType
) {
    let deviceToken = pushCredentials.token
        .map { String.format("%02x", $0) }
        .joined()
    sendVoIPTokenToServer(deviceToken)
}

След извикване на desiredPushTypes с PKPushType.voIP, системата автоматично иска разрешение за получаване на VoIP известия. В метода pushRegistry:didUpdatePushCredentials:forType: приложението получава устройствен токен като Data, който се преобразува в hex-низ и се изпраща на сървъра. Токенът е уникален за всяко устройство и се променя при преинсталиране на приложението — сървърът трябва да обработва актуализация на токена.

Получаване на входящо известие

func pushRegistry(
    _ registry: PKPushRegistry,
    didReceiveIncomingPushWith payload: PKPushPayload,
    for type: PKPushType,
    completion: @escaping VoidBlock
) {
    guard let caller = payload.dictionaryPayload["caller"] as? String else {
        completion()
        return
    }

    let update = CXCallUpdate()
    update.remoteHandle = CXHandle(type: .generic, value: caller)

    provider.reportNewIncomingCall(
        with: UUID(),
        update: update,
        completion: { error in
            if let error = error {
                print("Call error: \(error)")
            }
            completion()
        }
    )
}

В метода didReceiveIncomingPushWith приложението получава полезния товар с данни за повикването. След извличане на информацията за обаждащия се се създава CXCallUpdate от рамката CallKit за показване на екрана за входящо повикване. Важно е да се извика completion handler след завършване на обработката — в противен случай системата може принудително да прекрати процеса на приложението поради изтичане на време. Максималното време за обработка е 30 секунди, след което iOS счита известието за необработено.

Обработка на входящи повиквания с CallKit

PushKit е тясно интегриран с CallKit — рамката за показване на системния интерфейс за повиквания на iOS. Когато приложението получи VoIP известие чрез PushKit, то трябва да създаде CXProvider и CXCallController за управление на повикването. CallKit автоматично показва екрана за входящо повикване на заключения екран, дори ако приложението е минимизирано. По-долу е даден пример за конфигуриране на доставчик на CallKit.

let config = CXProviderConfiguration(localizedName: "MyApp")
config.supportsVideo = true
config.maximumCallGroups = 1
config.maximumCallsPerCallGroup = 1
config.supportedHandleTypes = [.phoneNumber, .generic]

let provider = CXProvider(configuration: config)
provider.setDelegate(self, queue: nil)

CXProviderConfiguration определя външния вид и поведението на екрана за повикване — името на приложението, поддръжката на видео, броя на едновременните повиквания. Интеграцията на PushKit с CallKit е задължителна за VoIP приложения: без нея системата няма да покаже екрана за входящо повикване и потребителят ще пропусне повикването. Apple изисква използването на CallKit за всички приложения, които използват PushKit.

Функции и ограничения

Използването на PushKit налага редица строги ограничения, установени от Apple. Рамката може да се използва само за VoIP функционалност — всякакви опити за изпращане на маркетингови известия чрез PushKit ще доведат до блокиране на приложението. Размерът на полезния товар не трябва да надвишава 4 KB и може да съдържа само JSON данни без прикачени файлове. От iOS 13 нататък Apple въведе ограничение на честотата на изпращане на VoIP известия — не повече от едно известие на минута на устройство. Сървърът трябва да спазва това ограничение, в противен случай известията ще бъдат отхвърлени от системата. PushKit също не работи на iOS симулатор — тестването е възможно само на физическо устройство.

Структура на полезния товар на PushKit

Полезният товар на VoIP известие представлява JSON речник с персонализирани данни за повикването. За разлика от APNs, PushKit не поддържа стандартните полета alert, badge и sound — всички данни се определят от разработчика. Типичната структура включва идентификатор на обаждащия се (caller), тип на повикването (voice или video), идентификатор на стая или сесия и времеви печат. Размерът на всяко поле трябва да бъде минимален, за да се спести място в лимита от 4 KB. Apple препоръчва да се включват в полезния товар само данните, необходими за показване на екрана за входящо повикване на заключения екран, а останалата информация (аватар, история на разговори) да се зарежда след като потребителят отговори чрез отделна мрежова заявка. Пример за минимален полезен товар: { „caller”: „Анна”, „caller_id”: „+79161234567”, „type”: „audio”, „room”: „uuid-room-1234”, „ts”: 1718534400 }. Всички ключове в полезния товар трябва да бъдат кратки, недвусмислени и документирани от страна на сървъра за съвместимост между версиите на приложението.

Обработка на грешки и повторни опити

При работа с PushKit трябва да се предвиди обработка на грешки при доставяне и загуба на връзка. Ако устройството е в офлайн режим или е изключено от мрежата, VoIP известието няма да бъде доставено — PushKit не поддържа съхранение и повторно изпращане, за разлика от APNs, които съхраняват известието до 24 часа за повторен опит. Сървърът трябва сам да проследява недоставените известия и да повтаря опита след възстановяване на връзката. За целта се използва механизмът push kit feedback service — той връща списък с недоставени известия с посочване на причината за грешката. Препоръчва се да се настрои мониторинг на успеваемостта на доставяне на VoIP известия чрез сървърна аналитика и да се уведомява разработчикът, когато процентът на успешно доставени известия падне под 95%. Системата PushKit гарантира доставяне само при активна интернет връзка на устройството — при липса на такава известието се губи безвъзвратно, което е критично да се вземе предвид при проектирането на надеждна система за VoIP повиквания с гарантирано доставяне.