Notification Payload — apa itu, struktur JSON dan parsing

Apa itu Notification Payload

Notification Payload (payload notifikasi) — adalah objek JSON yang dikirim server ke APNS (Apple Push Notification Service) untuk dikirimkan ke perangkat iOS. Payload berisi semua data yang diperlukan sistem untuk menampilkan notifikasi: judul, teks, suara, badge, dan metadata untuk pemrosesan latar belakang. Struktur payload diatur secara ketat oleh Apple dan mencakup kunci wajib untuk pemrosesan yang benar oleh sistem.

Peran payload dalam pengiriman push

Ketika server mengirim notifikasi push melalui HTTP/2 API APNS, permintaan berisi header otorisasi dan badan JSON — payload. APNS memeriksa validitas payload: jika JSON tidak valid atau melebihi batas ukuran, server Apple mengembalikan kesalahan 400 Bad Request. Setelah validasi, APNS mengirimkan payload ke perangkat, di mana sistem iOS mem-parsing-nya dan menentukan cara memproses notifikasi — menampilkan banner, menjalankan tugas latar belakang, atau memutar suara.

Evolusi format payload

Format payload APNS telah berevolusi dari payload teks sederhana di iOS 2 menjadi struktur JSON multi-komponen di versi modern. iOS 10 membawa dukungan untuk lampiran media melalui mutable-content, iOS 12 menambahkan pengelompokan notifikasi melalui thread-id, dan iOS 15 memperkenalkan supports-live-activities untuk Live Activities. Saat ini, payload dapat berisi hingga 15 kunci berbeda tergantung pada perilaku notifikasi yang diinginkan.

Struktur payload APNS: kunci wajib dan opsional

Objek akar payload berisi kamus aps dan bidang kustom opsional di tingkat atas. Kamus aps adalah satu-satunya elemen wajib, tetapi di dalamnya dapat terdapat berbagai kombinasi kunci tergantung pada jenis notifikasi: alert, badge, sound, content-available, mutable-content, interruption-level dan lainnya.

Kunci alert: format string dan kamus

Kunci alert dapat berupa string sederhana (yang menjadi badan notifikasi) atau kamus dengan bidang title, subtitle, body. Format kamus memungkinkan pengaturan judul dan subjudul terpisah dari teks utama. Untuk notifikasi yang dilokalkan, digunakan kunci title-loc-key, title-loc-args, loc-key, loc-args yang merujuk ke Localizable.strings aplikasi. Ini memungkinkan pengiriman payload tanpa teks dalam bahasa tertentu — aplikasi mengganti terjemahan.

Manajemen interupsi: interruption-level dan relevance-score

Mulai dari iOS 15, Apple menambahkan mekanisme Focus Mode yang mengharuskan pengembang menentukan tingkat interupsi notifikasi. interruption-level menerima nilai: passive (tanpa suara, tanpa membangunkan layar), active (perilaku standar), time-sensitive (menembus fokus, memerlukan special entitlement) dan critical (situasi medis/darurat). Kunci relevance-score (0–1) membantu sistem Focus memberi peringkat notifikasi dalam satu kategori.

Pengelompokan notifikasi melalui thread-id

Kunci thread-id menggabungkan notifikasi ke dalam grup di Notification Center. Semua notifikasi dengan thread-id yang sama ditampilkan sebagai satu grup yang dapat diperluas oleh pengguna. Ini sangat berguna untuk aplikasi pesan, di mana pesan dari satu kontak dikelompokkan bersama, atau untuk aplikasi yang mengirim banyak notifikasi dengan jenis yang sama.

Bidang kustom dan transmisi data

Bidang kustom — adalah kunci apa pun di luar kamus aps yang ditambahkan pengembang untuk mengirim data tambahan ke perangkat. Server memasukkannya ke dalam objek JSON akar payload, dan aplikasi menerimanya melalui userInfo di UNNotificationContent. Bidang kustom tidak boleh menduplikasi nama kunci dari aps untuk menghindari konflik saat parsing.

Batasan data kustom

Batasan utama — ukuran total payload tidak boleh melebihi 4096 byte. Bidang kustom bersaing untuk batas ini dengan kunci aps wajib, oleh karena itu penting untuk meminimalkan ukuran data yang dikirim. Gunakan nama kunci pendek (mis. uid bukan user-id), hindari struktur JSON besar dan kirim hanya pengidentifikasi, bukan objek data lengkap.

Keamanan dan validasi bidang kustom

Bidang kustom berasal dari server dan tidak boleh dipercaya tanpa verifikasi. Selalu validasi tipe dan nilai bidang kustom saat parsing: periksa keberadaan kunci melalui optional binding, konversikan ke tipe yang diharapkan dengan as? String/Int/Dictionary dan tangani kasus tidak adanya nilai. Jangan pernah menggunakan force unwrap (!) untuk data dari payload — server dapat mengirim data yang salah dan aplikasi akan crash.

