Notification Payload — bu nima, JSON tuzilishi va pars qilish

Notification Payload nima

Notification Payload (bildirishnoma payloadi) — bu server iOS qurilmasiga yetkazish uchun APNSga (Apple Push Notification Service) yuboradigan JSON obyektidir. Payload tizimga bildirishnomani ko'rsatish uchun zarur bo'lgan barcha ma'lumotlarni o'z ichiga oladi: sarlavha, matn, ovoz, badge va fon ishlovi uchun metama'lumotlar. Payload tuzilmasi Apple tomonidan qat'iy tartibga solingan va tizim tomonidan to'g'ri qayta ishlash uchun majburiy kalitlarni o'z ichiga oladi.

Push yetkazishda payloadning roli

Server HTTP/2 API APNS orqali push bildirishnomasini yuborganda, so'row avtorizatsiya sarlavhalari va JSON tanasini — payloadni o'z ichiga oladi. APNS tekshiradi payloadning to'g'riligini: agar JSON noto'g'ri bo'lsa yoki hajm chegarasidan oshsa, Apple serveri 400 Bad Request xatosini qaytaradi. Validatsiyadan so'ng APNS payloadni qurilmaga yetkazadi, u yerda iOS tizimi uni pars qiladi va bildirishnomani qanday qayta ishlashni aniqlaydi — bannerni ko'rsatish, fon vazifasini ishga tushirish yoki ovozni ijro etish.

Payload formatining evolyutsiyasi

APNS payload formati iOS 2 dagi oddiy matnli payloaddan zamonaviy versiyalarda ko'p komponentli JSON tuzilmasigacha evolyutsiya qilgan. iOS 10 mutable-content orqali media qo'shimchalari qo'llab-quvvatlashni olib keldi, iOS 12 thread-id orqali bildirishnomalarni guruhlashni qo'shdi, iOS 15 esa Live Activities uchun supports-live-activitiesni taqdim etdi. Bugungi kunda payload bildirishnomaning talab qilinadigan xatti-harakatiga qarab 15 tagacha turli kalitlarni o'z ichiga olishi mumkin.

APNS payload tuzilmasi: majburiy va ixtiyoriy kalitlar

Ildiz obyekt payload aps lug'atini va yuqori darajadagi ixtiyoriy maxsus maydonlarni o'z ichiga oladi. aps lug'ati yagona majburiy elementdir, ammo uning ichida bildirishnoma turiga qarab turli kalit kombinatsiyalari bo'lishi mumkin: alert, badge, sound, content-available, mutable-content, interruption-level va boshqalar.

Alert kaliti: satr va lug'at formati

Alert kaliti oddiy satr (bildirishnomaning tanasiga aylanadi) yoki title, subtitle, body maydonlari bo'lgan lug'at bo'lishi mumkin. Lug'at formati sarlavha va ostsarlavhani asosiy matndan alohida o'rnatishga imkon beradi. Mahalliylashtirilgan bildirishnomalar uchun ilovaning Localizable.strings fayliga havola qiluvchi title-loc-key, title-loc-args, loc-key, loc-args kalitlari ishlatiladi. Bu ma'lum bir tilda matnsiz payload yuborishga imkon beradi — ilova tarjimani o'zi qo'yadi.

Uzilishlarni boshqarish: interruption-level va relevance-score

iOS 15 dan boshlab Apple Focus Mode mexanizmini qo'shdi, bu dasturchidan bildirishnomaning uzilish darajasini ko'rsatishni talab qiladi. interruption-level quyidagi qiymatlarni qabul qiladi: passive (ovozsiz, ekranni uyg'otmasdan), active (standart xatti-harakat), time-sensitive (fokusni yorib o'tadi, maxsus ruxsat talab qiladi) va critical (tibbiy/favqulodda vaziyatlar). relevance-score (0–1) kaliti Focus tizimiga bir kategoriya ichidagi bildirishnomalarni tartiblashda yordam beradi.

thread-id orqali bildirishnomalarni guruhlash

thread-id kaliti bildirishnomalarni Notification Centerda guruhlarga birlashtiradi. Barcha bildirishnomalar bir xil thread-id bilan bitta guruh sifatida ko'rsatiladi, foydalanuvchi uni kengaytirishi mumkin. Bu, ayniqsa, xabar almashish ilovalari uchun foydali, bunda bir kontaktning xabarlari birgalikda guruhlanadi yoki bir turdagi ko'p bildirishnoma yuboradigan ilovalar uchun.

