Notification Payload — bu nədir, JSON strukturu və pars etmə

Notification Payload nədir

Notification Payload (bildiriş payload-u) — serverin iOS cihazına çatdırılmaq üçün APNS-ə (Apple Push Notification Service) göndərdiyi JSON obyektidir. Payload sistemin bildirişi göstərməsi üçün lazım olan bütün məlumatları ehtiva edir: başlıq, mətn, səs, badge və fon emalı üçün metadata. Payload strukturu Apple tərəfindən ciddi şəkildə tənzimlənir və sistem tərəfindən düzgün işlənməsi üçün məcburi açarları əhatə edir.

Push çatdırılmasında payload-ın rolu

Server HTTP/2 API APNS vasitəsilə push bildirişi göndərdikdə, sorğu avtorizasiya başlıqları və JSON gövdəsi — payload ehtiva edir. APNS yoxlayır payload-ın düzgünlüyünü: JSON səhvdirsə və ya ölçü limitini aşarsa, Apple serveri 400 Bad Request xətası qaytarır. Validasiyadan sonra APNS payload-ı cihaza çatdırır, burada iOS sistemi onu pars edir və bildirişi necə emal edəcəyini müəyyənləşdirir — banner göstərmək, fon tapşırığını işə salmaq və ya səs çalmaq.

Payload formatının təkamülü

APNS payload formatı iOS 2-də sadə mətn payload-dan müasir versiyalarda çoxkomponentli JSON strukturuna qədər təkamül etmişdir. iOS 10 mutable-content vasitəsilə media əlavələri dəstəyini gətirdi, iOS 12 thread-id ilə bildiriş qruplaşdırılmasını əlavə etdi, iOS 15 isə Live Activities üçün supports-live-activities-i təqdim etdi. Bu gün payload bildirişin tələb olunan davranışından asılı olaraq 15-ə qədər fərqli açar ehtiva edə bilər.

APNS-payload strukturu: məcburi və isteğe bağlı açarlar

Kök obyekt payload aps lüğətini və yuxarı səviyyədə isteğe bağlı xüsusi sahələri ehtiva edir. aps lüğəti yeganə məcburi elementdir, lakin onun daxilində bildiriş növündən asılı olaraq müxtəlif açar kombinasiyaları ola bilər: alert, badge, sound, content-available, mutable-content, interruption-level və başqaları.

Alert açarı: sətir və lüğət formatı

Alert açarı sadə sətir (bildirişin gövdəsinə çevrilir) və ya title, subtitle, body sahələri olan lüğət ola bilər. Lüğət formatı başlıq və alt başlığı əsas mətndən ayrıca təyin etməyə imkan verir. Lokallaşdırılmış bildirişlər üçün tətbiqin Localizable.strings faylına istinad edən title-loc-key, title-loc-args, loc-key, loc-args açarları istifadə olunur. Bu, müəyyən dildə mətn olmadan payload göndərməyə imkan verir — tətbiq tərcüməni özü əlavə edir.

Kəsilmələrin idarə edilməsi: interruption-level və relevance-score

iOS 15-dən başlayaraq Apple Focus Mode mexanizmini əlavə etdi ki, bu da proqramçıdan bildirişin kəsmə səviyyəsini göstərməyi tələb edir. interruption-level aşağıdakı dəyərləri qəbul edir: passive (səssiz, ekranı oyatmadan), active (standart davranış), time-sensitive (fokusu yarır, xüsusi icazə tələb edir) və critical (tibbi/fövqəladə hallar). relevance-score (0–1) açarı Focus sisteminə bir kateqoriya daxilində bildirişləri sıralamağa kömək edir.

thread-id vasitəsilə bildirişlərin qruplaşdırılması

thread-id açarı bildirişləri Notification Center-də qruplara birləşdirir. Bütün bildirişlər eyni thread-id ilə bir qrup kimi göstərilir, istifadəçi onu genişləndirə bilər. Bu, xüsusilə mesajlaşma tətbiqləri üçün faydalıdır, burada bir kontaktın mesajları birlikdə qruplaşdırılır və ya eyni tipli çoxlu bildiriş göndərən tətbiqlər üçün.

Xüsusi sahələr və məlumat ötürülməsi

Xüsusi sahələr — proqramçının cihaza əlavə məlumat ötürmək üçün aps lüğətindən kənarda əlavə etdiyi istənilən açarlardır. Server onları payload-ın kök JSON obyektinə daxil edir və tətbiq onları UNNotificationContent-də userInfo vasitəsilə əldə edir. Xüsusi sahələr pars zamanı konfliktlərin qarşısını almaq üçün aps-dan açar adlarını təkrarlamamalıdır.

Xüsusi məlumatlara məhdudiyyətlər

Əsas məhdudiyyət — payload-ın ümumi ölçüsü 4096 baytı keçməməlidir. Xüsusi sahələr bu limit üçün məcburi aps açarları ilə rəqabət aparır, buna görə də ötürülən məlumatların ölçüsünü minimuma endirmək vacibdir. Qısa açar adlarından istifadə edin (məsələn, “uid” əvəzinə “user-id”), böyük JSON strukturlarından qaçının və tam məlumat obyektləri əvəzinə yalnız identifikatorları ötürün.

Xüsusi sahələrin təhlükəsizliyi və validasiyası

Xüsusi sahələr serverdən gəlir və yoxlanılmadan etibar edilməməlidir. Həmişə validasiya edin pars zamanı xüsusi sahələrin tiplərini və dəyərlərini: açarın mövcudluğunu optional binding ilə yoxlayın, gözlənilən tipə as? String/Int/Dictionary ilə çevirin və dəyərin olmaması halını idarə edin. Payload məlumatları üçün heç vaxt force unwrap (!) istifadə etməyin — server səhv məlumat göndərə bilər və tətbiq crash olacaq.

