Notification Payload — nedir, JSON yapısı ve ayrıştırma

Notification Payload Nedir

Notification Payload, sunucunun APNS’ye (Apple Push Notification Service) bir iOS cihazına teslim edilmek üzere gönderdiği JSON nesnesidir. Payload, sistemin bildirimi görüntülemek için ihtiyaç duyduğu tüm verileri içerir: başlık, metin, ses, rozet ve arka plan işleme için meta veriler. Payload yapısı Apple tarafından sıkı bir şekilde düzenlenir ve sistem tarafından doğru işlenmesi için zorunlu anahtarlar içerir.

Payload’ın Push Teslimatındaki Rolü

Sunucu, APNS HTTP/2 API aracılığıyla bir push bildirimi gönderdiğinde, istek yetkilendirme başlıkları ve bir JSON gövdesi — payload içerir. APNS, payload’ı doğrular: JSON geçersizse veya boyut sınırını aşarsa, Apple sunucusu 400 Bad Request hatası döndürür. Doğrulamadan sonra APNS, payload’ı cihaza teslim eder, iOS bunu ayrıştırır ve bildirimin nasıl işleneceğini belirler — bir banner gösterme, arka plan görevi çalıştırma veya ses çalma.

Payload Formatının Evrimi

APNS payload formatı, iOS 2’deki basit metin payload’ından modern sürümlerde çok bileşenli JSON yapısına evrilmiştir. iOS 10, mutable-content aracılığıyla medya ekleri desteğini getirdi, iOS 12 thread-id ile bildirim gruplamayı ekledi ve iOS 15, Live Activities için supports-live-activities’i tanıttı. Günümüzde bir payload, istenen bildirim davranışına bağlı olarak 15 farklı anahtar içerebilir.

APNS Payload Yapısı: Zorunlu ve İsteğe Bağlı Anahtarlar

Kök nesne, bir aps sözlüğü ve üst düzeyde isteğe bağlı özel alanlar içerir. aps sözlüğü tek zorunlu öğedir, ancak içinde bildirim türüne bağlı olarak çeşitli anahtar kombinasyonları bulunabilir: alert, badge, sound, content-available, mutable-content, interruption-level ve diğerleri.

alert Anahtarı: String ve Dictionary Formatı

alert anahtarı, basit bir dize (bildirim gövdesi haline gelir) veya title, subtitle ve body alanlarına sahip bir sözlük olabilir. Sözlük formatı, başlık ve alt başlığı ana metinden ayrı olarak ayarlamaya olanak tanır. Yerelleştirilmiş bildirimler için, uygulamanın Localizable.strings dosyasına başvuran title-loc-key, title-loc-args, loc-key ve loc-args anahtarları kullanılır. Bu, belirli bir dilde metin olmadan payload göndermeye olanak tanır — uygulama çeviriyi değiştirir.

Kesinti Yönetimi: interruption-level ve relevance-score

iOS 15’ten itibaren Apple, geliştiricinin bildirimin kesinti düzeyini belirtmesini gerektiren Focus Mode mekanizmasını tanıttı. interruption-level şu değerleri alır: passive (ses yok, ekran uyandırma yok), active (standart davranış), time-sensitive (Focus’u deler, özel yetki gerektirir) ve critical (tıbbi/acil durumlar). relevance-score (0–1) anahtarı, Focus sisteminin aynı kategorideki bildirimleri sıralamasına yardımcı olur.

thread-id ile Bildirim Gruplama

thread-id anahtarı, Bildirim Merkezi’nde bildirimleri gruplar. Aynı thread-id’ye sahip tüm bildirimler, kullanıcının genişletebileceği tek bir grup olarak görüntülenir. Bu, özellikle bir kişiden gelen mesajların bir arada gruplandığı mesajlaşma uygulamaları veya aynı türden birçok bildirim gönderen uygulamalar için kullanışlıdır.

Özel Alanlar ve Veri Aktarımı

Özel alanlar, geliştiricinin cihaza ek veri iletmek için aps sözlüğünün dışına eklediği anahtarlardır. Sunucu bunları payload’ın kök JSON nesnesine dahil eder ve uygulama bunları UNNotificationContent içindeki userInfo aracılığıyla alır. Özel alanlar, ayrıştırma sırasında çakışmaları önlemek için aps anahtar adlarını kopyalamamalıdır.

Özel Veri Sınırlamaları

Ana sınırlama, toplam payload boyutunun 4096 baytı aşmaması gerektiğidir. Özel alanlar bu sınır için zorunlu aps anahtarlarıyla rekabet eder, bu nedenle iletilen verinin boyutunu en aza indirmek önemlidir. Kısa anahtar adları kullanın (örneğin, “uid” yerine “user-id” yerine), büyük JSON yapılarından kaçının ve tam veri nesneleri yerine yalnızca tanımlayıcıları iletin.

Özel Alanların Güvenliği ve Doğrulanması

Özel alanlar sunucudan gelir ve doğrulama yapılmadan güvenilmemelidir. Ayrıştırma sırasında her zaman özel alanların türlerini ve değerlerini doğrulayın: isteğe bağlı bağlama ile anahtar varlığını kontrol edin, as? String/Int/Dictionary ile beklenen türe dönüştürün ve değer yokluğu durumunu ele alın. Payload’dan gelen veriler için asla force unwrap (!) kullanmayın — sunucu geçersiz veri gönderebilir ve uygulama çökebilir.

