PushKit — چیست، فریم‌ورک اعلان‌های VoIP در iOS

PushKit چیست

PushKit فریم‌ورکی از Apple است که در iOS 8 معرفی شد و تحویل اعلان‌های push با تأخیر کم را برای برنامه‌های VoIP فراهم می‌کند. برخلاف APNs استاندارد (Apple Push Notification service)، PushKit به برنامه اجازه می‌دهد هنگام دریافت تماس ورودی، بدون نمایش اعلان به کاربر، در پس‌زمینه بیدار شود. این برای برنامه‌های صوتی و تصویری حیاتی است — کاربر تماس را فوراً دریافت می‌کند، حتی اگر برنامه بسته باشد. طبق Apple WWDC 2024، PushKit روزانه بیش از ۲ میلیارد اعلان VoIP را در سراسر جهان پردازش می‌کند.

PushKit چگونه کار می‌کند

مکانیزم کار بر اتصال مستقیم بین دستگاه و سرور push Apple استوار است و از کانال استاندارد اعلان عبور می‌کند. وقتی سرور برنامه یک اعلان VoIP ارسال می‌کند، از سرور اختصاصی PushKit عبور کرده و با حداکثر اولویت به دستگاه تحویل داده می‌شود. سیستم برنامه را در پس‌زمینه بیدار می‌کند و متد delegate یعنی pushRegistry:didReceiveIncomingPushWithPayload:forType: را فراخوانی می‌کند. برنامه payload را دریافت می‌کند، تماس را پردازش کرده و برای تأیید، completion handler را فراخوانی می‌کند. کل چرخه از ارسال تا پردازش حداکثر ۵ ثانیه طول می‌کشد که توسط مشخصات Apple تأیید شده است.

تفاوت‌های PushKit و APNs

تفاوت اصلی بین PushKit و APNs در مکانیزم تحویل و پردازش است. APNs از کانال استاندارد اعلان با نمایش بنر، صدا یا نشان استفاده می‌کند، در حالی که PushKit داده‌ها را مستقیماً بدون اعلان بصری به برنامه تحویل می‌دهد. در زیر جدول مقایسه ویژگی‌های کلیدی آورده شده است.

PushKit همچنین از پیوست‌های رسانه‌ای غنی پشتیبانی نمی‌کند و نمی‌توان برای اعلان‌های بازاریابی معمولی استفاده کرد. Apple استفاده از PushKit را به شدت کنترل می‌کند — برنامه باید دارای قابلیت VoIP باشد، در غیر این صورت در بررسی رد می‌شود. APNs یک راه‌حل جهانی برای سایر سناریوها باقی می‌ماند.

ثبت‌نام و دریافت اعلان‌های VoIP

برای استفاده از PushKit، برنامه باید از طریق PKPushRegistry با نوع pushType .voIP ثبت‌نام کند. ثبت‌نام یک بار در اولین راه‌اندازی انجام می‌شود، پس از آن سیستم یک token push یکتا تولید کرده و از طریق delegate ارسال می‌کند. این token برای ارسال بعدی اعلان‌های VoIP به سرور برنامه فرستاده می‌شود. در زیر نمونه ثبت‌نام PushKit و دریافت token در 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: برنامه device token را به صورت Data دریافت می‌کند که به رشته hex تبدیل شده و به سرور ارسال می‌شود. Token برای هر دستگاه یکتا است و با نصب مجدد برنامه تغییر می‌کند — سرور باید به‌روزرسانی token را مدیریت کند.

دریافت اعلان ورودی

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 برنامه payload را با داده‌های تماس دریافت می‌کند. پس از استخراج اطلاعات تماس‌گیرنده، CXCallUpdate از فریم‌ورک CallKit برای نمایش صفحه تماس ورودی ایجاد می‌شود. فراخوانی completion handler پس از اتمام پردازش ضروری است — در غیر این صورت سیستم ممکن است به دلیل پایان مهلت، فرآیند برنامه را به اجبار خاتمه دهد. حداکثر زمان پردازش ۳۰ ثانیه است، پس از آن iOS اعلان را پردازش‌نشده در نظر می‌گیرد.

پردازش تماس‌های ورودی با CallKit