{
    "aps": {
        "alert": {
            "title": "Yeni mesaj",
            "body": "Salam! Necəsən?"
        },
        "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"
}

Xüsusi sahələrin adlandırılması üçün tövsiyələr

Layihənin bütün payloadlarında vahid adlandırma üslubundan istifadə edin. kebab-case (message-type) və ya camelCase (messageType) — hər iki yanaşma məqbuldur, lakin layihə çərçivəsində birinə riayət etmək vacibdir. Uzun adlardan qaçının: “uid” əvəzinə “user-identifier”, “img” əvəzinə “profile-image-url”. Açar adındakı hər bir simvol 4096 limitindən bir baytdır.

Müxtəlif bildiriş növləri üçün payload nümunələri

Müxtəlif ssenarilər push bildirişləri payloadda müxtəlif açar kombinasiyaları tələb edir. Bir neçə tipik nümunəyə baxaq: sadə mətn bildirişi, lokallaşdırma ilə bildiriş, Silent Push və media əlavəsi ilə Rich Notification.

Sadə mətn bildirişi

Mətn və səs ilə əsas payload — istifadəçiyə bildiriş göstərmək üçün minimum konfiqurasiya. Sətir kimi alert qısa mesaj verir, sound default standart sistem səsini çaldırır. Badge isteğe bağlıdır və ikonada sayğac təyin edir. category və thread-id qruplaşdırma və interaktivlik üçün əlavə edilir.

{
    "aps": {
        "alert": "Xatırlatma: görüş 15 dəqiqəyə",
        "badge": 3,
        "sound": "default"
    }
}

Lokallaşdırma ilə bildiriş

Fərqli dilləri olan cihazlara göndərmək üçün sərt mətn əvəzinə lokallaşdırma açarlarından istifadə edin. title-loc-key tətbiqin Localizable.strings faylındakı açarına istinad edir, title-loc-args isə arqumentləri əvəz edir. Bu, bütün cihazlara bir payload göndərməyə imkan verir və tətbiq mətni lazımi dildə göstərir.

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

Fon sinxronizasiyası ilə Silent Push

Bildiriş göstərmədən fon sinxronizasiyası üçün content-available: 1 və alert olmaması istifadə olunur. Xüsusi sahələr əməliyyat növünü və emal üçün məlumatları göstərir. Sistem tətbiqi fonda aktivləşdirir, didReceiveRemoteNotification-u fetchCompletionHandler ilə çağırır və tətbiq sinxronizasiyanı yerinə yetirir.

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

Şəkil ilə Rich Notification

Media əlavəsinin göstərilməsi üçün Service Extension-i aktivləşdirmək üçün mutable-content: 1 və xüsusi sahədə şəkil URL-i tələb olunur. mutable-content: 1 sistemə UNNotificationServiceExtension-i işə salmağı bildirir, o URL-dən şəkli yükləyir və UNNotificationAttachment kimi əlavə edir. category fəaliyyət düymələrini göstərmək üçün qeydiyyatdan keçmiş kateqoriyanı göstərir.

{
    "aps": {
        "alert": {
            "title": "Yeni məhsul",
            "body": "Yeni kolleksiyaya baxın"
        },
        "category": "product",
        "mutable-content": 1
    },
    "media-url": "https://cdn.example.com/product.jpg"
}

Tətbiqdə payload-ın işlənməsi və pars edilməsi

UNNotificationContent.userInfo sistem tərəfindən emal edildikdən sonra alınan payload-ın tam lüğətini ehtiva edir. Tətbiq payload-a UNUserNotificationCenter delegatında bildiriş qəbul edərkən (ön planda), bildirişə klik edərkən, həmçinin Service Extension və Content Extension-də daxil olur. Xüsusi məlumatları çıxarmaq və sonrakı hərəkətləri müəyyənləşdirmək üçün düzgün pars etmə məcburidir.

Bildirişə klik edərkən AppDelegate-də pars etmə

İstifadəçi bildirişi kliklədikdə, sistem UNUserNotificationCenterDelegate-də didReceive response metodunu çağırır. response.notification.request.content.userInfo daxilində tam payload var. Proqramçı xüsusi sahələri çıxarır, hərəkət növünü müəyyənləşdirir (məsələn, çatı açmaq, məhsula keçmək) və tətbiqdə müvafiq naviqasiyanı çağırır.

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-də payload-ın validasiyası

Service Extension bildiriş göstərilməzdən əvvəl payload-ı alır və onu dəyişdirə bilər. Payload-ın validasiyası didReceive-də ilk addımdır: məcburi xüsusi sahələrin mövcudluğunu, əlavələr üçün URL-in düzgünlüyünü və məlumat tipini yoxlayın. Payload etibarsızdırsa, dərhal completion handler-i orijinal məzmunla çağırın, faydasız emala vaxt itirməyin.

Payload-ların loglanması və monitorinqi

İstehsalda push bildirişlərinin sazlanması üçün payload-ların strukturlaşdırılmış loglanmasından istifadə edin. OSLog payload-“notifications” kateqoriyası və debug səviyyəsi ilə loglamağa imkan verir. Server tərəfdə APNS cavablarını izləyin: uğurlu cavab göndərilən payload ilə uyğunlaşdırmaq üçün apns-id ehtiva edir, 400 xətası isə səhv JSON və ya ölçü aşılmasını göstərir.