Maxsus maydonlar va ma'lumot uzatish

Maxsus maydonlar — bu dasturchi qurilmaga qo'shimcha ma'lumot uzatish uchun aps lug'atidan tashqarida qo'shadigan har qanday kalitlardir. Server ularni payloadning ildiz JSON obyektiga qo'shadi va ilova ularni UNNotificationContentdagi userInfo orqali oladi. Maxsus maydonlar pars qilishda ziddiyatlarning oldini olish uchun aps kalit nomlarini takrorlamasligi kerak.

Maxsus ma'lumotlarga cheklovlar

Asosiy cheklov — payloadning umumiy hajmi 4096 baytdan oshmasligi kerak. Maxsus maydonlar bu chegara uchun majburiy aps kalitlari bilan raqobatlashadi, shuning uchun uzatiladigan ma'lumotlar hajmini minimallashtirish muhim. Qisqa kalit nomlaridan foydalaning (masalan, 'uid' o'rniga 'user-id'), katta JSON tuzilmalaridan qoching va to'liq ma'lumot obyektlari o'rniga faqat identifikatorlarni uzating.

Maxsus maydonlarning xavfsizligi va validatsiyasi

Maxsus maydonlar serverdan keladi va tekshirilmasdan ishonilmasligi kerak. Har doim validatsiya qiling pars qilishda maxsus maydonlarning turlari va qiymatlarini: kalit mavjudligini optional binding orqali tekshiring, kutilgan turga as? String/Int/Dictionary bilan o'zgartiring va qiymat yo'qligi holatini boshqaring. Payload ma'lumotlari uchun hech qachon force unwrap (!) ishlatmang — server noto'g'ri ma'lumot yuborishi mumkin va ilova crash bo'ladi.

{
    "aps": {
        "alert": {
            "title": "Yangi xabar",
            "body": "Salom! Qalaysiz?"
        },
        "badge": 5,
        "sound": "default",
        "category": "message",
        "thread-id": "chat_4521",
        "mutable-content": 1
    },
    "sender-id": "user_789",
    "chat-id": "chat_4521",
    "message-type": "text",
    "image-url": "https://cdn.example.com/img.jpg"
}

Maxsus maydonlarni nomlash bo'yicha tavsiyalar

Loyihaning barcha payloadlarida yagona nomlash uslubidan foydalaning. kebab-case (message-type) yoki camelCase (messageType) — ikkala yondashuv ham maqbul, ammo loyiha doirasida bittasiga rioya qilish muhim. Uzoq nomlardan qoching: 'uid' o'rniga 'user-identifier', 'img' o'rniga 'profile-image-url'. Kalit nomidagi har bir belgi 4096 chegarasidan bir baytdir.

Turli bildirishnoma turlari uchun payload misollari

Turli stsenariylar push bildirishnomalari payloadda turli kalit kombinatsiyalarini talab qiladi. Bir nechta tipik misollarni ko'rib chiqamiz: oddiy matnli bildirishnoma, mahalliylashtirish bilan bildirishnoma, Silent Push va media qo'shimchasi bilan Rich Notification.

Oddiy matnli bildirishnoma

Matn va ovoz bilan asosiy payload — foydalanuvchiga bildirishnomani ko'rsatish uchun minimal konfiguratsiya. Satr sifatida alert qisqa xabar beradi, sound default standart tizim ovozini ijro etadi. Badge ixtiyoriy va ikonkada hisoblagichni o'rnatadi. category va thread-id guruhlash va interaktivlik uchun qo'shiladi.

{
    "aps": {
        "alert": "Eslatma: uchrashuv 15 daqiqadan so'ng",
        "badge": 3,
        "sound": "default"
    }
}

Mahalliylashtirish bilan bildirishnoma

Turli tillardagi qurilmalarga yuborish uchun qat'iy matn o'rniga mahalliylashtirish kalitlaridan foydalaning. title-loc-key ilovaning Localizable.strings faylidagi kalitga havola qiladi, title-loc-args esa argumentlarni almashtiradi. Bu barcha qurilmalarga bitta payload yuborishga imkon beradi va ilova matnni kerakli tilda ko'rsatadi.