{
    "aps": {
        "alert": {
            "title": "Pesan baru",
            "body": "Halo! Apa kabar?"
        },
        "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"
}

Rekomendasi penamaan bidang kustom

Gunakan gaya penamaan seragam untuk bidang kustom di semua payload proyek. kebab-case (message-type) atau camelCase (messageType) — kedua pendekatan dapat diterima, tetapi penting untuk konsisten dalam proyek. Hindari nama panjang: uid bukan user-identifier, img bukan profile-image-url. Setiap karakter dalam nama kunci adalah satu byte dari batas 4096.

Contoh payload untuk berbagai jenis notifikasi

Skenario berbeda notifikasi push memerlukan kombinasi kunci yang berbeda dalam payload. Mari kita lihat beberapa contoh tipikal: notifikasi teks sederhana, notifikasi dengan lokalisasi, Silent Push dan Rich Notification dengan lampiran media.

Notifikasi teks sederhana

Payload dasar dengan teks dan suara — konfigurasi minimal untuk menampilkan notifikasi kepada pengguna. Alert sebagai string memberikan pesan pendek, sound default memutar suara sistem standar. Badge opsional dan mengatur penghitung pada ikon. category dan thread-id ditambahkan untuk pengelompokan dan interaktivitas.

{
    "aps": {
        "alert": "Pengingat: pertemuan dalam 15 menit",
        "badge": 3,
        "sound": "default"
    }
}

Notifikasi dengan lokalisasi

Untuk mengirim ke perangkat dengan bahasa berbeda, gunakan kunci lokalisasi alih-alih teks tetap. title-loc-key merujuk ke kunci di Localizable.strings aplikasi, dan title-loc-args mengganti argumen. Ini memungkinkan pengiriman satu payload ke semua perangkat, dan aplikasi menampilkan teks dalam bahasa yang sesuai.

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

Silent Push dengan sinkronisasi latar belakang

Untuk sinkronisasi latar belakang tanpa menampilkan notifikasi, digunakan content-available: 1 dan tanpa alert. Bidang kustom menunjukkan jenis operasi dan data untuk diproses. Sistem mengaktifkan aplikasi di latar belakang, memanggil didReceiveRemoteNotification dengan fetchCompletionHandler, dan aplikasi melakukan sinkronisasi.

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

Rich Notification dengan gambar

Untuk menampilkan lampiran media, diperlukan mutable-content: 1 untuk mengaktifkan Service Extension dan URL gambar di bidang kustom. mutable-content: 1 memberi sinyal pada sistem untuk menjalankan UNNotificationServiceExtension, yang akan mengunduh gambar dari URL dan menambahkannya sebagai UNNotificationAttachment. category menunjuk ke kategori terdaftar untuk menampilkan tombol tindakan.

{
    "aps": {
        "alert": {
            "title": "Produk baru",
            "body": "Lihat koleksi baru"
        },
        "category": "product",
        "mutable-content": 1
    },
    "media-url": "https://cdn.example.com/product.jpg"
}

Pemrosesan dan parsing payload di aplikasi

UNNotificationContent.userInfo berisi kamus lengkap payload yang diterima setelah diproses oleh sistem. Aplikasi mengakses payload di delegat UNUserNotificationCenter saat menerima notifikasi (di latar depan), saat mengetuk notifikasi, serta di Service Extension dan Content Extension. Parsing yang benar wajib dilakukan untuk mengekstrak data kustom dan menentukan tindakan selanjutnya.

Parsing di AppDelegate saat mengetuk notifikasi

Ketika pengguna mengetuk notifikasi, sistem memanggil metode didReceive response di UNUserNotificationCenterDelegate. Di response.notification.request.content.userInfo terdapat payload lengkap. Pengembang mengekstrak bidang kustom, menentukan jenis tindakan (misalnya, membuka chat, pergi ke produk) dan memanggil navigasi yang sesuai di aplikasi.

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()
}

Validasi payload di Service Extension

Service Extension menerima payload sebelum notifikasi ditampilkan dan dapat memodifikasinya. Validasi payload — langkah pertama di didReceive: periksa keberadaan bidang kustom wajib, kebenaran URL untuk lampiran, dan tipe data. Jika payload tidak valid, segera panggil completion handler dengan konten asli, jangan buang waktu untuk pemrosesan yang sia-sia.

Logging dan monitoring payload

Untuk debugging notifikasi push di produksi, gunakan logging terstruktur dari payload. OSLog memungkinkan logging payload dengan kategori notifications dan level debug. Di sisi server, lacak respons APNS: respons sukses berisi apns-id untuk dicocokkan dengan payload yang dikirim, dan kesalahan 400 menunjukkan JSON tidak valid atau kelebihan ukuran.