{
    "aps": {
        "alert": {
            "title": "Yeni mesaj",
            "body": "Merhaba! Nasılsı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"
}

Özel Alan Adlandırma Önerileri

Projedeki tüm payload’larda özel alanlar için tutarlı bir adlandırma stili kullanın. kebab-case (message-type) veya camelCase (messageType) — her iki yaklaşım da kabul edilebilir, ancak proje içinde tutarlılık önemlidir. Uzun adlardan kaçının: “uid” yerine “user-identifier” yerine, “img” yerine “profile-image-url” yerine. Anahtar adındaki her karakter, 4096 sınırının bir baytını tüketir.

Farklı Bildirim Türleri İçin Payload Örnekleri

Farklı senaryolardaki push bildirimleri, payload’da farklı anahtar kombinasyonları gerektirir. Birkaç tipik örneği inceleyelim: basit metin bildirimi, yerelleştirilmiş bildirim, Sessiz Push ve medya ekiyle Zengin Bildirim.

Basit Metin Bildirimi

Metin ve ses içeren temel bir payload — kullanıcıya bir bildirim görüntülemek için minimum yapılandırma. Dize olarak Alert kısa bir mesaj sağlar, sound default varsayılan sistem sesini çalar. Badge isteğe bağlıdır ve uygulama simgesindeki sayacı ayarlar. category ve thread-id gruplama ve etkileşim için eklenir.

{
    "aps": {
        "alert": "Hatırlatıcı: 15 dakika içinde toplantı",
        "badge": 3,
        "sound": "default"
    }
}

Yerelleştirilmiş Bildirim

Farklı dillerdeki cihazlara bildirim göndermek için, sabit kodlanmış metin yerine yerelleştirme anahtarlarını kullanın. title-loc-key, uygulamanın Localizable.strings dosyasındaki bir anahtara başvurur ve title-loc-args argümanları sağlar. Bu, tüm cihazlara tek bir payload göndermeye olanak tanır ve uygulama metni uygun dilde görüntüler.

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

Arka Plan Senkronizasyonlu Sessiz Push

Bildirim göstermeden arka plan senkronizasyonu için, alert olmadan content-available: 1 kullanın. Özel alanlar, işlem türünü ve işlenecek verileri belirtir. Sistem, uygulamayı arka planda etkinleştirir, fetchCompletionHandler ile didReceiveRemoteNotification’ı çağırır ve uygulama senkronizasyonu gerçekleştirir.

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

Görselli Zengin Bildirim

Bir medya eki görüntülemek için, Service Extension’ı etkinleştirmek üzere mutable-content: 1 ve özel bir alanda bir görsel URL’si gereklidir. mutable-content: 1, sisteme UNNotificationServiceExtension’ı başlatması için sinyal gönderir, URL’den görseli indirir ve UNNotificationAttachment olarak ekler. category anahtarı, eylem düğmelerini görüntülemek için kayıtlı bir kategori belirtir.

{
    "aps": {
        "alert": {
            "title": "Yeni ürün",
            "body": "Yeni koleksiyona göz atın"
        },
        "category": "product",
        "mutable-content": 1
    },
    "media-url": "https://cdn.example.com/product.jpg"
}

Uygulamada Payload İşleme ve Ayrıştırma

UNNotificationContent.userInfo, sistem işlemesinden sonra alınan payload’ın tam sözlüğünü içerir. Uygulama, bir bildirim alındığında (ön planda), bir bildirime dokunulduğunda ve ayrıca Service Extension ve Content Extension’da UNUserNotificationCenter temsilcisinde payload’a erişir. Özel verileri çıkarmak ve sonraki eylemleri belirlemek için doğru ayrıştırma şarttır.

Bildirime Dokunulduğunda AppDelegate’te Ayrıştırma

Kullanıcı bir bildirime dokunduğunda, sistem UNUserNotificationCenterDelegate’te didReceive response yöntemini çağırır. response.notification.request.content.userInfo tam payload’ı içerir. Geliştirici özel alanları çıkarır, eylem türünü belirler (örneğin, bir sohbet açma, bir ürüne gitme) ve uygulamada ilgili navigasyonu tetikler.

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 Doğrulaması

Service Extension, bildirim görüntülenmeden önce payload’ı alır ve değiştirebilir. Payload doğrulaması, didReceive’daki ilk adımdır: zorunlu özel alanları kontrol edin, ek URL’sini doğrulayın ve veri türlerini kontrol edin. Payload geçersizse, gereksiz işleme zaman harcamamak için hemen orijinal içerikle completion handler’ı çağırın.

Payload Günlükleme ve İzleme

Üretimde push bildirimlerinde hata ayıklamak için, yapılandırılmış payload günlükleme kullanın. OSLog, debug düzeyinde “notifications” kategorisiyle payload’ı günlüklemeye olanak tanır. Sunucu tarafında APNS yanıtlarını izleyin: başarılı bir yanıt, gönderilen payload ile eşleştirme için apns-id içerirken, 400 hatası geçersiz JSON veya boyut aşımını belirtir.