PushKit به طور نزدیک با CallKit ادغام شده است — فریم‌ورکی برای نمایش رابط سیستمی تماس‌ها در iOS. وقتی برنامه از طریق PushKit اعلان VoIP دریافت می‌کند، باید CXProvider و CXCallController را برای مدیریت تماس ایجاد کند. CallKit به طور خودکار صفحه تماس ورودی را روی lock screen نشان می‌دهد، حتی اگر برنامه کوچک شده باشد. در زیر نمونه تنظیمات provider 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 برای تمام برنامه‌های استفاده‌کننده از PushKit، استفاده از CallKit را الزامی می‌کند.

ویژگی‌ها و محدودیت‌ها

استفاده از PushKit مجموعه‌ای از محدودیت‌های سختگیرانه تعیین‌شده توسط Apple را اعمال می‌کند. فریم‌ورک فقط برای قابلیت VoIP قابل استفاده است — هرگونه تلاش برای ارسال اعلان‌های بازاریابی از طریق PushKit منجر به مسدود شدن برنامه می‌شود. اندازه payload نباید از ۴ کیلوبایت تجاوز کند و فقط می‌تواند حاوی داده‌های JSON بدون پیوست باشد. از iOS 13 به بعد، Apple محدودیتی بر روی تعداد ارسال اعلان‌های VoIP اعمال کرده است — حداکثر یک اعلان در دقیقه برای هر دستگاه. سرور باید این محدودیت را رعایت کند، در غیر این صورت اعلان‌ها توسط سیستم رد خواهند شد. PushKit همچنین روی شبیه‌ساز iOS کار نمی‌کند — آزمایش فقط روی دستگاه فیزیکی امکان‌پذیر است.

ساختار payload PushKit

payload اعلان VoIP یک دیکشنری JSON با داده‌های سفارشی تماس است. برخلاف APNs، PushKit از فیلدهای استاندارد alert، badge و sound پشتیبانی نمی‌کند — همه داده‌ها توسط توسعه‌دهنده تعریف می‌شوند. ساختار معمولی شامل شناسه تماس‌گیرنده (caller)، نوع تماس (voice یا video)، شناسه اتاق یا جلسه و مهر زمانی است. اندازه هر فیلد باید حداقل باشد تا در محدوده ۴ کیلوبایت صرفه‌جویی شود. Apple توصیه می‌کند فقط داده‌های لازم برای نمایش صفحه تماس ورودی روی lock screen را در payload قرار دهید و بقیه اطلاعات (آواتار، تاریخچه پیام‌ها) را پس از پاسخ کاربر با یک درخواست شبکه جداگانه بارگیری کنید. نمونه payload حداقلی: { «caller»: «آنا», «caller_id»: «+79161234567», «type»: «audio», «room»: «uuid-room-1234», «ts»: 1718534400 }. همه کلیدهای payload باید کوتاه، بدون ابهام و برای سازگاری بین نسخه‌های برنامه در سمت سرور مستند شده باشند.

مدیریت خطا و تلاش مجدد

هنگام کار با PushKit باید مدیریت خطاهای تحویل و قطع اتصال را پیش‌بینی کرد. اگر دستگاه در حالت آفلاین یا قطع از شبکه باشد، اعلان VoIP تحویل داده نخواهد شد — PushKit برخلاف APNs که اعلان را تا ۲۴ ساعت برای تلاش مجدد ذخیره می‌کند، از ذخیره و ارسال مجدد پشتیبانی نمی‌کند. سرور باید خود اعلان‌های تحویل‌نشده را ردیابی کرده و پس از برقراری اتصال دوباره تلاش کند. برای این منظور از مکانیزم push kit feedback service استفاده می‌شود که لیست اعلان‌های تحویل‌نشده را با ذکر دلیل خطا برمی‌گرداند. توصیه می‌شود نظارت بر موفقیت تحویل اعلان‌های VoIP را از طریق تحلیل سرور راه‌اندازی کرده و در صورت کاهش درصد تحویل موفق به زیر ۹۵٪ به توسعه‌دهنده اطلاع دهید. سیستم PushKit تنها در صورت وجود اتصال اینترنت فعال روی دستگاه، تحویل را تضمین می‌کند — در صورت عدم وجود اتصال، اعلان برای همیشه از دست می‌رود، که در طراحی یک سیستم تماس VoIP قابل اعتماد با تحویل تضمینی باید در نظر گرفته شود.