{
    "aps": {
        "alert": {
            "title-loc-key": "NEW_MESSAGE_TITLE",
            "title-loc-args": ["Anna"],
            "loc-key": "NEW_MESSAGE_BODY",
            "loc-args": ["Salom!"]
        },
        "sound": "message.caf"
    }
}

Fon sinxronizatsiyasi bilan Silent Push

Bildirishnomani ko'rsatmasdan fon sinxronizatsiyasi uchun content-available: 1 va alertning yo'qligi ishlatiladi. Maxsus maydonlar operatsiya turini va qayta ishlash uchun ma'lumotlarni ko'rsatadi. Tizim ilovani fonda faollashtiradi, didReceiveRemoteNotification ni fetchCompletionHandler bilan chaqiradi va ilova sinxronizatsiyani amalga oshiradi.

{
    "aps": {
        "content-available": 1
    },
    "sync-type": "invalidate-cache",
    "timestamp": "2026-07-03T12:00:00Z"
}

Rasm bilan Rich Notification

Media qo'shimchasini ko'rsatish uchun Service Extensionni faollashtirish uchun mutable-content: 1 va maxsus maydonda rasm URLi talab qilinadi. mutable-content: 1 tizimga UNNotificationServiceExtensionni ishga tushirishni bildiradi, u URLdan rasmni yuklab oladi va UNNotificationAttachment sifatida qo'shadi. category harakat tugmalarini ko'rsatish uchun ro'yxatdan o'tgan kategoriyani ko'rsatadi.

{
    "aps": {
        "alert": {
            "title": "Yangi mahsulot",
            "body": "Yangi kolleksiyani ko'ring"
        },
        "category": "product",
        "mutable-content": 1
    },
    "media-url": "https://cdn.example.com/product.jpg"
}

Ilovada payloadni qayta ishlash va pars qilish

UNNotificationContent.userInfo tizim tomonidan qayta ishlanganidan so'ng olingan payloadning to'liq lug'atini o'z ichiga oladi. Ilova payloadga UNUserNotificationCenter delegatida bildirishnomani qabul qilganda (oldingi planda), bildirishnomani bosganda, shuningdek Service Extension va Content Extensionda kiradi. Maxsus ma'lumotlarni olish va keyingi harakatlarni aniqlash uchun to'g'ri pars qilish majburiydir.

Bildirishnomani bosganda AppDelegate da pars qilish

Foydalanuvchi bildirishnomani bosganda, tizim UNUserNotificationCenterDelegate da didReceive response metodini chaqiradi. response.notification.request.content.userInfo ichida to'liq payload mavjud. Dasturchi maxsus maydonlarni chiqaradi, harakat turini aniqlaydi (masalan, chatni ochish, mahsulotga o'tish) va ilovada tegishli navigatsiyani chaqiradi.

func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    didReceive response: UNNotificationResponse,
    withCompletionHandler completionHandler: @escaping () -> Void
) {
    let userInfo = response.notification
        .request.content.userInfo

    guard let chatId = userInfo["chat-id"] as? String
    else {
        completionHandler()
        return
    }

    let messageType = userInfo["message-type"]
        as? String ?? "text"

    NavigationRouter.shared.navigate(
        to: .chat(chatId: chatId,
                  messageType: messageType))
    completionHandler()
}

Service Extension da payload validatsiyasi

Service Extension bildirishnoma ko'rsatilishidan oldin payloadni oladi va uni o'zgartirishi mumkin. Payload validatsiyasi didReceive dagi birinchi qadamdir: majburiy maxsus maydonlarning mavjudligini, qo'shimchalar uchun URLning to'g'riligini va ma'lumot turini tekshiring. Agar payload noto'g'ri bo'lsa, darhol completion handlerni asl kontent bilan chaqiring, foydasiz ishlovga vaqt sarflamang.

Payloadlarni loglash va monitoring qilish

Ishlab chiqarishda push bildirishnomalarini tuzatish uchun payloadlarni tuzilgan loglashdan foydalaning. OSLog payloadni 'notifications' kategoriyasi va debug darajasi bilan loglashga imkon beradi. Server tomonda APNS javoblarini kuzating: muvaffaqiyatli javob yuborilgan payload bilan moslashtirish uchun apns-id ni o'z ichiga oladi, 400 xatosi esa noto'g'ri JSON yoki hajm oshib ketishini ko'rsatadi.